Payments

x402 is the HTTP 402 payment protocol. A paywalled resource answers a request with 402 Payment Required and a payment-required header describing what it accepts. The Payments primitive gives each agent its own crypto wallet (USDC on Base) and lets it settle those 402s autonomously: quote the price, sign a USDC payment, retry the request, keep the receipt.

Payments is opt-in. Unlike most primitives it is disabled in a fresh AccountKit and must be enabled explicitly — see Account Kits. The wallet is per-agent: there is no company-level fallback mount, so CLI and API calls need a subject (naive use <user>).

CLI First

# The wallet is per-agent — select one first
naive use alice

# 1. Probe the price (zero side effects — the wallet is not even loaded)
naive payments quote --url https://api.example.com/report

# 2. Pay for and fetch the resource
naive payments pay --url https://api.example.com/report --max-amount 0.50

# 3. Reconcile
naive payments receipts --direction buy --limit 10
naive wallet balance

Tools

Tool	Type	Description
`naive_payments_quote`	Core	Probe an x402 URL for its price without paying
`naive_payments_pay`	Core	Pay for and fetch an x402 resource — sensitive, spends real USDC
`naive_payments_receipts`	Tracking	List x402 payment receipts
`naive_wallet_balance`	Read	Read the agent’s USDC balances

The wallet’s admin verbs (fund, transfer, policy, sweep) are deliberately not MCP tools and not in the SDK — they are the operator surface only. See Governance.

How it works

pay is the full buy-side flow. quote runs only the first two steps, which is why it has no side effects at all.

Fetch

The resource is fetched normally. If it returns anything other than 402, nothing was paywalled — pay returns the body with paid: false and no receipt is written.

Read the requirements

On a 402, the payment-required header is decoded into a list of accepts options (amount, asset, network, payTo).

Select under policy

The options are filtered against the wallet’s perTxMax, the per-call max_amount, and the allowed networks. The effective cap is min(max_amount, perTxMax).

Check balance and budget

The wallet balance and (if set) the rolling dailyBudget counter are checked. A refusal here happens before anything is signed and emits a payment.denied event.

Sign

The custody provider signs an EIP-3009 TransferWithAuthorization. The provider re-enforces perTxMax inside the custody plane at signing time.

Retry once

The request is retried with a PAYMENT-SIGNATURE header attached.

Hard stop

If the retried request fails, that is the end — there is no second retry. A payment.failed event is emitted and the call throws. On success, the payment-response envelope is stored and a receipt is written.

Quote

naive payments quote --url https://api.example.com/report

{
  "paid": false,
  "free": false,
  "status": 402,
  "accepts": [
    {
      "amount": "500000",
      "asset": "USDC",
      "network": "eip155:8453",
      "payTo": "0xabc..."
    }
  ]
}

accepts[].amount is in atomic units. USDC has 6 decimals, so 500000 = 0.50 USDC. Everything else in this primitive — perTxMax, dailyBudget, --max-amount, fund/transfer amount, and a receipt’s amount — is a decimal USDC string (e.g. "1.00").

If the resource is not paywalled, quote returns free: true with the real HTTP status and an empty accepts — fetch it normally, no payment needed.

Pay

naive payments pay --url https://api.example.com/report --max-amount 0.50

Returns the resource body plus the receipt:

{
  "status": 200,
  "body": "...the resource...",
  "paid": true,
  "receipt": {
    "direction": "buy",
    "origin": "https://api.example.com",
    "payTo": "0xabc...",
    "amount": "0.50",
    "asset": "USDC",
    "network": "eip155:8453",
    "txHash": "0x..."
  }
}

Receipts

Every settled payment is recorded. direction is buy (paid out) or sell (received).

naive payments receipts --direction buy --origin https://api.example.com --limit 20
naive payments receipts --since 2026-07-01T00:00:00Z

GET /v1/users/{user_id}/payments/receipts and GET /v1/users/{user_id}/wallet/balances return bare arrays, not wrapped objects. Receipt and wallet JSON fields are camelCase (txHash, payTo).

Spend control

This is the part that most deserves reading. Unlike Cards and Trading, payments have no approval workflow — there is no pending_approval, no approval queue, and that is deliberate, not an omission. Three controls bound a payment instead:

Control	Where enforced	Notes
Balance	The chain	The primary budget — an agent cannot spend what isn’t there.
`perTxMax`	Runtime and the custody plane	Max value of a single payment. Required. Defaults to `0.50` USDC.
`dailyBudget`	Runtime	Optional rolling per-UTC-day counter.

Why no approval prompt? perTxMax is enforced twice: once at runtime in the pay flow, and again as a static account policy inside the custody plane, checked when the payment is signed. That second check holds even if the agent runtime is fully compromised — a guarantee an approval prompt cannot make, since a compromised runtime can simply stop asking. Fund the wallet with what you can afford to lose, set perTxMax, and the ceiling is structural.

There are deliberately no origin or payee allowlists and no velocity rules. --max-amount (or max_amount) adds a per-call ceiling on top of perTxMax for one specific payment.

Governance

The wallet splits into two surfaces. Per spec §3.7, the admin verbs are operator-surface only — not agent tools:

Surface	Verbs	Who
Agent-safe	`wallet show`, `wallet balance`, and all of `payments` (quote/pay/receipts)	Any agent with the `payments` primitive granted
Operator-only	`wallet create`, `fund`, `transfer`, `policy`, `sweep`	A signed-in dashboard session, or an API key minted with the `wallet:admin` scope

The operator verbs are gated server-side by enforceWalletAdmin, and the CLI refuses them client-side too. An agent key is refused. They are also absent from the MCP tool list and the SDK entirely — non-exposure plus an explicit gate. An AccountKit can additionally deny wallet administration for a user by listing the payments.wallet.admin capability in primitives_config.payments.capabilities.deny.

Agents as code

Declare a wallet on an agent with has.crypto. This implies the payments slug in the allowlist and adds a crypto_wallet provisioning step.

import { agent, skills } from "@usenaive-sdk/iac";

agent({
  has: {
    // Bare form — a wallet with the default policy (perTxMax "0.50")
    crypto: true,
  },
});

agent({
  has: {
    // Or with a spend policy (decimal USDC strings)
    crypto: { perTxMax: "1.00", dailyBudget: "10.00" },
  },
  can: [skills.payments], // or skills.payments.pay / .quote
});

Do not reach for limits.approve: [skills.payments.pay]. Payments has no approval workflow, so such a rule compiles but is never enforced — it would give you a gate you believe in and do not have. Bound payments with has.crypto’s perTxMax / dailyBudget and with how much you fund the wallet.

Configuration

Setting	Purpose
`WALLET_ENABLED`	Master switch. Default false.
`WALLET_PROVIDER`	`fake` (default — works with no credentials) or `cdp`.

Network: USDC on Base (eip155:8453).

When WALLET_ENABLED is false, the crypto_wallet provisioning step resolves to needs_action — it never fails the deployment. With WALLET_PROVIDER=cdp, credentials are BYO from the tenant vault; missing creds produce a typed WalletNotConfigured error and a “connect your CDP account” prompt rather than an opaque failure.

Custody backends

Custody	Use
`fake`	Local development — no credentials required
`cdp`	Hosted custody with the tenant’s own CDP credentials; the static `perTxMax` account policy is attached here at create
`local`	Locally-held key

Typical Workflows (Agent Perspective)

Paying for a paywalled resource

1. POST /v1/users/<id>/payments/quote { url: "https://api.example.com/report" }
   → status: 402, accepts: [{ amount: "500000", asset: "USDC", network: "eip155:8453" }]
   → 500000 atomic = 0.50 USDC. Nothing was spent.

2. GET /v1/users/<id>/wallet/balances
   → [{ asset: "USDC", amount: "5.00" }] — affordable

3. POST /v1/users/<id>/payments/pay { url: "...", max_amount: "0.50" }
   → paid: true, body: "...", receipt: { amount: "0.50", txHash: "0x..." }

4. GET /v1/users/<id>/payments/receipts?direction=buy
   → [{ origin: "https://api.example.com", amount: "0.50", txHash: "0x..." }]

The resource turned out to be free

1. POST /v1/users/<id>/payments/quote { url: "https://api.example.com/public" }
   → free: true, status: 200, accepts: []
   → No paywall. Fetch it normally — no payment, no receipt.

The payment was refused

1. POST /v1/users/<id>/payments/pay { url: "...", max_amount: "0.05" }
   → PaymentRejected — the resource asks 0.50, over the effective cap
   → Refused BEFORE signing; a payment.denied event is logged; nothing spent.
   → Recovery: raise --max-amount (still bounded by perTxMax), or ask an
     operator to raise the wallet policy.

Setting up a wallet (operator, not the agent)

naive use alice
naive wallet create                                  # operator credential required
naive wallet policy --per-tx-max 1.00 --daily-budget 10.00
naive wallet fund --amount 5.00 --source faucet      # faucet is testnet only
naive wallet balance                                 # agent-safe from here on

Getting Started

Self-hosting (Tower)

Agent Profiles

Architecture

Templates

Migration Guides

Integrations

Primitives

CLI First

Tools

How it works

Quote

Pay

Receipts

Spend control

Governance

Agents as code

Configuration

Custody backends

Typical Workflows (Agent Perspective)

Paying for a paywalled resource

The resource turned out to be free

The payment was refused

Setting up a wallet (operator, not the agent)

​CLI First

​Tools

​How it works

​Quote

​Pay

​Receipts

​Spend control

​Governance

​Agents as code

​Configuration

​Custody backends

​Typical Workflows (Agent Perspective)

​Paying for a paywalled resource

​The resource turned out to be free

​The payment was refused

​Setting up a wallet (operator, not the agent)

CLI First

Tools

How it works

Quote

Pay

Receipts

Spend control

Governance

Agents as code

Configuration

Custody backends

Typical Workflows (Agent Perspective)

Paying for a paywalled resource

The resource turned out to be free

The payment was refused

Setting up a wallet (operator, not the agent)