Get paid per request

The model

Ordinal coordinates discovery, provider selection, and paid execution. Providers publish a JSON capability and a per-call USDG price. Agents select a service from the registry, satisfy its x402 challenge on Robinhood Chain, and receive the provider result.

Trust boundary

Ordinal never asks for a seed phrase or private key. The payer signs through its own EVM signer, while the provider receives USDG at the registered payout address. Live routes fail closed when the facilitator is missing or does not advertise exact support for Robinhood Chain.

Protocol flow

1. The agent posts valid JSON to /api/services/[id]/call.
2. Ordinal responds 402 with a base64 x402 v2 challenge in PAYMENT-REQUIRED.
3. The wallet signs the exact EVM token payment and retries with PAYMENT-SIGNATURE.
4. The facilitator verifies the signed transaction before Ordinal invokes the provider.
5. After a valid provider response, the facilitator settles it and Ordinal returns PAYMENT-RESPONSE.

Input schema validation runs before the payment challenge. Invalid input returns400 and never reaches payment verification.

Challenge fields

Canonical IDs

1{
2  "network": "eip155:4663",
3  "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
4  "symbol": "USDG",
5  "decimals": 6,
6  "scheme": "exact"
7}

Testnet uses eip155:46630. Its USDG contract must be supplied through ROBINHOOD_TESTNET_USDG_ADDRESS; Ordinal hides testnet listings until that address is configured and valid.

Publish a service

1. Connect an EVM wallet through Privy and switch to Robinhood Chain.
2. Publish a reachable HTTPS endpoint that accepts and returns JSON.
3. Provide input and output JSON Schemas plus a per-call USDG price.
4. Use the connected EVM address as the payout address.
5. Submit for review; only approved services enter public discovery.

The upstream URL remains private in public registry responses. Agents call the Ordinal gateway, which applies validation, payment, and provider-output checks.

Production checks

Install the bridge

@ordinal402/ordinal-mcp connects an agent to the marketplace and lets it pay from its own wallet. It runs on your machine, and that is the point: the exact scheme needs an EIP-712 signature from the payer for every payment, so a hosted server could only pay for you by holding your key. Browsing is forwarded to Ordinal untouched. Signing happens locally, and only the signature ever leaves your machine.

It needs Node 18 or newer and nothing else — no global install, no build step, no account. Every client below runs the same command and differs only in where its configuration lives.

1npx -y @ordinal402/ordinal-mcp@latest

Set up your client

Pick your client, paste the block, restart it. Replace 0xYOUR_KEY with the payer key. Any client not listed here almost certainly accepts the JSON shape at the bottom.

1claude mcp add ordinal \
2  -e ORDINAL_PRIVATE_KEY=0xYOUR_KEY \
3  -- npx -y @ordinal402/ordinal-mcp@latest
4
5# verify
6claude mcp list

1[mcp_servers.ordinal]
2command = "npx"
3args = ["-y", "@ordinal402/ordinal-mcp@latest"]
4
5[mcp_servers.ordinal.env]
6ORDINAL_PRIVATE_KEY = "0xYOUR_KEY"

Restart Codex after editing the file. The env table must come after args: in TOML every key/value pair belongs to the section above it, so a key placed under [mcp_servers.ordinal.env] and then followed by more server settings will not load.

1{
2  "mcpServers": {
3    "ordinal": {
4      "command": "npx",
5      "args": ["-y", "@ordinal402/ordinal-mcp@latest"],
6      "env": { "ORDINAL_PRIVATE_KEY": "0xYOUR_KEY" }
7    }
8  }
9}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. Quit and reopen the app — a window reload is not enough.

1{
2  "mcpServers": {
3    "ordinal": {
4      "command": "npx",
5      "args": ["-y", "@ordinal402/ordinal-mcp@latest"],
6      "env": { "ORDINAL_PRIVATE_KEY": "0xYOUR_KEY" }
7    }
8  }
9}

Use .cursor/mcp.json inside a repository to scope it to one project instead. Windsurf takes the same shape at ~/.codeium/windsurf/mcp_config.json, and Gemini CLI reads it from ~/.gemini/settings.json.

1{
2  "servers": {
3    "ordinal": {
4      "type": "stdio",
5      "command": "npx",
6      "args": ["-y", "@ordinal402/ordinal-mcp@latest"],
7      "env": { "ORDINAL_PRIVATE_KEY": "0xYOUR_KEY" }
8    }
9  }
10}

VS Code names the object servers rather than mcpServers and wants an explicit "type": "stdio". Ordinal's tools appear in agent mode.

1ORDINAL_PRIVATE_KEY=0xYOUR_KEY npx -y @ordinal402/ordinal-mcp@latest

The bridge speaks JSON-RPC 2.0 over stdin and stdout. Any MCP client that can launch a command works, including your own.

Fund the payer wallet

Three things make a wallet able to pay: it must be a plain externally owned account, it must hold USDG, and it must have approved Permit2 once.

1. Generate or pick an EOA. Not a smart-contract wallet, and not an account carrying an EIP-7702 delegation — see what a paid call costs.
2. Send it USDG on Robinhood Chain, plus a small amount of ETH for step three.
3. Approve Permit2 to spend that USDG. One transaction, once per wallet, ever.

1# USDG -> Permit2, once per wallet. Approves a fixed 25 USDG;
2# raise it or use type(uint256).max if you would rather not repeat this.
3cast send 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 \
4  "approve(address,uint256)" \
5  0x000000000022D473030F116dDEE9F6B43aC78BA3 \
6  25000000 \
7  --rpc-url https://rpc.mainnet.chain.robinhood.com \
8  --private-key 0xYOUR_KEY

After that every payment is gasless for the payer. Ordinal's relayer broadcasts each settlement and pays its gas; the payer only ever signs. The approval is what a payment draws against, so a wallet that runs out of allowance starts failing at settlement — top it up the same way.

Your first paid call

Ask in plain language. The agent picks the service, reads its schema, pays, and hands back the result with a transaction hash.

1What can Ordinal do? List the services and what they cost.
2
3Which wallet will you pay from?
4
5Run a full integrity check on
60x415ce1b4230b5f01170529b369f8ad4001024136 and pay for it.

A paid call returns the provider's JSON plus the settlement: a transaction hash, a block number, and a Blockscout link. Hand that hash to check_payment_status, or open it on Robinhood Chain Blockscout yourself — a paid call you cannot verify on-chain did not happen.

Want to see the shape of a response before spending anything? Ask for a free trial. try_service runs the real provider, settles nothing, and records no usage.

Tools the agent gets

Both call paths validate input against the service's inputSchema first and return that schema in the error, so an agent can correct itself in one turn. Only call_service ever spends; nothing else touches the wallet.

What a paid call costs you

The payer needs USDG for the price and, once per wallet, an on-chain approval of USDG to Permit2. Every payment after that is gasless for the payer: Ordinal's relayer broadcasts the settlement and pays its gas, and the payer only ever signs.

Use a plain externally owned account. Permit2 treats an address holding contract code as a smart wallet and calls isValidSignature on it, so a wallet that does not implement ERC-1271 — including an account delegated under EIP-7702 — will see settlement revert. This is the single most common reason a correctly configured bridge still cannot pay.

When something fails

Browsing without installing anything

The marketplace also answers MCP directly at https://ordinal402.xyz/api/mcp. Point a client at that URL to read the catalogue, inspect a service contract, and run free trials with no package and no wallet. It cannot make a paid call, for the reason above.

1curl -X POST https://ordinal402.xyz/api/mcp \
2  -H 'content-type: application/json' \
3  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Wire headers

MCP is the front door, but nothing depends on it. If your runtime speaks x402 itself, call the gateway directly and preserve these standard header names. Do not substitute transaction-hash proof headers.

1POST /api/services/{id}/call
2Content-Type: application/json
3
4HTTP/1.1 402 Payment Required
5PAYMENT-REQUIRED: <base64 PaymentRequired>
6
7POST /api/services/{id}/call
8PAYMENT-SIGNATURE: <base64 PaymentPayload>
9
10HTTP/1.1 200 OK
11PAYMENT-RESPONSE: <base64 SettleResponse>

Registry routes

Record shape

1{
2  "slug": "token-risk",
3  "name": "Ordinal Token Risk API",
4  "capabilities": ["token", "risk", "security"],
5  "price": { "amount": "0.05", "currency": "USDG" },
6  "network": "robinhood",
7  "endpoint": "https://your-domain.example/api/services/{id}/call",
8  "inputSchema": { "type": "object" },
9  "outputSchema": { "type": "object" },
10  "reliability": {
11    "verified": true,
12    "successRate": 99.5,
13    "averageLatencyMs": 132
14  }
15}

Status codes

Primary sources

Verify protocol behavior in the x402 network and token reference, x402 v2 specification, and Robinhood Chain connection reference, and the Robinhood Chain contract registry.