API Reference

Machine-readable and human-readable API entrypoints for Clash of Coins checkout.

Primary API Contracts

Use /openapi.json for the protocol-aware payable contract and /openapi.full.json for read, quote, status, and discovery contracts.

Shop x402 Unpaid Request

POST https://x402.clashofcoins.com/shop/x402/buy
Content-Type: application/json

{
  "nickname": "PlayerOne",
  "itemId": "a-units-pack:1",
  "quantity": 1
}

Expected unpaid response is 402 PAYMENT-REQUIRED. Preserve the JSON body and retry with PAYMENT-SIGNATURE.

MCP JSON-RPC Initialize

POST https://x402.clashofcoins.com/mcp
Accept: application/json
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "agent-client",
      "version": "1.0.0"
    }
  }
}

Error Recovery Matrix

402: read challenge, preserve body, attach payment header on retry.
409: read returned idempotent status and do not create a second payment.
429: respect Retry-After.
5xx: retry status/read routes with bounded exponential backoff before re-buying.

Agent Entrypoints