x402 Agent

​

Requirements

• Node.js 18+
• Fireblocks API account with a vault configured
• Sufficient token balance on the target network (for example, USDC on Base)

​

How it works

​

Payment sequence

Agent  ──GET /resource──►  Merchant server
                            │
                      ◄─── 402 + PaymentRequired body

Agent constructs EIP-712 payload, signs via Fireblocks,
retries with PAYMENT-SIGNATURE header:

Agent  ──GET /resource──►  Merchant server
  PAYMENT-SIGNATURE: <base64 payload>
                            │
                      ◄─── 200 + PAYMENT-RESPONSE header
                                 (tx hash, network, payer)

1. Initial request — Agent sends GET to the resource server.
2. 402 Payment Required — Resource server returns a PaymentRequired JSON body with accepts[] payment options.
3. (Optional) Integrity check — Agent verifies the envelope against the facilitator’s did:web key (see Payment Instruction Integrity).
4. Select mechanism — Agent picks the first supported accepts[] entry (preference: eip3009 → permit2; overridable via MECHANISM).
5. Build and sign EIP-712 — Agent constructs typed data locally and signs via Fireblocks.
6. Retry with signature — Agent resends the GET with a PAYMENT-SIGNATURE header. Resource server settles the payment and returns the resource with a PAYMENT-RESPONSE receipt header.

​

Transfer mechanisms

• exact — authorizes the merchant to pull exactly the amount in the 402 body. Recommended default.
• upto — authorizes the merchant to pull up to the amount in the 402 body (the actual debit is decided by the facilitator at settlement time). Useful for variable-cost endpoints, but gives the merchant discretion within the cap. Pair with tighter Policy Engine rules if you use it.

​

Payment Instruction Integrity

• The facilitator emits a base64url-encoded envelope on PaymentRequired.integrity (also mirrored on the X-402-Integrity response header).
• The envelope is signed ES256 (P-256) and the key is resolved via did:web.
• Canonical bytes: SHA-256( JCS({x402Version, accepts}) || "\n" || iat || "\n" || exp ).
• resource.url, error, and extensions are intentionally excluded from the signed slice.

​

Get started

git clone https://github.com/fireblocks/x402-agent
cd x402-agent
npm install
cp .env.example .env
# Edit .env with your Fireblocks credentials
npm run build

​

Usage

​

MCP server

npm start

​

Connect to Claude Desktop

{
  "mcpServers": {
    "x402-payment": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x402-agent/dist/mcp-server.js"],
      "env": {
        "FIREBLOCKS_API_KEY": "<api-key>",
        "FIREBLOCKS_VAULT_ACCOUNT_ID": "<vault-id>",
        "FIREBLOCKS_PRIVATE_KEY_PATH": "/ABSOLUTE/PATH/TO/x402-agent/.secrets/your-key.key",
        "VERIFY_INTEGRITY": "true"
      }
    }
  }
}

​

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/mcp-server.js

​

Example prompts

Use x402_get_and_pay to fetch http://localhost:3010/get-gold

Use x402_get_payment_info to check what payment is required for http://localhost:3010/get-gold

​

x402_get_and_pay options

​

CLI

npm run dev:cli

npx tsx src/index.ts

node dist/index.js

​

Secure deployment

​

Provision a scoped Fireblocks API user

• Role: Signer (or any role limited to Create Transaction / signing operations). No policy edit, no user management, no workspace admin.
• Vault scope: Restrict to a single dedicated vault used only for x402 spend. Keep its balance small — top it up as needed rather than parking your treasury there.
• IP allowlist: Add the machine(s) that will run the agent.
• CSR / API key fingerprint: Record both so you can rotate confidently.

​

Store the API credentials securely

​

Enforce human-in-the-loop signing via the Policy Engine

• Whitelist destinations. Allow only the asset types and recipient addresses you expect (for example, USDC on Base to specific facilitator settlement contracts). Deny everything else.
• Per-tx amount cap matched to a single x402 micropayment (for example, ≤ 1 USDC).
• Per-period velocity cap (hourly / daily) matched to the agent’s autonomous budget.
• Designate a manual signer / approver above a threshold. Configure the policy to require a designated approver for any transaction above your auto-sign threshold; approvals are pushed to the Fireblocks mobile app and enforced cryptographically by the policy, not by trust in the agent code. This is the canonical Fireblocks human-in-the-loop pattern (same approach recommended by the fireblocks-mcp server).
• 2-eyes for any change to the policy itself so a compromised admin can’t widen the rules silently.

​

Constrain the agent at the application layer

• Fireblocks base-URL allowlist (on by default). FIREBLOCKS_BASE_URL must be HTTPS under *.fireblocks.io. The Fireblocks SDK does not validate this URL itself, and its signed JWT only binds the request path — not the host — so an attacker who tampers with FIREBLOCKS_BASE_URL (via a poisoned .env, shell compromise, or CI env injection) could MITM the API channel and replay signed requests against the real Fireblocks within the 55s JWT validity window. For private / alternative endpoints, set FIREBLOCKS_BASE_URL_ALLOWED_HOSTS=host1,host2 with the exact additional hostnames you trust.
• SSRF guard (on by default). Every outbound URL is validated before any request is made: non-http/https schemes are rejected, and IP literals or DNS results in private / loopback / link-local / metadata-range space (including 169.254.169.254, GCP metadata.google.internal, Alibaba 100.100.100.200, IPv6 fc00::/7 / fe80::/10 / ::1) are blocked. HTTP redirects (maxRedirects: 0) are disabled so a 3xx can’t bypass the upfront check. Set ALLOW_LOCAL_TARGETS=true only for local development.
• ALLOWED_MERCHANT_HOSTS — agent refuses any request whose host isn’t in the comma-separated list. Recommended whenever the URL can come from an LLM or external feed.
• REQUIRE_CONFIRM=true (MCP only) — x402_get_and_pay returns a payment preview and refuses to sign until called again with confirmed=true.
• REQUIRE_INTEGRITY=true — refuse to sign 402 responses that fail Payment Instruction Integrity verification.
• Prefer Permit2 exact over upto unless you specifically need variable-cost semantics.

​

Troubleshooting

​

References

• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Permit2
• Fireblocks Web3 Provider
• Repository source layout — src/index.ts (CLI), src/mcp-server.ts (MCP), src/HttpX402Service.ts (payment logic), src/FireblocksService.ts (Web3 provider), src/IntegrityVerifier.ts (integrity checks)