Block402

npx add-mcp 'https://api.block402.xyz/mcp'

Your first blockchain read.A budget you control.

Read Bitcoin and Ethereum mainnet data through 44 tools. No account, API key or subscription. Pay 0.0025, 0.005 or 0.01 USDC per request on Base mainnet.

1. Install the agent client

Use Node.js 22 or later. You need no wallet to install, list methods or preview a price.

npm install https://block402.xyz/downloads/block402-agent-0.1.0.tgz
npx --no-install block402-agent demo simulate quote

The result shows a request ID and a 0.01 USDC quote for an Ethereum read-only contract call. paymentAttempted: false means no payment was signed or sent.

Download sizes and SHA-256 checksums · Download the Block402 agent skill

To install the skill, unzip the block402 folder into your agent's supported skill directory. Keep its SKILL.md and agents/openai.yaml together. The skill previews prices and requires payment authorization; installing it grants no spending permission.

2. Make one paid request

Approve the concrete price or a total budget. Supply a dedicated buyer wallet through your secret manager as BLOCK402_BUYER_MAINNET_PRIVATE_KEY, with native USDC on Base mainnet. Keep keys outside prompts, command arguments and shared configuration. The receiving wallet's private key is never required.

# This command can spend real USDC. Use the ID returned by your quote.
npx --no-install block402-agent demo simulate pay \
  --request-id REQUEST_ID --allow-pay --budget 0.05

The lifetime budget includes all purchases and uncertain signatures in your private ~/.block402 state. It persists across restarts. A new request ID means a new purchase. Do not clear state to retry a payment or bypass the budget.

3. Recover after an interrupted response

npx --no-install block402-agent demo simulate recover --request-id REQUEST_ID

Recovery never reads your wallet key, signs or pays. Keep the original ID, method and params. After a 202, timeout or interrupted paid call, recover that purchase instead of starting another. Results are retained for seven days by default.

Connect your MCP host

The local bridge adds wallet signing and persistent recovery to MCP hosts that do not handle x402. Install the package in the host's working directory, or configure an absolute path to the installed executable.

{"mcpServers":{"block402":{"command":"npx","args":["--no-install","block402-agent","mcp"]}}}

This configuration previews prices only. To permit payments, the operator can add --allow-pay --budget 0.05 after approving that total budget and inject the buyer wallet through the local process environment. Each tool takes params, a stable requestId and mode: quote, pay or recover. Quote is the default.

Already using an x402-capable MCP client?

{"mcpServers":{"block402":{"url":"https://api.block402.xyz/mcp"}}}

This is Streamable HTTP. Tool discovery is free. Paid invocation needs your host's x402 payment integration and private idempotency key; a plain MCP URL alone cannot supply a wallet.

Use the client in code

import { createClient } from 'block402-agent';
const client = createClient();
const quote = await client.request({
  network: 'ethereum', method: 'eth_blockNumber', params: [],
  requestId: 'head-check-1', mode: 'quote'
});
console.log(quote);

block402-agent methods lists every method with schemas and prices. For an approved programmatic payment, construct with allowPay: true, a total budget, and a getPrivateKey callback backed by your secret manager. JSON numbers are returned as decimal strings to preserve precision.

Bitcoin and Ethereum are the data networks. Base mainnet is the payment network. Simulation does not broadcast a transaction. Historical state and proofs depend on retained node data; archive state is not guaranteed. Legitimate null results are billable. Pre-settlement failures are unbilled; an uncertain settlement is not proof of failure.

Pick a useful first task

Local Sepolia is a separate development profile: --payment-env sepolia targets a local gateway and a separate BLOCK402_BUYER_TEST_PRIVATE_KEY. There is no public sandbox or silent network switch.