bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 4쪽
ion": "TRANSFER"
}
}
```
If the transfer fails, the command prints the reason. Check your wallet balance
and retry.
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--token` to transfer tokens other than USDC.
# Circle CLI
Source: https://developers.circle.com/agent-stack/circle-cli
A command-line tool to access Circle's product suite, including agent wallets, x402-compatible payments, and crosschain transfers.
Circle CLI gives developers and AI agents a unified interface for onchain
operations. Create and manage wallets, transfer, swap, and bridge USDC across
blockchains, execute smart contracts, and discover or pay for services. All
through a single command interface, without integrating multiple APIs and SDKs.
Use Circle CLI to access:
* **[Agent Wallets](/agent-stack/agent-wallets)**: Wallets with email OTP
authentication, full onchain capabilities, and customizable policy
enforcement.
* **Local wallets**: Self-custodial wallets imported from a private key or
mnemonic, stored using the
[Open Wallet Standard](https://github.com/open-wallet-standard/core).
* **[Agent Nanopayments](/agent-stack/agent-nanopayments)**: Gas-free, batched
USDC payments for x402-compatible services.
* **Circle products**: [CCTP](/cctp) for USDC bridging, [Gateway](/gateway) for
unified USDC balances, [Circle Contracts](/contracts) for smart contract
queries, and [Circle Skills](/ai/skills) for extending your agent with
Circle-specific capabilities.
## Installation
Install Circle CLI from [npm](https://www.npmjs.com/) (requires
[Node.js v20.18.2 or later](https://nodejs.org/)):
```bash theme={null}
npm install -g @circle-fin/cli
```
Verify the installation:
```bash theme={null}
circle --version
```
Once installed, you can run any
[Circle CLI command](/agent-stack/circle-cli/command-reference). If your version
is no longer supported, run
[`circle update`](/agent-stack/circle-cli/command-reference#circle-update).
## Get started
<CardGroup>
<Card title="Create an Agent Wallet" icon="wallet" href="/agent-stack/agent-wallets/quickstart">
Create an agent wallet and fund it with USDC.
</Card>
<Card title="Make a nanopayment" icon="bolt" href="/agent-stack/agent-nanopayments/quickstart">
Send a gas-free USDC payment for an x402-protected resource.
</Card>
<Card title="CLI Command Reference" icon="book" href="/agent-stack/circle-cli/command-reference">
All Circle CLI commands, options, and examples.
</Card>
</CardGroup>
# CLI command reference
Source: https://developers.circle.com/agent-stack/circle-cli/command-reference
Complete command reference for Circle's agent command-line tool, organized by resource.
Circle CLI follows a `circle <resource> <verb> [options]` pattern. All commands
support `--help` for inline documentation.
## Global options
| Option | Description |
| :- | :- |
| `--output json\|table` | Set output format. Defaults to `table`. |
| `-q, --quiet` | Minimal output, suitable for piping. |
| `-h, --help` | Show help for any command. |
| `-v, --version` | Print the Circle CLI version and exit. |
***
## Update command
### `circle update`
Check npm for the latest Circle CLI release and update a global installation.
This command remains available even when the installed version is no longer
supported and other commands are blocked.
**Syntax**
```bash theme={null}
circle update [options]
```
**Options**
| Option | Description |
| :- | :- |
| `-y, --yes` | Skip the confirmation prompt. Required when standard input is not a terminal. |
| `-h, --help` | Show command help. |
Circle CLI displays an update notice when a newer version is available. When
your installed version falls below the minimum supported version, most commands
are blocked until you run `circle update`. The `help`, `version`, `update`, and
`skill` commands remain available, and JSON output returns the `VERSION_BLOCKED`
error code.
For CI or air-gapped environments, set `CIRCLE_VERSION_CHECK=off` to skip
version checks. Don't use this to bypass a required update; run `circle update`
instead.
***
## Wallet commands
Manage your [agent wallet](/agent-stack/agent-wallets).
### `circle wallet login`
Authenticate using email OTP to create or access an agent wallet session.
**Syntax**
```bash theme={null}
circle wallet login <email> [options]
circle wallet login <email> --init
circle wallet login --request <id> --otp <code>
```
**Options**
| Option | Description |
| :- | :- |
| `--type` | Wallet type. Only `agent` is supported (the default). |
| `--testnet` | Authenticate against testnet. Sessions are stored separately from mainnet. |
| `--init` | Two-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**
```bash theme={null}
# 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
```
<Note>
Request IDs from `--init` expire after 10 minutes and are deleted after a
successful `--request`.
</Note>
***
### `circle wallet logout`
Clear stored credentials for the current session.
**Syntax**
```bash theme={null}
circle wallet logout [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--type` | Clear credentials for a specific wallet type (for example, `agent`). |
**Example**
```bash theme={null}
circle wallet logout --type agent
```
***
### `circle wallet status`
Show the current authentication status and session details.
**Syntax**
```bash theme={null}
circle wallet status [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--type` | Show status for a specific wallet type (for example, `agent`). |
**Example**
```bash theme={null}
circle wallet status --type agent
```
***
### `circle wallet create`
Create an additional wallet, separate from the wallets provisioned during login.
Each user can have up to 5 agent wallets. You can't delete agent wallets.
**Syntax**
```bash theme={null}
circle wallet create [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--type` | Wallet type: `agent` (default) or `local`. |
| `--testnet` | Create a testnet wallet. Omit for mainnet. |
| `--idempotency-key` | Unique key to prevent duplicate wallet creation on retry. |
**Example**
```bash theme={null}
circle wallet create --type agent --testnet
```
***
### `circle wallet list`
List wallets associated with your account.
**Syntax**
```bash theme={null}
circle wallet list --chain <chain> [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--chain` | Blockchain to list wallets on. |
| `--type` | Filter by wallet type: `agent` or `local`. |
**Example**
```bash theme={null}
circle wallet list --chain ARC --type agent
```
***
### `circle wallet limit`
Show spending policy limits for an agent wallet. Mainnet only.
**Syntax**
```bash theme={null}
circle wallet limit --address <addr> --chain <chain>
```
**Options**
| Option | Description |
| :- | :- |
| `--address` | Agent wallet address. |
| `--chain` | Mainnet blockchain. Testnet chains not supported. |
**Examples**
```bash theme={null}
circle wallet limit --address 0x... --chain ARC
circle wallet limit --address 0x... --chain ARC --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**
```bash theme={null}
# 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**
| Option | Description |
| :- | :- |
| `--address` | Agent wallet address. |
| `--chain` | Mainnet blockchain. Testnet blockchains are not supported. |
| `--policy-type` | Policy category: `stablecoin` for transfer-based rules, `contract` for contract-based rules. Auto-set when `--rule-type` is a contract rule. |
| `--rule-type` | Rule shape: `transfer-limit` (default), `recipient-allowlist`, `recipient-blocklist`, `contract-allowlist`, or `contract-blocklist`. |
| `--per-tx` | Per-transaction spending cap. Used with `--rule-type transfer-limit`. |
| `--daily` | Daily rolling-window cap. Used with `--rule-type transfer-limit`. |
| `--weekly` | Weekly rolling-window cap. Used with `--rule-type transfer-limit`. |
| `--monthly` | Monthly rolling-window cap. Used with `--rule-type transfer-limit`. |
| `--targets` | Bracketed comma-separated list of EVM addresses (for example, `"[0xA,0xB]"`). Required for allowlist and blocklist rule types. Validated client-side. |
| `--email` | Email address for the confirmation OTP. Defaults to the agent session email. |
<Note>
Transfer limits must satisfy: per-transaction ≤ daily ≤ weekly ≤ monthly.
</Note>
**Examples**
```bash theme={null}
# Transfer limits
circle wallet limit set \
--address 0x... \
--chain ARC \
--policy-type stablecoin \
--per-tx 100 \
--daily 500 \
--weekly 2000 \
--monthly 5000
# Recipient blocklist
circle wallet limit set \
--address 0x... \
--chain ARC \
--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**
```bash theme={null}
circle wallet limit reset --address <addr> --chain <chain> [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--address` | Agent wallet address. |
| `--chain` | Mainnet blockchain. Testnet chains not supported. |
| `--yes`, `-y` | Skip the confirmation prompt. |
**Example**
```bash theme={null}
circle wallet limit reset --address 0x... --chain ARC --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**
```bash theme={null}
circle wallet limit budget --address <addr>
```
**Options**
| Option | Description |
| :- | :- |
| `--address` | Agent wallet address. |
**Example**
```bash theme={null}
circle wallet limit budget --address 0x...
```
***
### `circle wallet balance`
Show the token balance for a wallet address on a given blockchain.
**Syntax**
```bash theme={null}
circle wallet balance --address <addr> --chain <chain> [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--address` | Wallet address. |
| `--chain` | Blockchain. |
| `--rpc-url` | RPC endpoint override. Required for local wallets without a configured default. |
**Example**
```bash theme={null}
circle wallet balance --address 0x... --chain ARC
```
***
### `circle wallet fund`
Add funds to a wallet by transfer from another wallet (crypto), through a fiat
onramp, or from the testnet faucet.
**Syntax**
```bash theme={null}
circle wallet fund --address <addr> --chain <chain> --amount <usdc> --method <crypto|fiat> [options]
```
**Options**
| Option | Description |
| :- | :- |
| `--address` | Wallet address to fund. |
| `--chain` | Blockchain. |
| `--amount` | Amount to fund. Ignored on testnet. |
| `--token` | Token: `usdc` (default), `eth`, `eurc`, `native`. |
| `--method` | Funding method: `crypto` or `fiat`. Required on mainnet. Omit on testnet, where `circle wallet fund` draws from the Circle faucet. |
| `--export <dir>` | With `--method crypto`, write a PNG QR code into `<dir>` instead of printing it to the terminal. |
| `--open` | Open the result in your browser. With `--method fiat`, opens the onramp provider. With `--method crypto`, opens an HTML page with the QR code. |
| `--no-open` | Print the onramp URL without opening it. Used with `--method fiat` only. |
**Examples**
```bash theme={null}
# Fund with crypto from another wallet
circle wallet fund --address 0x... --chain ARC --amount 10 --method crypto
# Fund with fiat through the onramp provider
circle wallet fund --address 0x... --chain ARC --amount 10 --method fiat
# Testnet: draws from the Circle 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**
```bash theme={null}
circle wallet transfer <toAddress> --amount <amount> --address <addr> --chain <chain> [options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<toAddress>` | Recipient address. |
**Options**
| Option | Description |
| :- | :- |
| `--amount` | Amount to transfer. |
| `--address` | Source wallet address. |
| `--chain` | Blockchain. |
| `--token` | Token contract address. Omit to use USDC. |
| `--rpc-url` | RPC endpoint override. Required for local wallets without a configured default. |
| `--estimate` | Show estimated fees without submitting the transfer. |
**Example**
```bash theme={null}
circle wallet transfer 0xRecipient --amount 5.0 --address 0x... --chain ARC
```
***
### `circle wallet swap`
Swap one token for another. Requires an agent wallet. Arc Testnet is the only
testnet supported.
**Syntax**
```bash theme={null}
circle wallet swap <sellToken> <sellAmount> <buyToken> [<buyAmount>] --address <addr> --chain <chain> [options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<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**
| Option | Description |
| :- | :- |
| `--address` | Agent wallet address. Optional when using `--quote`. |
| `--chain` | Blockchain. |
| `--quote` | Get a price quote without executing the swap. Does not require wallet ownership or `buyAmount`. |
| `--slippage-bps` | Maximum slippage in basis points (for example, `50` = 0.5%). Defaults to `300` (3%). |
| `--idempotency-key` | Unique key to prevent duplicate swaps on retry. |
**Examples**
```bash theme={null}
circle wallet swap EURC 100 USDC 99.5 --address 0x... --chain ARC
circle wallet swap EURC 100 USDC --chain ARC --quote
```
***
### `circle wallet sign message`
Sign a plain text or hex-encoded message with your wallet.
**Syntax**
```bash theme={null}
circle wallet sign message <message> --address <addr> --chain <chain> [options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<message>` | Message to sign (plain text or hex). |
**Options**
| Option | Description |
| :- | :- |
| `--address` | Wallet address. |
| `--chain` | Blockchain. |
| `--hex` | Message is hex-encoded (must start with `0x`). |
**Example**
```bash theme={null}
circle wallet sign message "hello world" --address 0x... --chain ARC
```
***
### `circle wallet sign typed-data`
Sign EIP-712 typed data with your wallet.
**Syntax**
```bash theme={null}
circle wallet sign typed-data <data> --address <addr> --chain <chain>
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<data>` | EIP-712 typed data as a JSON string. |
**Options**
| Option | Description |
| :- | :- |
| `--address` | Wallet address. |
| `--chain` | Blockchain. |
**Example**
```bash theme={null}
circle wallet sign typed-data '{"types":{...},"primaryType":"Mail","domain":{...},"message":{...}}' \
--address 0x... \
--chain ARC
```
***
### `circle wallet execute`
Execute a smart contract write function from a wallet.
**Syntax**
```bash theme={null}
circle wallet execute <abiFunctionSignature> [<abiParameters>...] \
--contract <addr> \
--address <addr> \
--chain <chain> \
[options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<abiFunctionSignature>` | ABI function signature (for example, `approve(address,uint256)`). |
| `[<abiParameters>...]` | ABI parameters, space-separated. |
**Options**
| Option | Description |
| :- | :- |
| `--contract` | Contract address. |
| `--address` | Wallet address. |
| `--chain` | Blockchain. |
| `--amount` | Native token value to send with the call. Defaults to `0`. |
| `--rpc-url` | RPC endpoint override. Required for local wallets without a configured default. |
| `--estimate` | Show estimated fees without submitting the transaction. |
**Example**
```bash theme={null}
circle wallet execute "approve(address,uint256)" 0xSpender 1000000 \
--contract 0xUSDC \
--address 0x... \
--chain ARC
```
***
### `circle wallet import`
Import a local wallet from a private key or mnemonic phrase. Stored using the
Open Wallet Standard at `~/.ows/wallets/<name>`.
<Warning>
Local wallets bypass Circle's compliance and safety controls. Spending
policies, OFAC screening, and audit logging only apply to agent wallets.
</Warning>
**Syntax**
```bash theme={null}
circle wallet import <name> [--private-key | --mnemonic]
```
**Options**
| Option | Description |
| :- | :- |
| `--private-key` | Import from a private key. You'll be prompted to enter the key securely. |
| `--mnemonic` | Import from a mnemonic phrase. You'll be prompted to enter it securely. |
<Warning>
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.
</Warning>
**Example**
```bash theme={null}
circle wallet import my-wallet --private-key
```
***
## Services commands
Discover and pay for [x402](/x402-facilitators/x402)-compatible API services.
### `circle services search`
Search for available services by keyword. Omit the query to list all services.
**Syntax**
```bash theme={null}
circle services search [<query>] [options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `[<query>]` | Optional search keyword or phrase. Omit to list all results. |
**Options**
| Option | Description |
| :- | :- |
| `--category` | Filter by category (for example, `FINANCIAL_ANALYSIS`, `WEB_SEARCH_RESEARCH`). |
| `--type` | Filter by service type. |
| `--limit` | Maximum number of results to return. Defaults to `50`. |
| `--offset` | Number of results to skip, for pagination. Defaults to `0`. |
**Example**
```bash theme={null}
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**
```bash theme={null}
circle services inspect <url> [options]
```
**Arguments**
| Argument | Description |
| :- | :- |
| `<url>` | Service URL to inspect. |
**Options**
| Option | Description |
| :- | :- |
| `--method`, `-X` | HTTP method override: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. |
| `-프로젝트로 돌아가기
