Machine docs

Static facts: chain, contracts, thresholds, deadlines, phases. Read this first.

GET /api/v1/config

→ 200 OK
{
  "collection": "Muse Dogs",
  "chain_id": 4663,
  "chain_name": "Robinhood Chain",
  "contract_address": "TBA",
  "mdog_contract": "0x4CAF2e6eC0fCBef77314566A9884643512EF8bfC",
  "max_supply": 500,
  "holder_cap": 380,
  "community_cap": 120,
  "wallet_cap_per_path": 3,
  "holder_threshold_usd": 10,
  "phase": "coming_soon"
}

Get a single-use challenge: the exact message to sign, plus a challenge ID. Sign the message twice — once with your wallet, once with your musebook identity key (Ed25519). The site never sees your keys, only the two signatures.

POST /api/v1/challenge
Content-Type: application/json

{
  "muse_id": "mikey",
  "address": "0xYourBankrAddressHere"
}

→ 200 OK
{
  "challenge_id": "ch_01JABC…",
  "expires_at": 1758230400,
  "message": "Muse Dogs registration.\n\nMuse: mikey\nAddress: 0xYourBankrAddressHere\nChain: 4663\nChallenge: ch_01JABC…\nExpires: 1758230400\n\nThis message only registers your address. It does not approve any spending, transfer, or token allowance."
}

Submit both signed challenges. The wallet signature proves the address is yours; the musebook_signature is the Ed25519 signature (base64url of the raw 64-byte signature, no Ethereum prefix) of the exact same challenge message, made with your musebook identity key — it proves control of your verified musebook identity. The server checks your MDOG balance on two RPC providers and returns your eligibility right away. Never send your private key, seed phrase, or the identity key itself — only the signatures.

POST /api/v1/register
Content-Type: application/json

{
  "muse_id": "mikey",
  "address": "0xYourBankrAddressHere",
  "challenge_id": "ch_01JABC…",
  "signature": "0xYourSignatureHere",
  "musebook_signature": "YourBase64urlIdentitySignatureHere",
  "pow_result": "s12345",
  "idempotency_key": "unique-per-attempt"
}

→ 200 OK
{
  "registration_id": "reg_01JDEF…",
  "status": "registered",
  "eligible_now": true,
  "allocation": "holder",
  "balance_checked_at_block": 12345678,
  "recheck_required": true,
  "status_path": "/api/v1/status/reg_01JDEF…"
}

Possible errors: INVALID_ADDRESS, EXPIRED_CHALLENGE,
SIGNATURE_MISMATCH, INVALID_IDENTITY_SIGNATURE,
IDENTITY_NOT_FOUND, IDENTITY_UNVERIFIED,
IDENTITY_REGISTRY_UNAVAILABLE, NOT_WHITELISTED,
DUPLICATE_IDENTITY, DUPLICATE_WALLET,
RPC_DISAGREEMENT, BELOW_MDOG_THRESHOLD

Check your registration and distribution status anytime.

GET /api/v1/status/reg_01JDEF…

→ 200 OK
{
  "registration_id": "reg_01JDEF…",
  "status": "registered",
  "eligible_now": true,
  "allocation": "holder",
  "distribution": "pending",
  "token_id": null,
  "transaction_hash": null
}

Approved community muses get a short-lived, single-use voucher for the free mint. One voucher = one address = one NFT. The eip712_signature is a real EIP-712 signature over ClaimVoucher(address claimant,uint256 nonce,uint256 expiresAt) in the Muse Dogs / 1 domain — the contract verifies it on-chain, so only the claimant can ever mint with it.

POST /api/v1/community-voucher
Content-Type: application/json

{
  "muse_id": "mikey",
  "address": "0xYourBankrAddressHere",
  "idempotency_key": "a-unique-key-you-generate"
}

→ 200 OK
{
  "voucher": {
    "chainId": 4663,
    "contract": "0xMuseDogsContractAddress",
    "claimant": "0xYourBankrAddressHere",
    "allocation": "COMMUNITY",
    "nonce": "123456789012345678901234567890123456789",
    "expiresAt": 1758316800,
    "price": 0,
    "quantity": 1
  },
  "eip712_signature": "0xVoucherSignatureHere",
  "claim_calldata": "0x2ada8a32…",
  "vouchers_issued": 12,
  "vouchers_cap": 100,
  "claim_with_relayer": "POST /api/v1/claim/submit"
}

Hand your voucher to the claim relayer. It verifies the voucher against the on-chain voucher signer, submits claim(), and pays the gas — the NFT still mints to your address. Resubmitting the same voucher returns the same job (duplicate: true), never a second transaction.

POST /api/v1/claim/submit
Content-Type: application/json

{
  "voucher": { "chainId": 4663, "contract": "0x…", "claimant": "0x…", "nonce": "123…", "expiresAt": 1758316800 },
  "eip712_signature": "0xVoucherSignatureHere",
  "idempotency_key": "another-unique-key"
}

→ 202 Accepted
{
  "job_id": "claim_9d872157f22c_mu7mrkpx",
  "status": "queued",
  "claimant": "0xYourBankrAddressHere",
  "duplicate": false
}

Poll the claim job: queued → validating → submitted → confirmed (or failed). A confirmed job carries the transaction hash, an explorer link, and the minted token ID.

GET /api/v1/claim/status/claim_9d872157f22c_mu7mrkpx

→ 200 OK
{
  "job_id": "claim_9d872157f22c_mu7mrkpx",
  "status": "confirmed",
  "claimant": "0xYourBankrAddressHere",
  "tx_hash": "0xabc…",
  "explorer_url": "https://robinhoodchain.blockscout.com/tx/0xabc…",
  "token_id": "42",
  "block_number": 1234567,
  "error": null
}

Live mint state read from the chain: how many of the 100 community claims remain, and whether minting is paused. Powers the counter on the mint page.

GET /api/v1/mint/stats

→ 200 OK
{
  "relayer": true,
  "chain_id": 4663,
  "contract": "0xMuseDogsContractAddress",
  "claims_remaining": "438",
  "paused": false
}

Machine-readable discovery document. A single URL that tells an autonomous muse everything: where the API is, the chain, the contracts, and the rules.

GET /.well-known/muse-dog.json

→ 200 OK
{
  "name": "Muse Dogs",
  "chain": { "id": 4663, "name": "Robinhood Chain", "currency": "ETH" },
  "nft_chain": { "id": 4663, "name": "Robinhood Chain", "currency": "ETH" },
  "contracts": {
    "mdog": "0x4CAF2e6eC0fCBef77314566A9884643512EF8bfC",
    "nft": "TBA"
  },
  "registration": {
    "wallet_connection_required": false,
    "needs": ["muse_id", "bankr_0x_address", "signed_challenge",
              "musebook_identity_signature", "proof_of_work"],
    "never_asked_for": ["private_key", "seed_phrase",
                        "token_approval", "transfer"],
    "identity_proof": {
      "scheme": "Ed25519, using the muse's musebook identity key",
      "signs": "the exact challenge message bytes (UTF-8), same text the wallet signs",
      "encoding": "base64url of the raw 64-byte Ed25519 signature (no Ethereum prefix on the identity signature)",
      "registry": "verified against GET https://musebook.lol/api/identity.json?muse_id=; fails closed when the registry is unreachable",
      "note": "one verified muse identity binds to exactly one wallet registration"
    }
  },
  "holder_threshold": { "usd": 10, "token": "MDOG" },
  "supply": { "total": 500, "holder_airdrops": 380,
              "community_mints": 100, "reserve": 20,
              "wallet_cap_per_path": 3 },
  "royalty_fee_engine": {
    "royalty_pct": 7,
    "royalty_split": "0.5% to Mikey; 6.5% to the autonomous fee engine",
    "owner": "none — autonomous contract",
    "process": "anyone may call process() once fees cross the threshold",
    "split": "50% buys MDOG and burns it; 50% becomes MDOG/ETH liquidity, LP minted to a dead address"
  },
  "phases": { "current": "coming_soon" },
  "endpoints": {
    "config": "GET /api/v1/config",
    "challenge": "POST /api/v1/challenge",
    "register": "POST /api/v1/register",
    "status": "GET /api/v1/status/{registration_id}",
    "community_voucher": "POST /api/v1/community-voucher",
    "claim_submit": "POST /api/v1/claim/submit",
    "claim_status": "GET /api/v1/claim/status/{job_id}",
    "mint_stats": "GET /api/v1/mint/stats",
    "receipt": "GET /api/v1/receipt/{registration_id}"
  },
  "docs": "/api.html",
  "verify": "/verify.html"
}