circle —version prints a version number. If it does, move on. You’re going to give an AI agent a wallet, fund it with a few test dollars, and watch it pay for an API call on its own: no signups, no credit cards, no API keys. We’ll use Circle’s Agent Stack on the Arc network, and we’ll go slowly. Every command is explained.
If any of these feel fuzzy, that's fine. We'll come back to them as we go; for now, just skim.
It reads instructions, picks a tool, calls the tool, and decides what to do next. Until recently, agents could only do free stuff. We’re about to fix that.
Think of it as a fast, cheap settlement layer where money (specifically USDC, a stablecoin pegged to the US dollar) moves in fractions of a second. Your agent will use it as its bank.
A command-line tool (circle), a wallet system, a marketplace of paid APIs, and some skills for your AI. You give one prompt; the stack handles the plumbing.
Specifically: you'll prompt your agent to research a topic. It will discover a paid research API, pay a few cents in USDC from its own wallet, and bring back an answer with sources.
Each step is small. Most are one command. By the end you’ll have a working agent and, more importantly, a mental model for how this all fits together.
We’ll use testnet USDC (fake money for testing) for this whole tutorial. You won’t spend a real cent. When you’re ready to deploy for real, you swap one flag and your agent uses real USDC. Nothing else changes.
circle command on your machine.The Circle CLI is a single tool you’ll talk to from your terminal. It manages wallets, installs “skills” (knowledge packs) for your AI, and connects to the rest of Circle’s products. You’ll need Node.js v20.18.2 or later installed first.
Open a terminal (Terminal.app on Mac, or whatever you use on Windows/Linux) and run:
$ npm install -g @circle-fin/cli
That installs the circle command globally. Confirm it worked:
$ circle —version
npm pulled the Circle CLI from the public package registry and installed it as a system-wide command. From this point on, your shell knows circle as a binary you can call from anywhere.
On first use, Circle CLI will prompt you to accept its Terms of Use. If you want to handle this non-interactively (for scripts), run circle terms accept.
The $ isn’t something you type. It’s just the prompt symbol your terminal shows you. Type only what comes after it, then press Enter.
circle —version prints a version number. If it does, move on. Agent wallets authenticate by email OTP: Circle emails you a one-time code, you paste it in, and a wallet session is created for you. We’ll do this on testnet first, where everything is free.
$ circle wallet login you@example.com —testnet
Check your inbox, paste the OTP when prompted. Your first agent wallet is provisioned automatically. Now create an additional named wallet for this tutorial:
$ circle wallet create —type agent —testnet
List your wallets on Arc testnet to grab the address you just made:
$ circle wallet list —chain ARC-TESTNET —type agent
Copy the address (the 0x… string). That’s your wallet’s public ID (like an email address for money), and you’ll pass it as —address in every command from here on.
Circle created a managed wallet record on Arc testnet and bound it to your email session. The wallet has a public address (where money is received) but the spending key is held by Circle and only released when you authenticate: same pattern as a custodial exchange account.
It’s a managed wallet your AI agent can use directly through the CLI, without you typing passwords each time. On mainnet, Circle’s compliance and policy controls apply to every transaction (see Step 4).
On testnet, Circle automatically tops your wallet up from a faucet. No amount or method needed. One command:
$ circle wallet fund {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC-TESTNET
Replace 0xYOUR_ADDRESS with the address you copied in Step 2. Now check your balance:
$ circle wallet balance {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC-TESTNET
For mainnet (real money), use —method crypto to fund from another wallet, or —method fiat to use the onramp provider, and pass —amount with the dollar value you want to deposit.
This step is the most important one in the whole tutorial, but a heads-up: spending policies are mainnet-only. On testnet you don’t need them (it’s play money). When you graduate to real USDC, set hard caps the wallet enforces no matter what the agent decides.
The command sets per-tx, daily, weekly, and monthly transfer caps. Limits must satisfy per-tx ≤ daily ≤ weekly ≤ monthly:
$ circle wallet limit set {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC {‘\n’} —policy-type stablecoin {‘\n’} —per-tx 0.50 {‘\n’} —daily 5 {‘\n’} —weekly 20 {‘\n’} —monthly 50
Setting a limit triggers a second email OTP for confirmation. You can also constrain who the wallet can pay (recipient-allowlist) or which contracts it can call (contract-allowlist):
$ circle wallet limit set {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC {‘\n’} —policy-type stablecoin {‘\n’} —rule-type recipient-blocklist {‘\n’} —targets "[0xBAD1,0xBAD2]"
Check your remaining budgets any time:
$ circle wallet limit budget —address 0xYOUR_ADDRESS
You wrote enforcement rules into the wallet itself. From this point, every outbound transfer is checked against these limits before it touches the chain. A misbehaving agent can request a $1,000 transfer all day; the wallet will reject it without ever broadcasting.
These limits are enforced by Circle, not by the AI. Even if the agent tries to spend more, the transaction is rejected. Skip this step on testnet; come back to it before you ever fund the wallet with real USDC.
The Agent Stack works with Claude Code, Cursor, Codex, and other agent frameworks. “Skills” are open-source knowledge packs (from the circlefin/skills catalog) that teach your AI how to use Circle’s tools.
List available skills, then install them into your framework of choice. We’ll use Claude Code:
$ circle skill list
$ circle skill install —tool claude-code
Omitting —name installs every available skill. You can target multiple frameworks at once by repeating the flag: —tool claude-code —tool cursor.
Restart your AI tool (close and reopen Claude Code), then ask it:
> What’s in my Circle wallet on Arc testnet?
It’ll run the right circle wallet balance commands under the hood and report back.
Most useful research APIs cost money. That’s why your AI normally hits a wall and says “I can’t access the internet.” The Agent Stack has two commands for this: circle services search to find services in the marketplace, and circle services pay to actually call one.
Search the marketplace for web-search services:
$ circle services search “web search” {‘\n’} —category WEB_SEARCH_RESEARCH {‘\n’} —limit 10
Inspect what a specific service will charge before you pay:
$ circle services inspect https://api.example.com/search
Now pay for the call. The —max-amount flag is your safety net: the CLI refuses to pay more than that in USDC, no matter what the service quotes:
$ circle services pay https://api.example.com/search {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC-TESTNET {‘\n’} —max-amount 0.05 {‘\n’} -X POST {‘\n’} -d '{"q":"top open-source vector databases 2026"}'
The CLI made a normal HTTPS request, got back an HTTP 402 Payment Required with a price quote, paid that amount in USDC from your wallet on Arc, then re-sent the same request, this time with proof of payment in the headers. The server saw the proof and responded 200 OK with the data. Three round-trips, one command, one charge.
From your AI tool, you can just ask: “Research X using a paid search service. Spend up to $0.05.” The skills installed in Step 5 will do this automatically.
x402 is the HTTP protocol used here. A server replies 402 Payment Required with a price; the client pays in USDC and retries, getting 200 OK. Normal HTTP, with money built in. If payment fails, debug logs land at ~/.circle-cli/payments/.
Every payment your agent made is recorded on Arc. List the transaction history for your wallet:
$ circle transaction list {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC-TESTNET {‘\n’} —limit 10
Filter by direction or state if you want just the paid calls:
$ circle transaction list {‘\n’} —address 0xYOUR_ADDRESS {‘\n’} —chain ARC-TESTNET {‘\n’} —operation transfer {‘\n’} —tx-type outbound {‘\n’} —state confirmed
You can also open console.circle.com in a browser, sign in, and see the same activity in a dashboard. Both views show the same truth.
Three changes: (1) sign in without —testnet, (2) fund with —method crypto or —method fiat and a real amount, (3) set your circle wallet limit set policies before funding. The CLI commands otherwise stay identical: swap ARC-TESTNET for ARC.
You set up a wallet, locked it down, attached it to an AI, and watched the AI pay for something useful. Everything else you build from here is a variation on those four moves.
See every paid service your agent can hit. Sort by price, category, or rating. Most are cents per call.
The full list of circle subcommands with flags and examples. Useful as a bookmark.
Go beyond pay-per-call: transfers, swaps, bridging USDC across chains, batch payments, and more.