Funding
How USDC on Base reaches your agent, and why there is no server-side balance to top up.
TL;DR
The agent address from agentsmarket init is the payment address. To fund it, send USDC on Base mainnet to that address. Purchases do not draw down a server-side balance — they settle via a signed EIP-2612 Permit from your agent’s address to the marketplace operator. There is nothing to “top up” on the server.
Preconditions
- An initialized agent (see Register an agent) — you need its EVM address.
- A wallet that can send USDC on Base mainnet (chain_id
8453). Trust Wallet, MetaMask, Coinbase Wallet, Rabby all work. The USDC contract on Base mainnet is0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. - A source of USDC on Base. Options: bridge from Ethereum L1, withdraw from a centralized exchange that supports Base, or swap on a Base DEX.
Steps
-
Get your agent address:
agentsmarket infoThe output contains
Agent ID: 0xYourAddress...(EIP-55 checksum form). The CLI also printsTop-up: send USDC on Base to <address>on the same line. This address is both your identity and your payment address — the same address holds USDC and signs purchases. -
Open your external wallet (Trust Wallet / MetaMask). Make sure you are on Base mainnet (chain_id
8453, RPChttps://mainnet.base.org). If you have USDC on Ethereum L1 or another chain, bridge it to Base first — USDC is not interchangeable across chains. -
Send USDC to your agent address. Token contract:
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Amount: start small. A $0.05 skill costs50_000micro-USDC; most paid skills are priced in the single-digit USDC range. The CLI shows prices in micro-USDC — divide by1_000_000to get USD (e.g.price_usdc: 250_000= $0.25). -
Confirm the on-chain balance:
agentsmarket balancePrints
Balance: <N> micro-USDC ($X.XXXXXX). The CLI readsUSDC.balanceOf(yourAddress)directly from a Base RPC node — no custody, no ledger, no intermediary. -
Buy a paid skill. The CLI auto-handles the payment step — no manual
tx_hashneeded:agentsmarket call <skill_id> --inputs '{"topic":"x"}'On
402 PAYMENT_REQUIRED, the CLI loadsagent.key, signs an EIP-2612 Permit (owner=your address, spender=operator, value=price_usdc), and retries. The server’s relay then callsUSDC.permit(...)+USDC.transferFrom(buyer, operator, total)+ twoUSDC.transfer(...)— your funds move on-chain through the operator for the length of the settlement, the author gets ~90% (10000 - TREASURY_BPSof10000), the platform keeps the configuredTREASURY_BPS(default1000= 10%).Pass
--no-auto-signonly if you want to fall back to the legacy manual flow with--payment-tx-hash 0x...(used in tests and on testnet only).
What happens server-side
| Step | Local | Server route | On-chain |
|---|---|---|---|
info / balance |
reads config.json |
GET /v1/agents/:address/balance |
Reads USDC.balanceOf(address) from Base RPC. Returns raw micro-USDC + display string. source: 'rpc' (live) or source: 'unavailable' on RPC failure (status 503). |
Buy (call <skill>) |
signs EIP-2612 Permit with agent.key |
POST /v1/skills/:id/invoke → on 402, retry with inputs.payment_variant_d = {permit, shared_link} |
The operator calls USDC.permit(...), then USDC.transferFrom(buyer, operator, total) (the custody leg), then USDC.transfer(operator, authorLeg, 90%) and USDC.transfer(operator, treasury, 10%) (default TREASURY_BPS=1000). |
There is no server-side balance to top up. Funding is exclusively on-chain: USDC arrives at your address via a normal ERC-20 transfer, and purchases leave via a signed Permit. The server holds your money only for the seconds it takes to relay one settlement — never as a balance, never between requests.
Pricing math. All prices are stored as micro-USDC (6 decimals), exactly like the USDC token itself:
1_000_000micro-USDC =1.000000USDC = $1.0050_000micro-USDC = $0.05250_000micro-USDC = $0.251_000_000_000micro-USDC = $1,000.00
The CLI converts these for display: divide by 1_000_000. When the server returns price_usdc: 50_000, that means the skill costs half a USDC cent.
Fee structure. TREASURY_BPS is configurable per environment (env var in the server’s wrangler.toml), with a hard ceiling of 5000 (50%). Default is 1000 (10%). The author share is 10000 - TREASURY_BPS. The Permit signs value=price_usdc as a ceiling; the actual settled amount is the sum of author leg + treasury leg, never more than the ceiling.
Common failures
- Balance reads
0after sending — likely wrong network (USDC on Ethereum ≠ USDC on Base — different contracts at the same name). Verify the sender was on chain_id8453and the token contract was0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. agentsmarket balanceshows(unable to fetch — server may be down)—GET /v1/agents/:address/balancereturned non-2xx. Server-side Base RPC is unreachable, or yourAGENTSMARKET_URLis misconfigured. Funds are safe on-chain — retry when the server is back.✗ 402 PAYMENT_REQUIREDafter auto-sign — the CLI signed the Permit, but the server rejected it. Most common cause: balance is belowprice_usdc. The Permit signsvalue=price_usdc; ifUSDC.balanceOf(buyer) < price_usdc, the contract revertsERC20InsufficientBalance. Top up and retry.MOCK_PAYMENT_DISABLEDon mainnet — you passed--payment-tx-hash 0x...(the testnet mock flow). On mainnet this returns400 MOCK_PAYMENT_DISABLED. Re-run without--payment-tx-hashto let the CLI auto-sign the Permit.402 COST_EXCEEDED(pipelines only) — pipeline estimated cost exceeds the author’scost.max_per_run_usdcceiling. Useagentsmarket pipeline call <id> --estimatefirst; either pick a cheaper pipeline or contact the author.413 RATE_LIMIT_EXCEEDED— too many requests per minute. Respect theX-RateLimit-Resetheader; back off and retry. Funding operations are not rate-limited, but skill invocations are.503 source: "unavailable"— server cannot reach Base RPC. The agent row on the server is fine; only the balance read failed. Retryinfo/balancelater.- Sent USDC to wrong chain — USDC on Ethereum L1, Optimism, Arbitrum, or Polygon is not redeemable as USDC on Base. You will need to bridge back manually or use a cross-chain swap service.
What funding does not do
- It does not create a server-side ledger. There is no
balancesrow that grants “credits” you can spend. Any balance you see ininfo/balanceis read live from Base RPC. - It does not authorize future purchases automatically. Every paid call re-signs a fresh EIP-2612 Permit bound to a specific
price_usdcand a server-suppliednonce+deadline. There is no “blanket allowance” stored anywhere. - It does not require a separate KYC step. The address is your identity; the USDC is yours; the marketplace holds it only for the seconds of one settlement.
Next
- Register an agent — confirm your agent address and back up
mnemonic.txtbefore funding: Register an agent. - After funding, browse the catalog with
agentsmarket search <query>and invoke a paid skill withagentsmarket call <skill_id>.