Hoodx402 docs

Everything you need to accept per-call payments from AI agents on Robinhood Chain — or to let an agent pay for anything without an account.

Overview

Hoodx402 has three roles. Most readers are one of the first two:

• API provider — wraps an HTTP endpoint with a price. Agents pay you per call; you never handle keys, invoices, or merchant infrastructure.
• Agent — any HTTP client with a wallet. It calls an API, receives a price, signs one payment, and gets the response plus an on-chain receipt.
• Facilitator — Hoodx402's service that verifies signed payments and settles them on-chain, so neither side waits on the other.

Payments use the x402 open standard: the API answers 402 Payment Required with terms in a header, the agent signs an EIP-3009 transfer-with-authorization, and the facilitator settles in USDG. No subscriptions, no API keys, no chargebacks.

Quickstart — provider

Wrap an existing route. If it answers today, it can earn per call.

import { wrap } from "@hoodx402/sdk";

// your server, unchanged
const api = wrap(app, {
  asset: "0x0f2fe3ca4308b144e4fc38da51d9e8f5a7a80643",
  assetSymbol: "USDG",
  assetName: "USDG Mock", // EIP-712 domain name
  assetVersion: "1",
  chainId: 46630,
  chain: "robinhood-testnet",
  payTo: "0x…",           // your payout address
  decimals: 6,
  facilitatorUrl: "https://facilitator.h402.finance",
});

api.route("GET /v1/quote", handler, {
  price: "0.001",   // human decimal — converted once, at registration
});

What the SDK does for you

• Intercepts the first unauthenticated request and answers 402 with a challenge header.
• Forwards the request with an X-PAYMENT signature to your handler once payment is verified.
• Returns a receipt header on every paid call, so both sides can audit it later.

Requirements

• Node 20+ and any HTTP framework (Express, Fastify, Hono — wrap adapts to the request/response objects).
• A payout address on Robinhood Chain testnet. Settlement lands there; you never sign anything as a provider.

The settlement flow

One call moves through four states. Each header below is part of the pilot spec.

1 · API answers 402

HTTP/2 402 PAYMENT REQUIRED
x-402: asset=0x0f2f…0643   # testnet MockUSDG
       amount=1000         # smallest units (0.001, 6 decimals)
       decimals=6 name=USDG%20Mock version=1
       chain-id=46630 facilitator=hoodx402
       pay-to=0x…          # provider payout address
       nonce=0x…           # bytes32, single-use
       valid-before=1787903890

Values are URL-encoded when they contain spaces (a token named USDG Mock arrives as name=USDG%20Mock). The provider stores every issued challenge — the payer must satisfy the exact quote.

2 · Agent signs once

The agent signs an EIP-3009 TransferWithAuthorization for amount of the asset, payable to pay-to, valid until valid-before. The signature is a header — not a transaction.

x-payment: scheme=eip3009 from=0x… # payer — must equal the recovered signer
           signature=<65-byte rsv> nonce=0x…

3 · Facilitator settles

The facilitator verifies the signature against the challenge, submits the settled transfer on-chain, and returns the receipt hash. Settlement is idempotent per nonce — a retried call never pays twice.

4 · 200 OK with receipt

HTTP/2 200 OK
x-receipt: 0x91c4…8e02 - settled 0.001 USDG

Agent side

Agents get one helper that handles the 402 round-trip. Give it a wallet-capable signer and a spending cap; it never exceeds the cap.

import { x402Fetch } from "@hoodx402/sdk";

const res = await x402Fetch(
  "https://quotes.example/v1/quote?symbol=NVDA",
  { signer, maxPrice: "0.01" }
);

const quote = await res.json();
console.log(res.headers.get("x-receipt"));

Chain config

Prices are strings denominated in the asset's smallest unit unless the route declares decimals. "0.001" USDG means 0.001 USDG — the SDK converts once, at the route definition, not per call. These addresses are testnet-only; do not reuse them for mainnet configuration.

Facilitator API

The base URL is https://facilitator.h402.finance. Payment calls are replay-safe: the service checks the durable receipt stored by Settlement.getRecord, including after container restarts.

GET /health and /ready

/health reports process liveness. /ready also verifies that the RPC is reachable on chain 46630.

curl -fsS https://facilitator.h402.finance/ready
# {"ok":true,"service":"hoodx402-facilitator","chainId":46630}

POST /verify

Checks a signed payment against a challenge. Returns valid or a machine-readable reason — nothing moves.

{ "valid": true, "payer": "0x7a…f3", "amount": "0.001" }

POST /settle

Submits the verified payment on-chain. Retries with the same nonce return the original receipt.

{ "receipt": "0x91c4…8e02", "tx": "0x7d3b…01aa",
  "settled": "0.001" }

Operational behavior

• Every response includes x-request-id for log correlation.
• /verify and /settle are rate-limited per client; honor Retry-After on 429.
• /metrics exposes Prometheus counters for uptime, HTTP status, and settlement outcomes.
• Malformed bodies return bounded 4xx JSON errors and never leak request signatures into logs.

Registry

Paid endpoints are discoverable. Providers list routes on-chain; agents query the registry instead of hard-coding URLs.

The pilot Registry is live at 0x006c…93e. Listing requires a 0.001 ETH registration stake, returned on delisting. The public SDK registry helper is still being designed; pilot listings are coordinated with design partners.

Errors

Status

• Facilitator: live on Robinhood Chain testnet.
• SDK: @hoodx402/sdk 0.1.x — testnet pilot release.
• Settlement v0.2 and Registry: deployed on-chain at the addresses above.
• Automated coverage: 60 SDK, facilitator, E2E, and contract checks.
• Mainnet: gated on the audit — see the roadmap.

Questions or an endpoint you want wrapped? Apply for the pilot or open an issue on GitHub.