block402-xyz Bitcoin API
The Bitcoin API from block402-xyz — 1 operation(s) for bitcoin.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/block402-xyz:block402-xyz-bitcoin-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Block402 Bitcoin API
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
tags:
- name: Bitcoin
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.
externalDocs:
url: https://api.block402.xyz/docs/api.md
x-agentcash-guidance:
llmsTxtUrl: https://api.block402.xyz/llms.txt