x402 payment

x402 is a machine-payment protocol: when a client hits a paid endpoint without a payment, the server responds HTTP 402 with a JSON challenge describing what to pay and where. The client signs a USDC transfer, retries with an X-PAYMENT header, the server forwards to the facilitator for /verify and /settle, and the request proceeds.

Calling the gated API

# 1. First call returns 402 with a challenge
curl -X POST http://localhost:3001/scan \
  -H 'content-type: application/json' \
  -d '{"address":"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","chainId":1}'

{
  "error": "Payment Required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "0.10",
    "resource": "...",
    "payTo": "0x...",
    "asset": "USDC",
    "facilitator": "https://x402.org/facilitator"
  }]
}

# 2. Sign and retry. Most x402 client libraries handle this loop for you.
curl -X POST http://localhost:3001/scan \
  -H 'content-type: application/json' \
  -H "X-PAYMENT: $signed_payload" \
  -d '{"address":"0x...","chainId":1}'

Calling the agent

The agent at apps/agent exposes /ask with x402-hono middleware configured for Base USDC. Cost is X402_PRICE_USDC per call (default $0.10).

curl -X POST http://localhost:3002/ask \
  -H 'content-type: application/json' \
  -H "X-PAYMENT: $signed" \
  -d '{"prompt":"Is 0xc02a...c756cc2 on Ethereum safe to use as collateral?"}'

The agent calls scan_token as a tool, then answers in natural language.

Server config

X402_RECEIVER_ADDRESS=0xYourReceiverWallet
X402_FACILITATOR_URL=https://x402.org/facilitator
X402_NETWORK=base
X402_PRICE_USDC=0.10