Agent Payments
Most buyers should still start with the governed API-key path. This page is for the wallet-first cases: use wallet-prefund when the same wallet will call repeatedly, and use x402 per-call when request-level payment authorization is the actual requirement.
Before you choose a wallet rail
Want to inspect the trust story first? Read Trust, inspect the public Methodology, or use the provider dispute path if a score or claim looks wrong.
Choose your rail
The buyer-readable version is simple: start with governed API key by default, use wallet-prefund when you want wallet identity plus repeat traffic, and use x402 only when each request should carry its own payment authorization.
Where this rail fits
Default path: start with governed API key or wallet-prefund on `X-Rhumb-Key`, discover a Service, choose a Capability, estimate the call, then execute through Layer 2. Start with Rhumb-managed superpowers first. Bring BYOK or Agent Vault only when the workflow touches your own systems. Use x402 only when zero-signup per-call matters. Use Layer 1 only when you must pin the provider. Use Layer 3 only when a published recipe already exists.
Default production path
Most repeat traffic should run through Layer 2 with governed API key or wallet-prefund on X-Rhumb-Key. Bring BYOK or Agent Vault only when provider control is the point.
Use x402 when
Zero-signup, request-level payment authorization matters more than repeat throughput or broad wallet-proof compatibility.
Switch to wallet-prefund when
The same wallet needs repeat calls. Authenticate once, top up reusable balance, then execute with X-Rhumb-Key.
Canonical onboarding map: /docs#resolve-mental-model
x402 is the payment-first execution rail. Instead of creating an account and receiving a reusable governed API key, an agent asks to run a capability, receives payment requirements on HTTP 402, pays that request, and then proves payment to complete execution.
Current public support is intentionally narrow: USDC on Base. That keeps the flow deterministic for agents and clear for operators.
Current compatibility boundary
The repeatable public x402 execute path today is the plain payment-proof flow shown below: request 402,
pay the exact requirement, then retry with X-Payment
carrying tx-hash proof. Some smart-wallet or wrapped authorization payloads still depend on a
facilitator path that is not wired in current production. Wallet-prefund top-up verification is the
standard x402 authorization path today. If your buyer emits wrapped proofs,
use wallet-prefund
or the standard governed API key rail instead of assuming drop-in x402 interoperability.
1
Call the execution endpoint without a governed API key when you want the payment rail to handle authorization.
2
Rhumb responds with exact payment requirements for that execution, including amount, token, and network.
3
Your agent submits the on-chain payment from its wallet instead of relying on pre-issued credentials.
4
Repeat the request with X-Payment using the tx hash, network, and payer wallet so Rhumb can verify payment and execute the capability.
Discover contract
curl https://api.rhumb.dev/v1/pricingEstimate before execution
curl "https://api.rhumb.dev/v1/capabilities/{capability_id}/execute/estimate"Execution flow
# Step 1: request execution without a governed API key
curl -X POST "https://api.rhumb.dev/v1/capabilities/{capability_id}/execute" \
-H "Content-Type: application/json" \
-d '{"body": {"to": "user@example.com", "subject": "Hello from Rhumb"}}'
# Step 2: pay the exact asset + amount to the exact address on the exact network returned in the 402 response
# Step 3: retry with payment proof from the same wallet
curl -X POST "https://api.rhumb.dev/v1/capabilities/{capability_id}/execute" \
-H 'X-Payment: {"tx_hash":"0x...","network":"<network-from-402>","wallet_address":"0x..."}' \
-H "Content-Type: application/json" \
-d '{"body": {"to": "user@example.com", "subject": "Hello from Rhumb"}}'
Use pure x402 when you want zero-signup authorization on every request. Use wallet-prefund
when you still want wallet-first funding, but repeat traffic should execute via
X-Rhumb-Key against reusable balance.
x402 per-call
X-Payment.wallet-prefund
org_credits.X-Rhumb-Key execution.Wallet-prefund route map
POST /v1/auth/wallet/request-challenge
POST /v1/auth/wallet/verify
POST /v1/billing/x402/topup/request
POST /v1/billing/x402/topup/verify
POST /v1/capabilities/{capability_id}/execute # with X-Rhumb-KeyFirst successful call
If you are choosing between wallet-prefund and x402, anchor on the first call that should feel normal in production.
Use wallet-prefund
Use wallet-prefund when wallet identity matters but you want the steady-state call path to look like normal Layer 2 execution.
Authenticate the wallet once, top up reusable balance, then execute repeat calls with X-Rhumb-Key.
# After wallet verify + top-up, the first successful repeatable call looks like this
curl -X POST "https://api.rhumb.dev/v1/capabilities/{capability_id}/execute" \
+ -H "X-Rhumb-Key: rk_live_..." \
+ -H "Content-Type: application/json" \
+ -d '{"body": {"to": "user@example.com", "subject": "Hello from Rhumb"}}'Use x402 per-call
Use x402 when the payment authorization itself is the product requirement, not just a funding source behind repeat traffic.
Request execution without a governed API key, pay the exact 402 requirement, then retry with X-Payment from the same wallet.
# One-off zero-signup request
curl -X POST "https://api.rhumb.dev/v1/capabilities/{capability_id}/execute" \
+ -H 'X-Payment: {"tx_hash":"0x...","network":"<network-from-402>","wallet_address":"0x..."}' \
+ -H "Content-Type: application/json" \
+ -d '{"body": {"to": "user@example.com", "subject": "Hello from Rhumb"}}'If neither of those stories sounds like you, go back to pricing and start with the governed API-key path.
Your agent needs a wallet that can hold USDC on Base and sign transactions programmatically.
The current public rail is fixed: USDC on Base. Other assets and networks are intentionally not advertised as public options yet.
Keep private keys in your wallet system or secret manager. x402 removes API-key signup, but it does not remove wallet-key security.
Best when the agent should discover, pay for, and execute work without waiting for a human to create an account first.
Useful for ephemeral agents, sandboxes, and evaluation flows where provisioning a governed API key would add avoidable friction.
Each execution carries its own payment event, which is easier to reason about when you want strict request-level budget visibility.
If you need team billing, human-friendly procurement, or a reusable credential for repeated app traffic, standard API-key pricing is usually the better default.
x402 pricing is still cost-plus pricing. Rhumb passes through the upstream call cost and adds a 15 percent margin on top.
That margin covers the agent-payment-specific overhead: verifying payment proof, operating the on-chain settlement path, abuse controls around zero-signup execution, and the managed capability routing behind the request.
Looking for standard API-key plans instead? Go back to main pricing .