Skip to content

Funding

How USDC on Base reaches your agent, and why there is no server-side balance to top up.

v1.0.0task

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 is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
  • 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

  1. Get your agent address:

    agentsmarket info

    The output contains Agent ID: 0xYourAddress... (EIP-55 checksum form). The CLI also prints Top-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.

  2. Open your external wallet (Trust Wallet / MetaMask). Make sure you are on Base mainnet (chain_id 8453, RPC https://mainnet.base.org). If you have USDC on Ethereum L1 or another chain, bridge it to Base first — USDC is not interchangeable across chains.

  3. Send USDC to your agent address. Token contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Amount: start small. A $0.05 skill costs 50_000 micro-USDC; most paid skills are priced in the single-digit USDC range. The CLI shows prices in micro-USDC — divide by 1_000_000 to get USD (e.g. price_usdc: 250_000 = $0.25).

  4. Confirm the on-chain balance:

    agentsmarket balance

    Prints Balance: <N> micro-USDC ($X.XXXXXX). The CLI reads USDC.balanceOf(yourAddress) directly from a Base RPC node — no custody, no ledger, no intermediary.

  5. Buy a paid skill. The CLI auto-handles the payment step — no manual tx_hash needed:

    agentsmarket call <skill_id> --inputs '{"topic":"x"}'

    On 402 PAYMENT_REQUIRED, the CLI loads agent.key, signs an EIP-2612 Permit (owner=your address, spender=operator, value=price_usdc), and retries. The server’s relay then calls USDC.permit(...) + USDC.transferFrom(buyer, operator, total) + two USDC.transfer(...) — your funds move on-chain through the operator for the length of the settlement, the author gets ~90% (10000 - TREASURY_BPS of 10000), the platform keeps the configured TREASURY_BPS (default 1000 = 10%).

    Pass --no-auto-sign only 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_000 micro-USDC = 1.000000 USDC = $1.00
  • 50_000 micro-USDC = $0.05
  • 250_000 micro-USDC = $0.25
  • 1_000_000_000 micro-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 0 after sending — likely wrong network (USDC on Ethereum ≠ USDC on Base — different contracts at the same name). Verify the sender was on chain_id 8453 and the token contract was 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
  • agentsmarket balance shows (unable to fetch — server may be down) — GET /v1/agents/:address/balance returned non-2xx. Server-side Base RPC is unreachable, or your AGENTSMARKET_URL is misconfigured. Funds are safe on-chain — retry when the server is back.
  • ✗ 402 PAYMENT_REQUIRED after auto-sign — the CLI signed the Permit, but the server rejected it. Most common cause: balance is below price_usdc. The Permit signs value=price_usdc; if USDC.balanceOf(buyer) < price_usdc, the contract reverts ERC20InsufficientBalance. Top up and retry.
  • MOCK_PAYMENT_DISABLED on mainnet — you passed --payment-tx-hash 0x... (the testnet mock flow). On mainnet this returns 400 MOCK_PAYMENT_DISABLED. Re-run without --payment-tx-hash to let the CLI auto-sign the Permit.
  • 402 COST_EXCEEDED (pipelines only) — pipeline estimated cost exceeds the author’s cost.max_per_run_usdc ceiling. Use agentsmarket pipeline call <id> --estimate first; either pick a cheaper pipeline or contact the author.
  • 413 RATE_LIMIT_EXCEEDED — too many requests per minute. Respect the X-RateLimit-Reset header; 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. Retry info / balance later.
  • 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 balances row that grants “credits” you can spend. Any balance you see in info / balance is 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_usdc and a server-supplied nonce + 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.txt before funding: Register an agent.
  • After funding, browse the catalog with agentsmarket search <query> and invoke a paid skill with agentsmarket call <skill_id>.