x402 Documentation

How to call Ontario Protocol's paid endpoints from any agent that speaks HTTP. USDC on Base. No API keys.

New: x402 endpoint readiness quickstart (generate a public report_id before asking agents to pay) · agent payment preflight guide (apply /api/agent/can-pay policy before signing) · wallet-enabled buyer client quickstart (connect a local x402 wallet bridge after free preflight) · agent payment policy JSON (publishable allow/review/deny contract for payment-capable agents) · embed a readiness badge (link badge → signed report; verify integrity + freshness) · list an x402 service (validate payload, rehearse in sandbox, then submit paid listing) · x402 verification tools comparison (which checks an agent should run before payment) · GitHub x402 repository scanner (check public repository evidence before deployment) · MCP Registry readiness checker (check public registry metadata and read-only MCP discovery) · agent decision playbooks (100 Search Console-informed pre-payment workflows) · Search Console indexing playbook (core sitemap, evidence sitemap, and 404 triage).

Agent/tool registry bundle

If you list Ontario in an MCP registry, agent tool catalog, GitHub README, or AI crawler profile, point to the three canonical manifests together. The MCP manifest tells agents which tools exist, the x402 manifest tells payment-aware clients what can be paid, and the buyer guide tells agents when to stop or proceed.

curl https://ontarioprotocol.com/.well-known/mcp.json
curl https://ontarioprotocol.com/.well-known/x402.json
curl https://ontarioprotocol.com/.well-known/agent-buyer.json
curl https://ontarioprotocol.com/.well-known/agent-payment-policy.json

Payment posture: discover first, run free preflight, probe the structured HTTP 402, then pay only when policy allows and the paid result adds value beyond free reports or catalog data.

Overview

Every paid endpoint on Ontario follows the x402 protocol:

1. Client makes a normal request, no payment header.
2. Server replies HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON).
3. Client signs a payment payload (EIP-3009 transferWithAuthorization for USDC) and resends with PAYMENT-SIGNATURE header.
4. Server forwards to a facilitator (Coinbase by default) for verify + settle, then returns HTTP 200 + PAYMENT-RESPONSE header.

The flow, in pictures

Client                        Ontario                       Coinbase Facilitator
  |  POST /api/x402/...      |                              |
  |------------------------->|                              |
  |  402 PAYMENT-REQUIRED    |                              |
  |<-------------------------|                              |
  |  build + sign            |                              |
  |  PaymentPayload          |                              |
  |  POST + PAYMENT-SIGNATURE|                              |
  |------------------------->|  POST /verify                |
  |                          |----------------------------->|
  |                          |  isValid: true               |
  |                          |<-----------------------------|
  |                          |  POST /settle                |
  |                          |----------------------------->|
  |                          |  success: true, tx: 0x...    |
  |                          |<-----------------------------|
  |  200 + PAYMENT-RESPONSE  |                              |
  |<-------------------------|                              |

curl

# 1. Probe — get the 402 with payment requirements
curl -i -X POST https://ontarioprotocol.com/api/x402/agent-trust-scan \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent","target_url":"https://example.com"}'

# 2. Decode the PAYMENT-REQUIRED header (base64 → JSON):
echo "$PAYMENT_REQUIRED_HEADER" | base64 -d | jq

# 3. Sign the payload with your wallet (using x402 client SDK, see Python below)
# 4. Resubmit with PAYMENT-SIGNATURE header:
curl -X POST https://ontarioprotocol.com/api/x402/agent-trust-scan \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: $SIGNED_PAYLOAD_B64" \
  -d '{"agent_id":"my-agent","target_url":"https://example.com"}'

Python

# pip install x402 web3 eth-account requests
# Never paste real keys into source files. Use an env var and a dedicated low-balance wallet.
from x402.client import X402Client
from eth_account import Account
import os

acct  = Account.from_key(os.environ["X402_PRIVATE_KEY"])
client = X402Client(account=acct, default_network="base")

resp = client.post(
    "https://ontarioprotocol.com/api/x402/agent-trust-scan",
    json={
        "agent_id": "my-agent",
        "target_url": "https://example.com",
    },
    max_payment_atomic=10_000,   # 0.01 USDC, prevents over-pay
)
print(resp.json()["report"]["trust_score"])

TypeScript

// npm install x402 viem
// Never hardcode keys. Use an env var (Node) and a dedicated low-balance wallet.
import { createX402Client } from "x402";
import { privateKeyToAccount } from "viem/accounts";

const privateKey = process.env.X402_PRIVATE_KEY;
if (!privateKey) throw new Error("Missing X402_PRIVATE_KEY");
const account = privateKeyToAccount(privateKey);
const client  = createX402Client({ account, defaultNetwork: "base" });

const res = await client.fetch(
  "https://ontarioprotocol.com/api/x402/agent-trust-scan",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      agent_id:   "my-agent",
      target_url: "https://example.com",
    }),
    maxPaymentAtomic: 10_000n,
  }
);
const data = await res.json();

Endpoints

* "Free" meaning no fee to call the endpoint. Settlement transactions themselves cost gas + the marketplace's 1.5% take rate when applicable.

Marketplace: list a third-party service

POST /api/x402/list-service is a paid marketplace endpoint (0.50 USDC) used to register a third-party x402-paid API so agents can find it through Ontario’s discovery surfaces. On submission, Ontario runs the free readiness verifier against your endpoint and stores the resulting report.

• Immediately: your submission appears in /listings as PENDING or READY.
• Only when ready: it enters /discover (default filters) and /.well-known/x402.json when its stored report grades ready.
• Trust boundary: readiness signals are not a safety guarantee; agents should still preflight and enforce budgets.

Request body

{
  "name": "My Cool API",
  "description": "What it does",
  "category": "data",
  "endpoint": "https://example.com/api/data",
  "method": "GET",
  "price_atomic": 10000,
  "price_usdc": "0.01",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "base",
  "owner_url": "https://example.com",
  "owner_contact": "ops@example.com",
  "tags": ["dataset", "ai-agent", "x402"]
}

Tip: run /verify first and submit only after you reach grade=ready with a fresh report.

Before you pay the listing fee, you can validate your payload shape for free: POST /api/x402/list-service/validate (no payment; does not store a listing).

Sandbox rehearsal (no on-chain rails; does not store a listing): POST /sandbox/api/x402/list-service. It behaves like a paid x402 endpoint (HTTP 402 first, then accept a simulated payment payload), so you can test your x402 client integration without spending money.

Machine-readable schema: /.well-known/x402-list-service.schema.json

curl -sS https://ontarioprotocol.com/api/x402/list-service/validate \\
  -H "Content-Type: application/json" \\
  -d '{"name":"Example Service","description":"Paid endpoint","endpoint":"https://example.com/api/paid","method":"POST","price_usdc":"0.01","network":"base","owner_url":"https://example.com"}'

SDK examples: ontario_list_service.py · ontario-list-service.ts

Response body

The response includes the settlement context under payment and the stored listing under listing (including verification_status, verification, and paid_listing_tx).

Directory: list an agent (optional)

POST /api/x402/list-agent (0.10 USDC) registers an agent card URL for the directory. It uses the same auto-verification behavior (a readiness report is attempted and attached if available).

Validate your agent submission payload for free with POST /api/x402/list-agent/validate.

Machine-readable schema: /.well-known/x402-list-agent.schema.json

curl -sS https://ontarioprotocol.com/api/x402/list-agent/validate \\
  -H "Content-Type: application/json" \\
  -d '{"name":"Example Agent","description":"Agent card","agent_card_url":"https://example.com/agent.json","owner_url":"https://example.com"}'

Errors

Facilitator

By default Ontario delegates verification + settlement to Coinbase's hosted facilitator (limits and rate policies may apply — confirm against Coinbase docs). With X402_USE_PROXY=1 in the server's .env, requests pass through Ontario's proxy_facilitator, which logs every settlement to a public, append-only SQLite ledger and applies the 1.5% take rate on third-party listings.

See /treasury for the live, public ledger summary or call /api/treasury/ledger directly.

Cookbook: production-tested pay-and-scan script

The following is a production-style reference script for paying an x402 endpoint and then running an Ontario scan to record evidence. Download it, set env vars, and run:

# Install deps
pip install x402 requests pyjwt[crypto] cryptography python-dotenv

# Set env (or add to .env)
export CDP_API_KEY="your-cdp-key-id"
export CDP_API_SECRET="base64-ed25519-secret"
export BUYER_WALLET_SECRET="base64-ec-p256-der-private"
export BUYER_WALLET_ADDRESS="0x…your-wallet"

# Run
python pay_and_scan.py

⬇ Download pay_and_scan.py — The complete reference implementation (~210 lines).

Common pitfalls