Payments Layer

Built on @x402/core, @x402/evm (exact EVM scheme), and @coinbase/x402 for CDP mainnet facilitator auth. paid_fetch is x402-only in this build (no MPP/Tempo payment protocol).

The kit picks the facilitator from X402_NETWORK — no manual URL switching per environment when you change network id.

1. 1

   tools/call without paymentPayload

   For priced tools, router evaluates spend policy, resolves payTo (X402_PAY_TO_ADDRESS or agent evmAddress), builds accepts[] via facilitator. Returns a Payment Required error with data.paymentRequirements (scheme: exact, network, payTo, price).

2. 2

   Client signs paymentPayload

   Host wallet or signing service produces x402 v2 paymentPayload matching an accept. The kit never holds private keys.

3. 3

   tools/call with paymentPayload in params

   Facilitator verifies → tool executes → facilitator settles on chain.

4. 4

   MCP success response

   result.content carries tool output (JSON text). result.paymentReceipt carries settlement metadata from facilitator.

5. 5

   Ledger (optional)

   If spend policy is enabled, agent_spend_ledger records USD micro-amount with idempotent requestKey (SHA-256 of agent + tool + payload).

1. 1

   Probe (no paymentPayload)

   paid_fetch calls the HTTPS URL. On a Payment Required response from the HTTPS endpoint (or v1 JSON body), MCP returns a Payment Required error with upstream requirements.

2. 2

   Pay and retry

   Client signs x402 v2 paymentPayload only (v1 rejected). Second call verifies via facilitator, adds PAYMENT-SIGNATURE headers, executes HTTP request.

3. 3

   Settlement

   Prefer PAYMENT-RESPONSE / X-PAYMENT-RESPONSE from origin; else settle via facilitator. Response includes payment_made, payment_details, status, ok, data.

Variable pricing — amount comes from the third party. Trust spend policy does not cap paid_fetch; use discover_services maxUsdPrice operationally.

Discovery alignment: discover_services filters — network, asset (usdc), scheme, payTo, maxUsdPrice — so agents find services that match your payment rail before paid_fetch.

• get_token_priceFixed $0.001/call · full x402 + optional spend policy + ledger
• paid_fetchThird-party x402 HTTPS · variable price · v2 paymentPayload only
• transferNot x402 — unsigned same-chain transfers to fund paying wallets
• discover_services / get_serviceFree catalog browse; returns paymentsProtocolConfig and accepts before spend

Micropayments (x402): exact EVM scheme on X402_NETWORK. Transfers (wallet rail): USDC / USDC.e on ethereum, base, sepolia, polygon, arbitrum-one, monad, tempo, and Solana USDC for prefunding pay-to wallets. Sender pays native gas unless your wallet stack sponsors it.

• mcp_tool_call_logs

  Every tools/call logged with status: ok, error, payment_required, spend_policy_denied, auth_error, invalid_params. Args and response JSON stored (credentials hashed).

  GET /mcp/tool-call-logs?agentId=&toolName=&status=payment_required&from=&to=
• agent_spend_ledger

  Per-agent USD micro totals for Trust Layer budgets after successful kit tool settlement.

• Network picks facilitator

  One X402_NETWORK config switches testnet vs mainnet settlement infrastructure — fewer misconfigurations between dev and prod.

• Verify before execute

  Kit tools run priced logic only after facilitator verification succeeds.

• Two-step payment UX

  paymentRequired first, paymentPayload second — natural pause for approval UI.

• No custody in the kit

  Client signs; facilitators verify and settle; payTo can be agent wallet or platform override.

• Idempotent accounting

  Ledger requestKey deduplication; tool call logs for operational audit.

• Payments Layer

  You are here

  x402 verify and settle on chain for kit tools and external APIs. Network-aware facilitators, per-call pricing, paymentReceipt and tool-call logs.

• Agent Interface

  Payments are MCP tools/call with optional params.paymentPayload. Success bundles content + paymentReceipt.

• Identity Layer

  Registration JSON declares x402Support: true and MCP endpoint.

• Discovery Layer

  Bazaar entries include accepts and payTo; paid_fetch executes what discovery finds.

• Trust Layer

  Spend policy before -32402 on kit fixed prices; ledger after settle. paid_fetch and transfer limits composable in your app.

Dependencies: @x402/core, @x402/evm, @coinbase/x402. Env: X402_NETWORK, X402_TESTNET_FACILITATOR_URL, CDP_API_KEY_*, X402_PAY_TO_ADDRESS.

# Testnet (default Base Sepolia)
X402_NETWORK=eip155:84532
X402_TESTNET_FACILITATOR_URL=https://x402.org/facilitator
# CDP keys not required