cli

Circle's CLI for setting up an agent wallet, funding it with USDC, and using it for stablecoin-powered workflows.

Learn more at agents.circle.com.

Quickstart

Install the CLI and login.

npm install -g @circle-fin/cli
circle --version
circle wallet login <email>
# Enter the OTP code sent to your email when prompted
circle wallet status

Logout

To clear the current session:

circle wallet logout

Check or Create a Wallet

Check the current wallet state on BASE:

circle wallet list --chain BASE --type agent --output json

The initial agent wallets are provisioned during login. Use circle wallet list first to inspect what is already available.

Create an additional wallet only if needed:

circle wallet create

Check the wallet balance:

circle wallet balance --address <addr> --chain BASE --output json

Discover Skills

Once the wallet is set up, use the CLI to discover other Circle skills:

circle skill list
circle skill info --name use-circle-cli

Install a skill for the current tool:

circle skill install --tool claude-code --name use-circle-cli
# or --tool cursor, --tool codex

Commands

Blockchain

Blockchain commands let you inspect supported chains and configure per-chain RPC settings.

# Inspect blockchain RPC configuration
circle blockchain config --chain BASE
# List supported blockchains
circle blockchain list

Bridge

Bridging moves USDC from one supported blockchain to another with CCTP.

# Show the fee for a bridge route
circle bridge get-fee MATIC --chain BASE
# Check the status of a bridge transfer
circle bridge status <burn-tx-hash> --chain BASE
# Bridge USDC from BASE to Polygon
circle bridge transfer MATIC --amount 1.0 --address <addr> --chain BASE

Contract

Contract queries let you look up Circle contract addresses and read onchain contract state without submitting a transaction.

# Show Circle contract addresses on a chain
circle contract address usdc --chain BASE
# Query read-only contract state
circle contract query "balanceOf(address)" <addr> --contract <contract> --chain BASE --output json

Gateway

Gateway is used for nanopayments, including depositing wallet funds into a Gateway balance and managing that balance.

# Show the current Gateway balance across all settlement chains
circle gateway balance --address <addr> --chain BASE --all
# Deposit wallet USDC into Gateway for nanopayments
circle gateway deposit --amount 0.5 --address <addr> --chain BASE --method eco
# Withdraw funds from Gateway back to a wallet
circle gateway withdraw --amount 0.1 --address <addr> --chain BASE-SEPOLIA

Services

Services lets you discover paid x402 endpoints, inspect pricing, and estimate or execute paid requests with the wallet.

# Inspect a paid endpoint and its pricing
circle services inspect https://api.example.com/data
# Estimate a paid request before sending it
circle services pay https://api.example.com/data --address <addr> --chain BASE --estimate
# Search for paid x402 services
circle services search "web search"

Transaction

Transaction commands help manage pending transactions after they have been submitted.

# Speed up a pending transaction
circle transaction accelerate <transaction-id> --chain BASE
# Cancel a pending transaction
circle transaction cancel <transaction-id> --chain BASE

Wallet

The wallet flow covers sending USDC, swapping into supported assets, executing onchain actions, and managing spending policy from a wallet address.

# Execute a write call from the wallet
circle wallet execute "approve(address,uint256)" <spender> <amount> --contract <contract> --address <addr> --chain BASE --estimate
# Swap tokens with Circle Stablecoin Kits
circle wallet swap --chain BASE --from USDC --to WETH --amount 1.0 --address <addr>
# Move USDC between wallets
circle wallet transfer <recipient> --amount 1.0 --address <addr> --chain BASE

Limit

Limit controls spending policy on an agent wallet, including remaining budget, transfer limits, blocklists, and resetting custom policies. Policy writes require OTP confirmation.

# Show remaining EVM-wide rolling-window policy + budget (daily / weekly / monthly)
circle wallet limit budget --address <addr>
# Set a custom transfer limit — OTP-gated, ephemeral human session
circle wallet limit set --address <addr> --chain BASE \
  --policy-type stablecoin --per-tx 100 --daily 100 --weekly 100 --monthly 100
 # Block specific recipient addresses — OTP-gated
circle wallet limit set --address <addr> --chain BASE \
  --policy-type stablecoin --rule-type recipient-blocklist \
  --targets "[0xBAD1,0xBAD2]"
# Block specific contracts on the contract-execution path — OTP-gated
circle wallet limit set --address <addr> --chain BASE \
  --policy-type contract --rule-type contract-blocklist \
  --targets "[0xCONTRACT]"
# Reset every custom policy on this (wallet, chain) back to defaults — OTP-gated
circle wallet limit reset --address <addr> --chain BASE

External Wallet

Import a local wallet from a private key or mnemonic phrase:

circle wallet import my-wallet --private-key || circle wallet import my-wallet --mnemonic
circle wallet list --chain BASE --type local

Imported local wallets can be used with wallet-based commands such as transfer, contract execution, bridge, and Gateway flows where local wallet support is available.

Testnet Funds

Use a separate testnet login session when you want to try the CLI without using mainnet funds:

circle wallet login <email> --testnet
circle wallet list --chain BASE-SEPOLIA

Testnet and mainnet sessions are stored separately.

Update

To update to a new version of the CLI, run:

circle update

This checks for a newer published version and, if one is available, prompts before running npm install -g @circle-fin/cli@latest for you. Pass --yes to skip the prompt (useful in scripts and CI). If you'd rather upgrade by hand, the npm command above works directly.

Help

Use --help on any command group to see the full list of supported verbs, flags, and examples.

circle --help
circle wallet --help
circle gateway --help
circle services --help

Legal

By using the Circle CLI, you agree to the Terms of Use and Privacy Policy.