{"openapi":"3.1.0","info":{"title":"Block402","version":"0.1.0","contact":{"email":"hello@block402.xyz"},"description":"Blockchain intelligence for AI agents. Read-only blockchain data, paid per request with x402. Currently advertised chains: Bitcoin. Payments: USDC on Base mainnet (eip155:8453). The payment network is independent of the blockchain being queried.","x-guidance":"Generate and privately persist an Idempotency-Key before calling. Unsigned probes without a key are discovery-only, even with a valid body; POST a valid body and key for a bound quote before signing. Payments use eip155:8453. After uncertainty, recover with the same key without signing again. Guide: https://api.block402.xyz/docs/api.md"},"servers":[{"url":"https://api.block402.xyz"}],"paths":{"/rpc/bitcoin":{"post":{"operationId":"bitcoin_rpc","summary":"Bitcoin JSON-RPC","tags":["Bitcoin"],"security":[],"description":"POST method and positional params in a JSON-RPC 2.0 body. Unsigned probes are discovery-only. A valid body and private Idempotency-Key obtain the exact bound price. Schema examples are illustrative, not current chain state.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Private random 32-byte lowercase hex recovery key. Persist before payment and reuse only for retries of this same method and params. Never publish it."},"description":"Private random 32-byte lowercase hex recovery key. Persist before payment and reuse only for retries of this same method and params. Never publish it."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getblockcount"},"params":{"type":"array","minItems":0,"maxItems":0}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getbestblockhash"},"params":{"type":"array","minItems":0,"maxItems":0}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getblockhash"},"params":{"type":"array","minItems":1,"maxItems":1,"prefixItems":[{"type":"integer","minimum":0,"maximum":100000000}]}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getblockheader"},"params":{"type":"array","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},{"type":"boolean"}]}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getblock"},"params":{"type":"array","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},{"type":"number","enum":[0,1]}]}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"getrawtransaction"},"params":{"type":"array","minItems":3,"maxItems":3,"prefixItems":[{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},{"type":"boolean","const":false},{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}]}},"required":["jsonrpc","id","method","params"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string","const":"gettxout"},"params":{"type":"array","minItems":3,"maxItems":3,"prefixItems":[{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},{"type":"integer","minimum":0,"maximum":100000},{"type":"boolean","const":false}]}},"required":["jsonrpc","id","method","params"],"additionalProperties":false}]},"example":{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]}}}},"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"dynamic","currency":"USD","min":"0.002500","max":"0.005000"}},"x-block402-payment":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x5b5cE945b2Cda4446fC4899496A85dBBEd626c63","testnet":false},"x-block402-data-network":"bip122:000000000019d6689c085ae165831e93","x-block402-archive":true,"x-block402-history":"See method documentation.","x-block402-methods":{"getblockcount":{"tool":"bitcoin_getblockcount","amount":"2500","description":"Read the height of the current best Bitcoin chain.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"type":"integer","minimum":0}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]}},"getbestblockhash":{"tool":"bitcoin_getbestblockhash","amount":"2500","description":"Read the hash of the current best Bitcoin block.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getbestblockhash","params":[]}},"getblockhash":{"tool":"bitcoin_getblockhash","amount":"2500","description":"Look up a Bitcoin block hash by its height.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getblockhash","params":[170]}},"getblockheader":{"tool":"bitcoin_getblockheader","amount":"2500","description":"Read a Bitcoin block header. Set verbose to true for JSON or false for serialized hex.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"oneOf":[{"type":"string","pattern":"^([0-9a-fA-F]{2})+$"},{"type":"object","additionalProperties":true}]}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getblockheader","params":["00000000d1145790a8694403d4063f323d499e655c83426834d4ce2f8dd4a2ee",true]}},"getblock":{"tool":"bitcoin_getblock","amount":"5000","description":"Read a Bitcoin block. Verbosity 0 returns serialized hex; verbosity 1 returns JSON with transaction IDs. Verbosity 2 and 3 are not supported.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"oneOf":[{"type":"string","pattern":"^([0-9a-fA-F]{2})+$"},{"type":"object","additionalProperties":true}]}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getblock","params":["00000000d1145790a8694403d4063f323d499e655c83426834d4ce2f8dd4a2ee",1]}},"getrawtransaction":{"tool":"bitcoin_getrawtransaction","amount":"5000","description":"Read a serialized Bitcoin transaction from an explicit block. Verbose must be false; a block hash is required.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"type":"string","pattern":"^([0-9a-fA-F]{2})+$"}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"getrawtransaction","params":["f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",false,"00000000d1145790a8694403d4063f323d499e655c83426834d4ce2f8dd4a2ee"]}},"gettxout":{"tool":"bitcoin_gettxout","amount":"5000","description":"Read an unspent Bitcoin transaction output, excluding the mempool. A spent or unknown output returns null.","resultSchema":{"type":"object","properties":{"jsonrpc":{"const":"2.0"},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}},"required":["jsonrpc","id","result"],"additionalProperties":false},"example":{"jsonrpc":"2.0","id":1,"method":"gettxout","params":["f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",0,false]}}},"responses":{"200":{"description":"Settled result, or an unbilled Ethereum execution error. Both are retained for same-key recovery.","headers":{"X-Block402-Payment-Status":{"schema":{"const":"not-settled"},"description":"Present for unbilled Ethereum execution errors."},"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded x402 settlement response."},"X-Block402-Receipt-Id":{"schema":{"type":"string"},"description":"Receipt identifier; not a recovery credential."}},"content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Payment pending or ambiguous. Recover with the same key; do not authorize a new payment."},"400":{"description":"Invalid JSON-RPC request, params, recovery key, or payment."},"402":{"description":"Read PAYMENT-REQUIRED. Discovery-only challenges cannot be paid; request a bound quote first.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 challenge."}}},"409":{"description":"Conflicting retry, expired quote, consumed authorization, or definitively failed preparation."},"410":{"description":"Settled result has expired. The receipt is retained; no second charge."},"413":{"description":"Request exceeds the configured size limit."},"415":{"description":"Use uncompressed application/json."},"429":{"description":"Rate limited. Retry the original key after Retry-After."},"502":{"description":"Upstream failed before settlement."},"503":{"description":"New payments paused, review expired, not ready, capacity exhausted, or storage/facilitator unavailable. Existing-key recovery and unsigned discovery remain available during a payment pause."}}}}},"x-agentcash-guidance":{"llmsTxtUrl":"https://api.block402.xyz/llms.txt"},"externalDocs":{"url":"https://api.block402.xyz/docs/api.md"}}