Protocol Reference

x402 on Vaultfire

x402 is HTTP's payment-required code, reborn for the agentic web. Vaultfire ships 82 paid endpoints that any agent can discover, price, and pay — without an account, an API key, or human intervention.

How it works

  1. Discover. Fetch /api/x402/discovery or /.well-known/x402.json to enumerate every endpoint, price, and category.
  2. Probe. Hit any endpoint with no header. You receive a 402 body containing accepts[], errorCatalog, abi, agentHints, and relatedEndpoints — enough for an agent to act without ever reading docs.
  3. Sign. Build an EIP-3009 transferWithAuthorization against USDC on Base (or Avalanche, Arbitrum, Polygon), base64-encode {x402Version,scheme,network,payload}, and resend as the X-PAYMENT header.
  4. Settle. Vaultfire verifies on-chain balance, replay protection (nonce KV), and the EIP-712 signature, then executes the action — all in one round-trip.
  5. Recover. Every failure mode carries a stable code (VF-PAY-001..013) plus retryable, hint, and details fields. Agents branch on the code, not the message.

What makes a Vaultfire 402 agent-native

Beyond the base x402 spec, every Vaultfire 402 includes:

  • serviceName, category, tags, iconUrl — surface metadata for directories and UIs.
  • abi.fullAbiUrl + SHA-256 — hosted, tamper-evident Solidity ABI for the underlying on-chain function.
  • relatedEndpoints — graph hints to neighbouring endpoints, so an agent can chain calls without re-discovering.
  • agentHints.next, agentHints.agentGuide, agentHints.errorCatalog — direct pointers to the instructions and catalog an agent needs to recover.
  • errorCatalog — stable code table, including deprecation markers, so a 2026 agent and a 2030 agent both branch correctly.

Get going

x402 — Vaultfire