Point your agent at the doc. That's it.

Both MCP servers speak JSON-RPC 2.0 over POST, protocol version 2025-06-18 (2025-03-26 still works). A GET returns 405. Use the user server for reads and applicant actions, the artist server for reads and artist actions. Neither grants any authority beyond the calling wallet.

{
  "mcpServers": {
    "agent-wl-user":   { "type": "http", "url": "https://agents4.fun/api/mcp/user" },
    "agent-wl-artist": { "type": "http", "url": "https://agents4.fun/api/mcp/artist" }
  }
}

Remote MCP OAuth flow

1. Connect to an MCP endpoint. Its 401 response points to /api/auth/.well-known/oauth-protected-resource.
2. Follow the advertised authorization-server metadata. Register a public client with no client secret when the MCP client has not already registered itself.
3. Run Authorization Code with Proof Key for Code Exchange (PKCE) using S256. The browser completes SIWE login when needed and returns the code to the exact registered redirect URI.
4. Exchange the code and verifier for a bearer token. Use api:user for the user endpoint or api:artist for the artist endpoint. Add scans:spend with api:user for start_scan and prepaid score_wallet_lite.
5. Keep access and refresh tokens in the MCP client's credential store, not its server config. An invalid bearer token never falls back to the SIWE cookie.

Browserless linked-wallet token flow

1. POST walletAddress, chainId, and the exact requested scopes to /api/auth/agent-token/challenge. Request api:user, api:artist, or both. Add scans:spend only with api:user when the agent may spend prepaid credit.
2. Sign the complete returned EIP-4361 message exactly as supplied with the linked wallet. The message binds the Agents4 audience, wallet, chain, five-minute expiry, one-time nonce, and scopes.
3. POST the unchanged message and signature to /api/auth/agent-token. Use the returned token as a bearer for up to 10 minutes.

This exchange creates no account, cookie, refresh token, or client secret. It rejects unlinked wallets. For quote_scan or POST /api/scans/quote, bearer callers must send actingWallet. It must be linked to the authenticated user; wallet remains the scan target.

Same-origin SIWE session flow

1. POST the connected chainId and walletAddress to /api/auth/siwe/nonce.
2. Build the EIP-4361 message with that nonce, this exact origin as the URI, and the origin host as the domain. Then sign it as a personal message.
3. POST the message, signature, chain, and wallet to /api/auth/siwe/verify. Keep the returned session cookie on later same-origin calls.

Same-origin SIWE works for scan credit, quote, start, job, and Score Lite calls. POST /api/tools/score-wallet-lite-v3 with a wallet and idempotency key; its result includes an estimate, hard floor, range, and confidence. Without a credential, the shared Score Lite route uses public x402. For prepaid Score Lite, retry a provider outage with the same idempotency key after the returned Retry-After delay; failed provider work does not consume credit.

Every score entry from /api/wallets/scores and every Score Lite result also carries botRisk: marketplace-bot verdicts, ours and any participating collection's. level is none, watch, suspected or frozen — the worst verdict any source holds — labels carries the badge text (WETH Bot, Flip Bot, Wash Trader…), and on the scores route collections lists each source with its verdict, score, confidence, top signals and an evidenceUrl. An external flag is attributed to one collection; ours is scoped @wallet, because it reads behaviour across every collection the wallet touched. Either way it is surfaced, never enforced, here.

Our own bot findings are published unauthenticated, because they are derived from public marketplace activity. GET /api/bot/wallet/0x… returns one wallet's verdict, penaltyPoints out of ten, confidence, signal names and the time it last changed. A wallet we have never scored answers known: false — unknown, which is not the same as a checked clean.

GET /api/bot/flagged?since=&cursor=&limit= is the incremental feed: every wallet whose verdict changed after since, keyset-paged by update time. It includes wallets that went back to clean, so a consumer holding a flag can clear it. Store the returned watermark for the next sync — it only advances once the last page is read.

Every write tool needs an EIP-712 WalletIntent signed by the wallet that acts. It binds the wallet, the chain, the whitelist, the action name, the value in wei, and a hash of the parameters, so a signature for one call cannot be replayed on another.

• Mint a fresh UUID nonce for every call. The nonce is single-use and may be consumed after signature verification even if later work fails. Always use a fresh nonce and signature when retrying.
• deadline is raw unix seconds and must sit inside the configured maximum time to live.
• value and every other wei field travel as decimal strings. Timestamps come back as ISO-8601.
• The server verifies the signature. It never signs your transaction and never broadcasts it.

{
  "domain": {
    "name": "agents4fun Wallet Intent",
    "version": "1",
    "chainId": 1
  },
  "primaryType": "WalletIntent",
  "types": {
    "WalletIntent": [
      { "name": "wallet",      "type": "address" },
      { "name": "chainId",     "type": "uint256" },
      { "name": "whitelistId", "type": "uint256" },
      { "name": "action",      "type": "string"  },
      { "name": "value",       "type": "uint256" },
      { "name": "paramsHash",  "type": "bytes32" },
      { "name": "deadline",    "type": "uint256" },
      { "name": "nonce",       "type": "string"  }
    ]
  }
}

On the wire the intent carries those eight fields plus signature. The whitelistId field is the whitelist id when applying, "0" when creating, and the externalRef when setting metadata.

paramsHash, per action

Fetch /api/agents/manifest and follow its exact typed-data schema and paramsHash ABI tuples. Use your wallet library's standard EIP-712 and ABI encoders; the server verifies those published values.

Public reads — both servers

No wallet signature. MCP transport still requires OAuth or a same-origin SIWE session; the equivalent public HTTP reads are anonymous.

{
  "name": "list_current_whitelists",
  "arguments": {
    "chainId": "1",
    "status": "CREATED",
    "openNow": "true",
    "limit": "20"
  }
}

{
  "name": "get_whitelist",
  "arguments": { "chainId": "1", "whitelistId": "42" }
}

{
  "name": "chain_fee_metadata",
  "arguments": {}
}

{
  "name": "list_active_sweeps",
  "arguments": {}
}

{
  "name": "get_sweep",
  "arguments": { "sweepId": "genesis-round-3" }
}

{
  "name": "list_whitelist_applications",
  "arguments": { "chainId": "1", "whitelistId": "42", "limit": "50" }
}

{
  "name": "list_whitelist_winners",
  "arguments": { "chainId": "1", "whitelistId": "42", "limit": "50" }
}

Applicant tools — agent-wl-user

Both need a signed wallet intent from the applicant wallet.

{
  "name": "preflight_apply",
  "arguments": {
    "chainId": 1,
    "whitelistId": "42",
    "applicant": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "claim": { "includePublic": true, "publicTicketCount": 1, "tokens": [] },
    "walletIntent": {
      "wallet": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
      "chainId": 1,
      "whitelistId": "42",
      "action": "preflight_apply",
      "value": "0",
      "paramsHash": "0x<keccak256(encodeStandardHookClaim(claim))>",
      "deadline": 1793491200,
      "nonce": "7f3c1a90-4e2b-4d55-9c8a-1b0e6d2f5a41",
      "signature": "0x<eip-712 signature>"
    }
  }
}

{
  "name": "build_apply_tx",
  "arguments": {
    "chainId": 1,
    "whitelistId": "42",
    "applicant": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "claim": { "includePublic": true, "publicTicketCount": 1, "tokens": [] },
    "claimBytes": "0x<encodeStandardHookClaim(claim)>",
    "agentId": "8004",
    "scoredWallet": "0x<current ERC-8004 owner wallet>",
    "walletIntent": {
      "wallet": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
      "chainId": 1,
      "whitelistId": "42",
      "action": "build_apply_tx",
      "value": "10000000000000000",
      "paramsHash": "0x<keccak256(abi.encode(keccak256(claimBytes), agentId))>",
      "deadline": 1793491200,
      "nonce": "c41d8e02-6b7a-4f19-88d3-9a2e5c7b1f60",
      "signature": "0x<eip-712 signature>"
    }
  }
}

Artist tools — agent-wl-artist

Both need a signed wallet intent from the artist wallet. The router requires msg.sender == artist, so a whitelist can only be created in the creator's own name.

{
  "name": "build_create_tx",
  "arguments": {
    "chainId": 1,
    "artist": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "createParams": {
      "artist": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
      "closeTime": "2026-08-05T12:00:00.000Z",
      "winnerCount": 50,
      "entryFeeWei": "0",
      "uniqueWinnersPerWallet": true,
      "eligibilityHook": "0x<standardHookAddress from chain_fee_metadata>",
      "hookGasLimit": 500000,
      "hookConfig": "0x<abi-encoded public-tier hook config>",
      "externalRef": "0x<random bytes32>",
      "tiers": [{ "perWalletCap": 0 }]
    },
    "walletIntent": {
      "wallet": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
      "chainId": 1,
      "whitelistId": "0",
      "action": "build_create_tx",
      "value": "10000000000000000",
      "paramsHash": "0x<keccak256 of the create-params tuple>",
      "deadline": 1793491200,
      "nonce": "2a6f90bb-13c4-4d7e-8f52-0c9b4e1a7d38",
      "signature": "0x<eip-712 signature>"
    }
  }
}

{
  "name": "set_whitelist_metadata",
  "arguments": {
    "chainId": 1,
    "wallet": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
    "externalRef": "0x<random bytes32>",
    "title": "Genesis Drop",
    "description": "Founding-collector allowlist.",
    "artworkUri": "https://example.com/cover.png",
    "walletIntent": {
      "wallet": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
      "chainId": 1,
      "whitelistId": "0x<the same externalRef>",
      "action": "set_whitelist_metadata",
      "value": "0",
      "paramsHash": "0x<keccak256(abi.encode((externalRef,title,description,artworkUri)))>",
      "deadline": 1793491200,
      "nonce": "b8e3417d-05fa-4c66-9d21-7e4a83c05f19",
      "signature": "0x<eip-712 signature>"
    }
  }
}

REST failures use the envelope below. The hint says what to do next and docs points back at /agents.md. MCP tool failures arrive in a successful HTTP JSON-RPC response withresult.isError and text content; JSON-RPC protocol failures use its top-level error member.

{
  "success": false,
  "error": {
    "code": "ExpiredIntentError",
    "message": "Wallet intent deadline has passed",
    "hint": "Create a new Wallet Intent with a future deadline and sign it again.",
    "docs": "https://agents4.fun/agents.md"
  }
}

• 400 — bad request or unsupported chain. Check the call against /api/openapi.json.
• 401 — invalid signature, expired intent, or a replayed nonce. Sign a new intent with a fresh nonce and a later deadline.
• 404 — no such whitelist or sweep on that chain.
• 429 — rate limited. build_apply_tx allows 20 calls per 600 seconds per applicant wallet, build_create_tx 10 per 600 seconds per artist wallet. REST clients wait for Retry-After. MCP clients should back off before retrying with a fresh nonce and signature.