What onboarding involves

Onboarding an AI agent to stablecoin payments is the journey from an agent that cannot touch money to one that transacts in USDC on Base, safely. Each step is small, and there are dedicated guides for each, but doing them in the right order, on testnet, before real funds are involved, is what turns a pile of how-tos into a smooth path. This page is the connective overview: the stages, what each gives you, and the order to do them in.

It links out to the deep guide for each stage rather than repeating them. If you want the full detail on any one step, follow its link; if you want the map, stay here. The agent wallets product page is the broader reference.

The five stages

Onboarding is five stages, and the order matters because each builds on the last.

Create the agent, which provisions its USDC wallet on Base. Fund that wallet, so it has something to spend. Make a first payment, to prove the agent can transact. Set a spend limit, so it cannot transact beyond what you intend. And verify its identity, so counterparties trust it. Create and fund come first because nothing works without them; the limit comes before going live because real money without a cap is the one thing you must not ship; verification comes when the agent will face counterparties. Walk them on testnet, then promote to mainnet by switching keys.

Prerequisites

• A Blockchain0x account.
• A sk_test_ API key for the testnet walk-through.
• Node 18 or newer. The SDK targets >=18.

export B0X_API_KEY=sk_test_...   # sk_test_ -> Base Sepolia

Stage 1: create and fund

Creating the agent provisions its wallet; funding it gives the agent something to spend.

import { createClient } from "@blockchain0x/node";

const client = createClient({ apiKey: process.env.B0X_API_KEY! });
const agent = await client.agents.create({ name: "my-agent" });
console.log(agent.id, agent.network); // agt_..., "testnet"

A wallet.deployed webhook fires when the wallet is live. Then fund it: copy the wallet address from the dashboard or the agent's public profile and send it test USDC from a public Base Sepolia faucet. The full wallet detail is in how-to-add-wallet-to-my-agent. At the end of this stage the agent exists and has a balance.

Stage 2: first payment

Prove the agent can pay. Wrap the x402 client and make one paid call.

import { createX402Client } from "@blockchain0x/x402/client";

const fetchWithPay = createX402Client({ sdk: client });
const res = await fetchWithPay("https://api.example.com/paid-endpoint");

On a 402, the client settles in USDC and retries. Watch it happen; that first settled call is the milestone that says the agent is genuinely transacting, not just configured. The framework-specific versions are in how-to-add-usdc-payments-to-ai-agent. At the end of this stage the agent has paid for something.

Stage 3: bound and verify

Two stages that turn a working agent into a safe, trusted one. First, set a spend limit in the dashboard, a per-transaction cap and a per-period allowance, which the wallet enforces before settlement. Read it back to confirm:

const res = await fetch(
  `https://api.blockchain0x.com/v1/agents/${agent.id}/spend-permissions`,
  { headers: { Authorization: `Bearer ${process.env.B0X_API_KEY!}` } },
);
const permissions = await res.json(); // per_tx_wei, allowance_wei, period_seconds

This is the stage you do not skip before mainnet. Then, if the agent will face counterparties, verify its identity: set a display name and earn at least the email badge on its public profile, so a payer or paying agent can trust it. At the end of this stage the agent is bounded and, where it matters, trusted.

The onboarding checklist

If you want a single thing to work through, here is the checklist the five stages reduce to, in order:

• Create the agent and confirm it has an id and a wallet.
• See the wallet.deployed event (or confirm wallet status in the dashboard).
• Fund the wallet with test USDC from a Base Sepolia faucet.
• Make one paid call through createX402Client and watch it settle.
• Set a per-transaction cap and a period allowance in the dashboard.
• Read the limit back over the API and confirm it is what you intended.
• Set the agent's display name and earn at least the email verification badge.
• Run the failure paths once: an over-limit call refused, an empty-wallet call handled.
• Swap the sk_test_ key for sk_live_ and re-check the limit on the live agent.

Work top to bottom on testnet, and only the last line touches mainnet. Each item is small, and the list is the difference between an agent that "sort of" pays and one you have actually proven, bounded, and made trustworthy before real money is involved.

Go live

When all five stages work on Base Sepolia, going live is a key swap. Replace the sk_test_ key with a sk_live_ one and the agent transacts in real USDC on Base mainnet. The only new variable is that the money is real, which is why you walked the whole path on testnet first.

Two checks before you flip it: re-confirm the spend limit on the live agent, since limits are per agent and the testnet limit does not carry over, and add a boot-time key-prefix check so a test key never runs in production. With the stages proven on testnet, the live agent is the same agent doing the same thing with real funds, bounded the same way.

What good looks like

It helps to know when onboarding is actually done, because "it made a payment once" is not the bar. A properly onboarded agent has four properties you can point at. It transacts: a real paid call settled in USDC and returned. It is bounded: a spend limit is set and enforced, and you have seen an over-limit call get refused. It is accountable: its public profile has a name and at least one verification, so a counterparty can check it. And it fails safely: an empty wallet or a refused payment produces a clean, handled outcome rather than a loop or a crash.

If all four hold on the live agent, onboarding is complete and you can let it run. If any one is missing, that is the gap to close before you trust it with volume. The most common gap is the last one, failing safely, because it is the only property you cannot confirm by a single happy-path test; you have to deliberately push the agent into failure to know it handles failure. An agent that has all four is one you can walk away from, which is the whole point of onboarding it properly rather than just getting it to pay once.

Common pitfalls

Three traps onboarding an agent.

Going to mainnet without a spend limit. The limit is the one stage you cannot skip before real money. Set it on testnet and re-set it on the live agent.

Skipping the testnet walk. Doing the five stages first on Base Sepolia, for free, is how you find problems before they cost anything. Do not onboard straight on mainnet.

Treating verification as optional for a market-facing agent. If counterparties decide whether to transact with the agent, an unverified profile caps how far it gets. Earn at least the email badge.

What to ship today

Walk the five stages on Base Sepolia: create and fund the agent, make a first paid call, set a spend limit, and earn a verification badge. Confirm each works, then swap the sk_test_ key for sk_live_ and re-check the limit. The deep guides for each stage are linked above. Pricing is on the pricing page.