Overview
The Circle CLI (
, command
) is a holistic stablecoin CLI for AI agents. It surfaces Circle's full agent-facing stack — wallet management, cross-chain transfers, paid services, Gateway/Nanopayments, smart contracts, spending policy, transaction operations, and Circle's own skill catalog — through one consistent binary. New capabilities ship continuously; this skill is the
front door that introduces the CLI broadly and routes to specialized skills for deep flows.
If the user is doing something narrow (paying for a service, setting up the wallet for the first time, configuring a spending limit), use one of the dedicated skills under Alternatives below. Use this skill when the user is exploring what the CLI can do, when they're doing something that doesn't have its own dedicated skill yet (e.g., bridging, smart contract execution), or when you need a quick orientation across the full command surface.
Install & verify
bash
which circle || command -v circle
circle --version # also surfaces any update notice from Circle's server
If not installed:
bash
npm install -g @circle-fin/cli
Discoverability: always ask
The CLI is self-documenting.
Whenever the agent is unsure about a verb, flag, output shape, or whether a command exists, run on the relevant scope first — don't guess flags, don't invent commands.
bash
circle --help # top-level command list
circle <command> --help # verbs available under a command group
circle <command> <verb> --help # flags, examples, and output format for a specific verb
Examples:
bash
circle --help # all top-level commands (wallet, bridge, services, ...)
circle wallet --help # all verbs under `wallet`
circle services pay --help # flags and examples for `circle services pay`
circle bridge transfer --help # flags and output shape for cross-chain bridging
The CLI ships new commands and flags faster than this document.
Always prefer output over what's documented here when they disagree — the help text reflects the installed version, this skill might lag.
Command surface (high-level)
Top-level command groups, organized by what the user typically wants to do:
Wallet & identity
| Command | What it does |
|---|
| Create a Circle-managed agent wallet on supported EVM chains |
| / / | Email + OTP authentication for the agent wallet (two-step / flow designed for non-interactive agents) |
| List wallets (filter by or , requires ) |
| Show token balances for a wallet on a chain |
| Send USDC (or another supported token) from this wallet to another address on the same chain |
| Open a fiat on-ramp or render a deposit QR code so the user can fund the wallet |
circle wallet limit show/set/reset
| View and change spending policy (mainnet only; set/reset require human OTP) |
| Execute a smart contract function (any chain Circle supports) |
circle terms show/accept/reset
| Manage Circle CLI Terms of Use acceptance (gates wallet commands; never accept on the user's behalf without consent) |
Cross-chain & on-chain operations
| Command | What it does |
|---|
| Bridge USDC to another blockchain via CCTP (~8–20s on fast chains, longer on slow chains) |
| Check progress of a bridge transfer |
| Show CCTP fee schedule |
| Move on-chain USDC into Circle Gateway for nanopayments (eco lands on Polygon ~50-60s for $0.03; direct stays on source chain) |
| Show Gateway / Nanopayments balance per chain |
| Move Gateway balance back to a wallet (same-chain only in v1) |
Paid services (x402)
| Command | What it does |
|---|
| Search the x402 paid-API marketplace by keyword |
| Inspect a paid endpoint — pricing, schema, supported chains, payment scheme |
| Make a paid HTTP request with automatic x402 payment in USDC |
Smart contracts
| Command | What it does |
|---|
| Show Circle contract addresses (USDC token, Gateway, etc.) per chain |
| Read-only ABI query against any deployed contract |
| Execute a write call against any contract (state-changing transaction) |
Transactions
| Command | What it does |
|---|
| Show transaction history for a wallet on a chain |
circle transaction cancel
| Cancel a pending transaction (replace-by-nonce) |
circle transaction accelerate
| Speed up a pending transaction (replace-with-higher-gas) |
Discovery & tooling
| Command | What it does |
|---|
| List supported blockchains with their public RPC defaults |
| Inspect or set per-chain RPC overrides |
circle skill list/info/install/update
| Discover and install Circle skills from the catalog |
This list will keep growing as Circle ships more capabilities.
For any unfamiliar command, run — it is authoritative and reflects the CLI you have installed, not this document.
Common end-to-end flows
For each common flow, there's a dedicated skill that handles the full walkthrough. If the user's task matches one of these, route to the named skill.
| User intent | Skill to use |
|---|
| "Set up Circle / log in / create an agent wallet" | |
| "Pay for a service / call a paid API / use the x402 marketplace" | |
| "Fund my wallet / add USDC / deposit into Gateway" | |
| "Set / change spending limits / view current caps" | |
| "Bridge USDC to another chain (CLI)" | This skill — is the right command |
| "Execute a smart contract / read a contract" | This skill — for writes, for reads |
| "Manage transactions / cancel a pending tx" | This skill — circle transaction list/cancel/accelerate
|
| "Build with Circle SDKs in an app" | One of the SDK-flavored or skills (those are for app code generation, not agent CLI use) |
If the task fits a dedicated skill, hand off there — that skill has the gotchas and decision trees baked in (some, like
and
, also ship
whitelists). If it doesn't, the high-level commands in the table above are enough to get started; use
for flag-level detail.
Bridging and smart contracts
For cross-chain USDC, run
and
circle bridge transfer --help
. For ABI-level read and write calls, run
circle contract query --help
and
circle wallet execute --help
. The CLI's
output is the source of truth for flag positions and ABI conventions — don't guess.
Rules
- ALWAYS run when you're unsure about flags or output shape — the help text is authoritative and reflects the installed CLI version, not this skill.
- ALWAYS pass for commands whose output the agent needs to parse.
- ALWAYS pass when running , , , , , , and . If unsure which chain to use, run first.
- NEVER accept Circle's Terms of Use on the user's behalf — even with . The agent MUST show the live Terms (from
circle terms show --init --output json
- NEVER guess or hardcode the user's email address for .
- NEVER store, log, or display private keys, OTP codes, or session tokens beyond their immediate use.
- Treat the CLI as the source of truth for the user's wallet state. Don't infer balances or transaction status — query the CLI fresh.
- Default to mainnet for the agent wallet flow unless the user explicitly requests testnet. Spending policy is mainnet-only.
- For routine permissionless tasks the user has already asked for, act first and summarize after — don't ask for re-confirmation on routine read-only operations like or .
Staying current
Surface these to the user when relevant — start of session, after a long gap, or when a command behaves unexpectedly.
bash
# Check the CLI version (also surfaces any update notice from Circle's server)
circle --version
# Update the CLI
npm install -g @circle-fin/cli@latest
# Update Circle's installed skills (pick the host matching the runtime: claude-code, cursor, codex, opencode, amp, or another tool name)
circle skill update --tool <tool>
# Universal fallback (works on any host the open `skills` registry supports)
npx skills update
These commands are idempotent (re-running is safe). But
,
, and
all mutate the user's system — ask the user before running any of them, don't run them unprompted.
Reference Links
Alternatives
Trigger the
skill instead when:
- The user wants to install the CLI, log in, accept Terms, create a wallet, check balance, or otherwise bootstrap the agent wallet.
- The user mentions , , .
Trigger the
skill instead when:
- The user wants to call, pay for, or use a paid x402 service.
- The user mentions
circle services search/inspect/pay
Trigger the
skill instead when:
- The user wants to add USDC to the wallet (fiat on-ramp, crypto deposit, Gateway deposit, withdrawal).
- The user mentions deposit, fiat on-ramp, fiat purchase, QR-code transfer, or Gateway deposit.
Trigger the
skill instead when:
- The user wants to view, set, or reset spending limits on the agent wallet.
- The user mentions per-tx / daily / weekly / monthly caps, spending policy, or wallet rules.
Trigger one of the SDK-flavored skills (
,
,
,
,
,
use-developer-controlled-wallets
,
use-user-controlled-wallets
,
,
use-smart-contract-platform
,
) instead when:
- The user is writing application code that uses Circle SDKs (e.g., , ,
@circle-fin/developer-controlled-wallets
- The user wants architectural guidance on choosing a wallet type, integrating CCTP into a web app, or deploying contracts via Circle's Smart Contract Platform.
The CLI is for agent-flow use (an AI agent operating on behalf of a user). The SDK skills are for code-generation use (the agent is helping a developer write application code).
DISCLAIMER: This skill is provided "as is" without warranties, is subject to the
Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository
README.