Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

Circle CLI follows a circle <resource> <verb> [options] pattern. All commands support --help for inline documentation.

Global options

OptionDescription
--output json|text|yamlSet output format. Defaults to text.
-q, --quietMinimal output, suitable for piping.
-h, --helpShow help for any command.
-v, --versionPrint the Circle CLI version and exit.

Wallet commands

Manage your agent wallet.

circle wallet login

Authenticate using email OTP to create or access an agent wallet session. Syntax
circle wallet login <email> [options]
circle wallet login <email> --init
circle wallet login --request <id> --otp <code>
Options
OptionDescription
--typeWallet type. Defaults to agent.
--testnetAuthenticate against testnet. Sessions are stored separately from mainnet.
--initTwo-step login for scripts and AI agents. Sends the OTP and returns a request ID. Pair with --request.
--request <id>Complete a --init login. Combine with --otp <code>.
--otp <code>One-time password for the request ID. Required with --request. Codes are alphanumeric (for example, B1X-123456).
Examples
# Interactive login (mainnet)
circle wallet login you@example.com

# Two-step login for scripts and AI agents
circle wallet login you@example.com --init
circle wallet login --request <request-id> --otp B1X-123456
Request IDs from --init are stored at ~/.circle/login-requests/<id>.json, expire after 10 minutes, and are deleted after a successful --request.

circle wallet logout

Clear stored credentials for the current session. Syntax
circle wallet logout [options]
Options
OptionDescription
--typeClear credentials for a specific wallet type (for example, agent).
Example
circle wallet logout --type agent

circle wallet status

Show the current authentication status and session details. Syntax
circle wallet status [options]
Options
OptionDescription
--typeShow status for a specific wallet type (for example, agent).
Example
circle wallet status --type agent

circle wallet create

Create an additional wallet, separate from the wallets provisioned during login. Each user can have at most 5 agent wallets. Syntax
circle wallet create [options]
Options
OptionDescription
--typeWallet type: agent (default) or local.
--testnetCreate a testnet wallet. Omit for mainnet.
--idempotency-keyUnique key to prevent duplicate wallet creation on retry.
Example
circle wallet create --type agent --testnet

circle wallet list

List wallets associated with your account. Syntax
circle wallet list --chain <chain> [options]
Options
OptionDescription
--chainBlockchain to list wallets on.
--typeFilter by wallet type: agent or local.
Example
circle wallet list --chain ARC-TESTNET --type agent

circle wallet limit

Show spending policy limits for an agent wallet. Mainnet only. Syntax
circle wallet limit --address <addr> --chain <chain>
Options
OptionDescription
--addressAgent wallet address.
--chainMainnet blockchain. Testnet chains not supported.
Examples
circle wallet limit --address 0x... --chain BASE
circle wallet limit --address 0x... --chain BASE --output json

circle wallet limit set

Set a custom spending policy for an agent wallet. Requires a second email OTP to confirm the change. Mainnet only. Use --rule-type to choose the kind of policy:
  • transfer-limit (default): cap how much USDC the wallet can transfer per transaction or over a rolling time window. Set with --per-tx, --daily, --weekly, --monthly.
  • recipient-allowlist / recipient-blocklist: allow or block transfers to specific recipient addresses. Set with --targets.
  • contract-allowlist / contract-blocklist: allow or block contract interactions with specific addresses. Set with --targets.
Syntax
# Transfer limit (default)
circle wallet limit set --address <addr> --chain <chain> \
  --policy-type <type> \
  [--per-tx <amount>] [--daily <amount>] [--weekly <amount>] [--monthly <amount>] \
  [options]

# Allowlist or blocklist
circle wallet limit set --address <addr> --chain <chain> \
  --policy-type <type> \
  --rule-type <recipient-allowlist|recipient-blocklist|contract-allowlist|contract-blocklist> \
  --targets "[0xAddr1,0xAddr2]" \
  [options]
Options
OptionDescription
--addressAgent wallet address.
--chainMainnet blockchain. Testnet blockchains are not supported.
--policy-typePolicy category: stablecoin for transfer-based rules, contract for contract-based rules. Auto-set when --rule-type is a contract rule.
--rule-typeRule shape: transfer-limit (default), recipient-allowlist, recipient-blocklist, contract-allowlist, or contract-blocklist.
--per-txPer-transaction spending cap. Used with --rule-type transfer-limit.
--dailyDaily rolling-window cap. Used with --rule-type transfer-limit.
--weeklyWeekly rolling-window cap. Used with --rule-type transfer-limit.
--monthlyMonthly rolling-window cap. Used with --rule-type transfer-limit.
--targetsBracketed comma-separated list of EVM addresses (for example, "[0xA,0xB]"). Required for allowlist and blocklist rule types. Validated client-side.
--emailEmail address for the confirmation OTP. Defaults to the agent session email.
Transfer limits must satisfy: per-transaction ≤ daily ≤ weekly ≤ monthly.
Examples
# Transfer limits
circle wallet limit set \
  --address 0x... \
  --chain BASE \
  --policy-type stablecoin \
  --per-tx 100 \
  --daily 500 \
  --weekly 2000 \
  --monthly 5000

# Recipient blocklist
circle wallet limit set \
  --address 0x... \
  --chain BASE \
  --policy-type stablecoin \
  --rule-type recipient-blocklist \
  --targets "[0xBAD1,0xBAD2]"

circle wallet limit reset

Reset all custom spending policies for an agent wallet back to defaults. Requires a second email OTP to confirm. Mainnet only. Syntax
circle wallet limit reset --address <addr> --chain <chain> [options]
Options
OptionDescription
--addressAgent wallet address.
--chainMainnet blockchain. Testnet chains not supported.
--yes, -ySkip the confirmation prompt.
Example
circle wallet limit reset --address 0x... --chain BASE --yes

circle wallet limit budget

Show remaining spending budgets for an agent wallet. Displays per-transaction limits and rolling-window remaining amounts (daily, weekly, monthly). Budgets are EVM-wide and not blockchain-specific. Mainnet only. Syntax
circle wallet limit budget --address <addr>
Options
OptionDescription
--addressAgent wallet address.
Example
circle wallet limit budget --address 0x...

circle wallet balance

Show the token balance for a wallet address on a given blockchain. Syntax
circle wallet balance --address <addr> --chain <chain> [options]
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
--rpc-urlRPC endpoint override. Required for local wallets without a configured default.
Example
circle wallet balance --address 0x... --chain BASE

circle wallet fund

Add funds to a wallet by transfer from another wallet (crypto), through a fiat onramp, or from the testnet faucet. Syntax
circle wallet fund --address <addr> --chain <chain> --amount <usdc> --method <crypto|fiat> [options]
Options
OptionDescription
--addressWallet address to fund.
--chainBlockchain.
--amountAmount to fund. Ignored on testnet.
--tokenToken: usdc (default), eth, native.
--methodFunding method: crypto or fiat. Required on mainnet. Omit on testnet, where wallets auto-fund from the Circle faucet.
--export <dir>With --method crypto, write a PNG QR code into <dir> instead of printing it to the terminal.
--openOpen the result in your browser. With --method fiat, opens the onramp provider. With --method crypto, opens an HTML page with the QR code.
--no-openPrint the onramp URL without opening it. Used with --method fiat only.
Examples
# Fund with crypto from another wallet
circle wallet fund --address 0x... --chain BASE --amount 10 --method crypto

# Fund with fiat through the onramp provider
circle wallet fund --address 0x... --chain BASE --amount 10 --method fiat

# Testnet auto-funded from faucet (omit --method and --amount)
circle wallet fund --address 0x... --chain ARC-TESTNET

circle wallet transfer

Transfer tokens from a wallet to another address. Syntax
circle wallet transfer <toAddress> --amount <amount> --address <addr> --chain <chain> [options]
Arguments
ArgumentDescription
<toAddress>Recipient address.
Options
OptionDescription
--amountAmount to transfer.
--addressSource wallet address.
--chainBlockchain.
--tokenToken contract address. Omit to use USDC.
--rpc-urlRPC endpoint override. Required for local wallets without a configured default.
--estimateShow estimated fees without submitting the transfer.
Example
circle wallet transfer 0xRecipient --amount 5.0 --address 0x... --chain ARC-TESTNET

circle wallet swap

Swap one token for another. Requires an agent wallet. Arc Testnet is the only testnet supported. Syntax
circle wallet swap <sellToken> <sellAmount> <buyToken> [<buyAmount>] --address <addr> --chain <chain> [options]
Arguments
ArgumentDescription
<sellToken>Token to sell. Use a symbol (for example, EURC) or contract address.
<sellAmount>Amount to sell.
<buyToken>Token to buy. Use a symbol (for example, USDC) or contract address.
[<buyAmount>]Minimum acceptable output (stop-limit). Omit when using --quote.
Options
OptionDescription
--addressAgent wallet address. Optional when using --quote.
--chainBlockchain.
--quoteGet a price quote without executing the swap. Does not require wallet ownership or buyAmount.
--slippage-bpsMaximum slippage in basis points (for example, 50 = 0.5%).
--idempotency-keyUnique key to prevent duplicate swaps on retry.
Examples
circle wallet swap EURC 100 USDC 99.5 --address 0x... --chain ARC-TESTNET
circle wallet swap EURC 100 USDC --chain ARC-TESTNET --quote

circle wallet sign message

Sign a plain text or hex-encoded message with your wallet. Syntax
circle wallet sign message <message> --address <addr> --chain <chain> [options]
Arguments
ArgumentDescription
<message>Message to sign (plain text or hex).
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
--hexMessage is hex-encoded (must start with 0x).
Example
circle wallet sign message "hello world" --address 0x... --chain ARC-TESTNET

circle wallet sign typed-data

Sign EIP-712 typed data with your wallet. Syntax
circle wallet sign typed-data <data> --address <addr> --chain <chain>
Arguments
ArgumentDescription
<data>EIP-712 typed data as a JSON string.
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
Example
circle wallet sign typed-data '{"types":{...},"primaryType":"Mail","domain":{...},"message":{...}}' \
  --address 0x... \
  --chain ARC-TESTNET

circle wallet execute

Execute a smart contract write function from a wallet. Syntax
circle wallet execute <abiFunctionSignature> [<abiParameters>...] \
  --contract <addr> \
  --address <addr> \
  --chain <chain> \
  [options]
Arguments
ArgumentDescription
<abiFunctionSignature>ABI function signature (for example, approve(address,uint256)).
[<abiParameters>...]ABI parameters, space-separated.
Options
OptionDescription
--contractContract address.
--addressWallet address.
--chainBlockchain.
--amountNative token value to send with the call. Defaults to 0.
--rpc-urlRPC endpoint override. Required for local wallets without a configured default.
--estimateShow estimated fees without submitting the transaction.
Example
circle wallet execute "approve(address,uint256)" 0xSpender 1000000 \
  --contract 0xUSDC \
  --address 0x... \
  --chain ARC-TESTNET

circle wallet import

Import a local wallet from a private key or mnemonic phrase. Stored using the Open Wallet Standard at ~/.ows/wallets/<name>.
Local wallets bypass Circle’s compliance and safety controls. Spending policies, OFAC screening, and audit logging only apply to agent wallets.
Syntax
circle wallet import <name> [--private-key | --mnemonic]
Options
OptionDescription
--private-keyImport from a private key. You’ll be prompted to enter the key securely.
--mnemonicImport from a mnemonic phrase. You’ll be prompted to enter it securely.
Do not pass your private key or mnemonic as a command-line argument or environment variable in plain text. Enter it at the prompt or use a secrets manager.
Example
circle wallet import my-wallet --private-key

Services commands

Discover and pay for x402-compatible API services. Search for available services by keyword. Omit the query to list all services. Syntax
circle services search [<query>] [options]
Arguments
ArgumentDescription
[<query>]Optional search keyword or phrase. Omit to list all results.
Options
OptionDescription
--categoryFilter by category (for example, FINANCIAL_ANALYSIS, WEB_SEARCH_RESEARCH).
--typeFilter by service type.
--limitMaximum number of results to return. Defaults to 50.
--offsetNumber of results to skip, for pagination. Defaults to 0.
Example
circle services search "weather" --category WEB_SEARCH_RESEARCH --limit 20

circle services inspect

Inspect the payment requirements for a service URL. The CLI auto-detects the HTTP method from the service’s discovery metadata and auto-generates a minimal request body from its input schema. Override either with the flags below. Syntax
circle services inspect <url> [options]
Arguments
ArgumentDescription
<url>Service URL to inspect.
Options
OptionDescription
--method, -XHTTP method override: GET, POST, PUT, DELETE, PATCH.
--data, -dRequest body as a JSON string. Overrides the auto-generated body.
--header, -HCustom request header as Key: Value. Repeat the flag to send multiple.
Example
circle services inspect https://api.example.com/weather -X POST -d '{"city":"SF"}'

circle services pay

Pay for a service using your agent wallet. Syntax
circle services pay <url> --address <address> --chain <chain> [options]
Arguments
ArgumentDescription
<url>Service URL to pay for.
Options
OptionDescription
--addressAgent wallet address.
--chainBlockchain to pay from.
--max-amount <usdc>Refuse to pay more than this amount in USDC (for example, 0.01).
--method, -XHTTP method: GET, POST, PUT, DELETE, PATCH. Defaults to GET.
--data, -dRequest body as a JSON string.
--header, -HCustom request header as Key: Value.
--estimateShow payment requirements without submitting payment.
--quiet, -qPrint response body only (useful for piping).
--timeout <seconds>Per-step timeout in seconds. Defaults to 30.
Example
circle services pay https://api.example.com/weather --address 0x... --chain BASE
Failed payments write debug logs to ~/.circle-cli/payments/. Check the most recent file for the request, response, and stage where the failure occurred.

Bridge commands

Bridge USDC across blockchains using CCTP.

circle bridge transfer

Bridge USDC from one blockchain to another. Syntax
circle bridge transfer <toChain> [<recipient>] --amount <amount> --address <addr> --chain <from>
Arguments
ArgumentDescription
<toChain>Destination blockchain (for example, ARB, ETH).
[<recipient>]Recipient address on the destination. Defaults to the value of --address.
Options
OptionDescription
--amountUSDC amount the recipient will receive.
--addressSender wallet address.
--chainSource blockchain.
--rpc-urlRPC endpoint override for the source blockchain.
--idempotency-keyUnique key to prevent duplicate transfers on retry.
--quiet, -qPrint transaction hash only (useful for piping).
Example
circle bridge transfer ARB-SEPOLIA --amount 10.0 --address 0x... --chain ARC-TESTNET

circle bridge status

Check the status of a bridge transfer by transaction hash. Syntax
circle bridge status <txHash> --chain <chain>
Arguments
ArgumentDescription
<txHash>Transaction hash of the burn transaction.
Options
OptionDescription
--chainSource blockchain.
Example
circle bridge status 0xabc... --chain ARC-TESTNET

circle bridge get-fee

Get the estimated fee for bridging from a given blockchain. Syntax
circle bridge get-fee <to> --chain <from>
Arguments
ArgumentDescription
<to>Destination blockchain (for example, ARB, ETH).
Options
OptionDescription
--chainSource blockchain.
Example
circle bridge get-fee ETH --chain ARC-TESTNET

Gateway commands

Interact with Circle Gateway.

circle gateway balance

Show your Gateway balance for nanopayments. Syntax
circle gateway balance --address <addr> --chain <chain> [options]
Options
OptionDescription
--addressWallet address.
--chainBlockchain where the wallet lives. Any Gateway-supported blockchain is valid.
--allShow all blockchains including those with zero balances.
--rpc-urlRPC endpoint override. Required for local wallets without a configured default.
Examples
circle gateway balance --address 0x... --chain BASE
circle gateway balance --address 0x... --chain BASE --all

circle gateway deposit

Deposit USDC into Circle Gateway for nanopayments. Minimum deposit is 0.5 USDC. Syntax
circle gateway deposit --amount <usdc> --address <addr> --chain <chain> --method <method> [options]
Options
OptionDescription
--amountAmount of USDC to deposit.
--addressWallet address.
--chainSource blockchain. With --method direct, any Gateway-supported blockchain is valid. With --method eco, only BASE and BASE-SEPOLIA.
--methodDeposit method: eco or direct. Eco deposits always settle on Polygon (MATIC mainnet, MATIC-AMOY testnet) regardless of source.
--timeoutTransaction poll timeout in seconds. Defaults to 120.
Eco is a third-party fast-deposit service. Circle does not operate, endorse, or audit Eco. Review Eco’s docs and test the flow before using it in production.
Example
circle gateway deposit --amount 5 --address 0x... --chain BASE --method eco

circle gateway withdraw

Withdraw USDC from Circle Gateway back to a wallet on the same blockchain. Syntax
circle gateway withdraw --amount <usdc> --address <addr> --chain <chain> [options]
Options
OptionDescription
--amountAmount of USDC to withdraw.
--addressSource wallet address (the Gateway depositor).
--chainSource blockchain. Any Gateway-supported blockchain is valid.
--recipientDestination address to receive USDC. Defaults to --address.
--timeoutMint transaction poll timeout in seconds. Defaults to 120. Agent wallets only.
Withdrawals are same-chain only. The withdrawn USDC is minted on --chain. Agent wallets must be Smart Contract Accounts (SCAs). Pass the SCA address as --address. JSON output includes transferId, estimatedFee, and chargedFee.
Examples
# Withdraw to your own wallet
circle gateway withdraw --amount 0.1 --address 0x... --chain BASE

# Withdraw to a different recipient
circle gateway withdraw --amount 5 --address 0x... --chain BASE --recipient 0xOTHER

Blockchain commands

Query supported blockchain information.

circle blockchain list

List all blockchains supported by Circle CLI. Syntax
circle blockchain list

circle blockchain config

Show or update the RPC URL for a blockchain. Syntax
circle blockchain config --chain <chain> [options]
Options
OptionDescription
--chainBlockchain to configure.
--rpc-urlSet a custom RPC URL override for this blockchain.
--defaultReset to the default RPC URL. Cannot be used with --rpc-url.
Examples
circle blockchain config --chain ARC-TESTNET --output json
circle blockchain config --chain ARC-TESTNET --rpc-url https://my-node.example.com
circle blockchain config --chain ARC-TESTNET --default

Transaction commands

Manage pending and submitted transactions.

circle transaction list

List transaction history for a wallet. Syntax
circle transaction list --address <addr> --chain <chain> [options]
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
--operationFilter by operation: transfer or execute.
--stateFilter by state: initiated, queued, sent, confirmed, complete, failed, cancelled, denied, cleared, stuck.
--tx-typeFilter by direction: inbound or outbound.
--lowest-nonceReturn only the lowest-nonce pending transaction. Ignores other filters.
--cursorPagination token: return transactions after this ID.
--limitMaximum number of transactions to return. Defaults to 50.
Examples
circle transaction list --address 0x... --chain ARC-TESTNET
circle transaction list --address 0x... --chain ARC-TESTNET --operation transfer --state confirmed

circle transaction cancel

Cancel a pending transaction. Syntax
circle transaction cancel <id> --address <addr> --chain <chain>
Arguments
ArgumentDescription
<id>Transaction ID.
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
Example
circle transaction cancel abc-123 --address 0x... --chain ARC-TESTNET

circle transaction accelerate

Accelerate a pending transaction by increasing the gas fee. Syntax
circle transaction accelerate <id> --address <addr> --chain <chain>
Arguments
ArgumentDescription
<id>Transaction ID.
Options
OptionDescription
--addressWallet address.
--chainBlockchain.
Example
circle transaction accelerate abc-123 --address 0x... --chain ARC-TESTNET

Contract commands

Interact with onchain contracts.

circle contract address

Show Circle contract addresses, optionally filtered by category and blockchain. Syntax
circle contract address [category] [--chain <chain>]
Arguments
ArgumentDescription
[category]Contract category to filter by (for example, usdc, cctp, gateway).
Options
OptionDescription
--chainFilter by blockchain.
Examples
circle contract address usdc --chain ARC-TESTNET
circle contract address cctp --output json

circle contract query

Execute a read-only contract call. Syntax
circle contract query <abiFunctionSignature> [abiParameters...] --contract <address> --chain <chain>
Arguments
ArgumentDescription
<abiFunctionSignature>ABI function signature (for example, balanceOf(address)).
[abiParameters...]ABI parameters, space-separated (for example, 0x1234...).
Options
OptionDescription
--contractContract address.
--chainBlockchain to query.
Examples
circle contract query "balanceOf(address)" 0xWALLET --contract 0xUSDC --chain ARC-TESTNET
circle contract query "totalSupply()" --contract 0xUSDC --chain ARC-TESTNET --output json

Skill commands

Discover and install skills from the circlefin/skills catalog.
The --tool option specifies your agent framework. Common values: claude-code, cursor, codex.

circle skill list

List all available skills from the catalog. Syntax
circle skill list [--output json]
Options
OptionDescription
--output jsonReturn results as JSON.

circle skill info

Show details and full content for a specific skill. Syntax
circle skill info --name <name>
Options
OptionDescription
--nameName of the skill to inspect.
Example
circle skill info --name <skill-name>

circle skill install

Install a skill into your agent framework. Syntax
circle skill install --tool <tool> [--name <name>]
Options
OptionDescription
--toolAgent framework to install into. Use multiple --tool options for more than one framework.
--nameSkill name to install. Omit to install all available skills.
Examples
circle skill install --tool claude-code --name <skill-name>
circle skill install --tool cursor --tool codex --name <skill-name>

circle skill update

Update installed skills for an agent framework. Syntax
circle skill update --tool <tool>
Options
OptionDescription
--toolAgent framework to update skills for.

Terms commands

Inspect, accept, or reset your local Circle CLI Terms of Use acceptance record. The first time you run any command, Circle CLI prompts you to accept the Terms of Use and Privacy Policy. Acceptance is stored locally and reused on subsequent runs. To handle Terms acceptance non-interactively in scripts and AI agents, use circle terms accept or set CIRCLE_ACCEPT_TERMS=1 in the environment.

circle terms

Show the current acceptance status and the canonical Terms of Use and Privacy Policy URLs. Default verb is show. Syntax
circle terms [show] [options]
Options
OptionDescription
--initReturn Terms info (version, URLs, notice text) for an agent to present before calling accept. Implies --output json.
Examples
circle terms
circle terms --output json
circle terms show --init --output json
JSON output
{
  "accepted": true,
  "currentVersion": "1.0.0",
  "termsOfUseUrl": "https://www.circle.com/legal/circle-cli-terms-of-use",
  "privacyPolicyUrl": "https://www.circle.com/legal/privacy-policy",
  "acceptance": {
    "version": "1.0.0",
    "acceptedAt": "2026-05-07T12:34:56Z"
  }
}

circle terms accept

Explicitly accept the Terms of Use and Privacy Policy. Use this in scripts and AI agent workflows after the user provides explicit consent. Syntax
circle terms accept [--output json]
Example
circle terms accept --output json

circle terms reset

Clear the local acceptance record. The next command run prompts you to accept the Terms again. Syntax
circle terms reset

Telemetry commands

Manage CLI telemetry preferences. Telemetry collects privacy-preserving usage data to help improve Circle CLI.

circle telemetry status

Show the current telemetry preference. Syntax
circle telemetry status [options]
Example
circle telemetry status

circle telemetry enable

Enable telemetry for future commands. Syntax
circle telemetry enable

circle telemetry disable

Disable telemetry for future commands. Syntax
circle telemetry disable