Skip to main content

Wallet setup

Pay-per-call access uses one of two protocols:

  • x402 on Base mainnet: pay each call in USDC on Base. The standard agent-payment protocol.
  • MPP on Tempo: pay each call in USDC.e (or pathUSD) on the Tempo network. Lower per-call gas costs.

Both require a wallet you control with a funded balance in the relevant currency.

Pick a wallet flavor​

ProtocolNetworkCurrencyWallet needs
x402Base mainnet (chain ID 8453)USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)Ethereum-style key (secp256k1) with a USDC balance on Base
MPPTempo mainnetUSDC.e (0x20c000000000000000000000b9537d11c60e8b50) or pathUSD (0x20c0000000000000000000000000000000000000)Tempo-style key with USDC.e or pathUSD balance

If you already use an agent wallet (e.g., AgentCash), it likely supports both protocols out of the box; skip to the protocol pages.

Fund a fresh wallet​

x402 / Base​

1. Get a private key. You need a 64-char hex string starting with 0x, 66 chars total.

  • Export from MetaMask: Account menu (three dots) → Account details → Show private key.
  • Export from Coinbase Wallet: Settings → Developer settings → Export private key.
  • Generate a fresh one: echo "0x$(openssl rand -hex 32)". Fund this address before using it.
Use a dedicated wallet

Don't use the private key from a wallet that holds significant funds. Create or designate a wallet specifically for OneSource payments and keep only a small USDC balance on it (a few dollars).

2. Send USDC on Base to its address. Sources:

  • Bridge from Ethereum mainnet via Base Bridge.
  • Withdraw USDC directly to Base from an exchange that supports Base (Coinbase, Kraken, etc.).
  • Swap directly on Base via Uniswap, Aerodrome, or your DEX of choice.

3. Budget. A few dollars of USDC handles thousands of API calls (per-call prices range from $0.001 to $0.010).

Base network only

USDC must be on Base (chain ID 8453), not Ethereum mainnet. Sending USDC on the wrong network to the same address won't work; the funds will sit on the wrong chain. If this happens, use Base Bridge to move them across.

MPP / Tempo​

  1. Generate a Tempo-compatible key.
  2. Obtain USDC.e or pathUSD on Tempo. See Tempo's docs for current bridge and on-ramp options.
  3. Mainnet RPC: https://rpc.tempo.xyz.

What the OneSource REST API does​

When you call an endpoint without a Bearer key, the service returns HTTP 402 Payment Required with two headers offered in parallel:

  • Payment-Required: x402 v2 challenge (price, payTo, chain, asset).
  • WWW-Authenticate: Payment: RFC 7235-style MPP challenge (price, payTo, network, asset).

Your client picks whichever protocol it supports, signs the proof, and resends the request with the Payment-Signature (x402) or Authorization: Payment (MPP) header. The service verifies, settles on-chain, and returns the response, along with a receipt header for your records.

Security best practices​

  • Dedicated wallet: not a wallet that holds real funds.
  • Never commit keys: use env vars, .env in .gitignore, or a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI).
  • Small balance: a few dollars at a time. Top up when it drains.
  • Rotate: if a key was ever shared, logged, or pasted somewhere unexpected, generate a new one and move the balance.
  • Production: secrets manager, not plain env vars.

Troubleshooting​

ProblemFix
Payment required (402) keeps coming backx402 isn't configured; your client isn't signing. Set X402_PRIVATE_KEY (or supply an account to @x402/fetch).
Payment fails / times outWallet has no USDC on Base. Check the balance on BaseScan.
x402 setup failed / "invalid key" in logsKey must start with 0x and be 66 characters (0x + 64 hex).
USDC went to the wrong networkBridge it to Base via bridge.base.org.
Tools work but call returns no payment receiptConfirm Payment-Response header is present; settlement is async and may lag the response slightly.

Next​