bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 3쪽
cle CLI](/agent-stack/circle-cli). Full command syntax is in the
[CLI command reference](/agent-stack/circle-cli/command-reference).
The following table describes common wallet operations and the CLI commands to
perform them.
| Operation | What it does | Command |
| :- | :- | :- |
| [Authenticate](/agent-stack/agent-wallets/wallet-operations/authenticate) | Sign up or log in to your agent wallet using email OTP. Creates a session valid for 28 days. | `circle wallet login` |
| [Fund wallet](/agent-stack/agent-wallets/wallet-operations/fund) | Add funds to your agent wallet using a wallet transfer or fiat onramp. | `circle wallet fund` |
| [Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer) | Send USDC and other tokens to a designated wallet address. | `circle wallet transfer` |
| [Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge) | Move USDC from one blockchain to another using CCTP. | `circle bridge transfer` |
| [Swap tokens](/agent-stack/agent-wallets/wallet-operations/swap) | Swap one token for another directly from your agent wallet. | `circle wallet swap` |
| [Execute contract](/agent-stack/agent-wallets/wallet-operations/execute-contract) | Interact with a smart contract by calling a write function. | `circle wallet execute` |
| [Sign messages](/agent-stack/agent-wallets/wallet-operations/sign) | Sign a message or EIP-712 typed data with your wallet. | `circle wallet sign` |
| [Set policies](/agent-stack/agent-wallets/wallet-operations/custom-policies) | Set USDC transfer limits or allow/block specific recipient or contract addresses. | `circle wallet limit set` |
For deposits into Gateway, payments to x402-compatible services, and
withdrawals, see [Agent nanopayments](/agent-stack/agent-nanopayments).
# How-to: Authenticate an agent wallet
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/authenticate
Log in with your email to create an agent wallet session on all supported blockchains.
Authenticating creates an agent session and provisions agent wallets on all
[supported blockchains](/agent-stack/agent-wallets/supported-blockchains)
automatically. You only need to do this once per environment. Sessions last 28
days. Session secrets are stored in your operating system's secure keychain. Run
`circle wallet logout` to clear the session.
This is a prerequisite for all other wallet operations, including
[Fund wallet](/agent-stack/agent-wallets/wallet-operations/fund),
[Transfer USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[Bridge USDC](/agent-stack/agent-wallets/wallet-operations/bridge), and
[Pay for service](/agent-stack/agent-nanopayments/operations/pay-for-service).
<Warning>
Never give an AI agent unrestricted access to your email account. Circle sends
a one-time password (OTP) to the email you log in with. Anyone who can read
that inbox can use the OTP code to log in to your agent wallet. They can then
perform any wallet operation, including changing your spending policies. Enter
the OTP code yourself instead of giving your agent access to your email.
</Warning>
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
## Steps
Choose the flow that matches your environment. Use **Interactive** when you can
respond to prompts in a terminal. Use **Non-interactive** for scripts and AI
agents that can't respond to interactive prompts.
<Tabs>
<Tab title="Interactive">
<Steps>
<Step title="Run the login command">
Run `circle wallet login` with your email address:
```bash theme={null}
circle wallet login you@example.com
```
<Note>
To use testnet, add `--testnet` to the command. Sessions are stored separately
for mainnet and testnet and expire after 28 days.
</Note>
On first run, Circle CLI prompts you to accept the Terms of Use and
Privacy Policy.
</Step>
<Step title="Enter the one-time password">
Check your email for the one-time password from Circle. Enter it in
the terminal to verify your identity. You should see output similar
to:
```text theme={null}
Logged in as you@example.com
```
Agent wallets are created automatically on all
[supported blockchains](/agent-stack/agent-wallets/supported-blockchains).
</Step>
<Step title="Get your wallet address">
List your wallets to find the address for the blockchain you want to
use:
```bash theme={null}
circle wallet list --type agent --chain ARC
```
Copy the address returned. You'll need it for
[funding your wallet](/agent-stack/agent-wallets/wallet-operations/fund),
[transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[depositing for nanopayments](/agent-stack/agent-nanopayments/operations/deposit),
and other operations.
</Step>
</Steps>
</Tab>
<Tab title="Non-interactive (scripts and AI agents)">
<Steps>
<Step title="Initialize the login">
Run `circle wallet login` with `--init` to send the OTP and capture a
request ID. The `CIRCLE_ACCEPT_TERMS=1` prefix accepts the Circle CLI
Terms of Use and Privacy Policy so the command doesn't pause for
input on first run:
```bash theme={null}
CIRCLE_ACCEPT_TERMS=1 circle wallet login you@example.com --init
```
The CLI prints a request ID. Request IDs expire after 10 minutes and
are consumed on first use.
</Step>
<Step title="Complete the login">
Pass the request ID and the OTP from your inbox:
```bash theme={null}
circle wallet login --request <request-id> --otp B1X-123456
```
OTP codes are alphanumeric. Once login completes, agent wallets are
created automatically on all
[supported blockchains](/agent-stack/agent-wallets/supported-blockchains).
</Step>
<Step title="Get your wallet address">
List your wallets to find the address for the blockchain you want to
use:
```bash theme={null}
circle wallet list --type agent --chain ARC
```
Copy the address returned. You'll need it for
[funding your wallet](/agent-stack/agent-wallets/wallet-operations/fund),
[transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[depositing for nanopayments](/agent-stack/agent-nanopayments/operations/deposit),
and other operations.
</Step>
</Steps>
</Tab>
</Tabs>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.
# How-to: Bridge USDC
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/bridge
Move USDC from one blockchain to another using CCTP.
Bridge USDC across blockchains using [CCTP](/cctp). Circle handles attestation
and minting on the destination chain. You don't need a funded wallet or gas on
the destination.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* Completed the
[Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
(authenticates and funds your wallet).
## Steps
Follow these steps to bridge USDC to another blockchain.
<Steps>
<Step title="Check the fee">
Get the estimated fee before bridging:
```bash theme={null}
circle bridge get-fee ARC --chain BASE
```
</Step>
<Step title="Bridge USDC">
Run `circle bridge transfer` with the destination chain, amount, and your
wallet details:
```bash theme={null}
circle bridge transfer ARC --amount 10.0 --address 0xYourWalletAddress --chain BASE
```
USDC is burned on the source chain and minted on the destination. The
command returns once the bridge is complete:
```json theme={null}
{
"data": {
"message": "Bridge complete: 10.0 USDC from BASE to ARC",
"burnTxHash": "0xabc...",
"forwardTxHash": "0xdef...",
"fromChain": "BASE",
"toChain": "ARC"
}
}
```
If the bridge is still processing, you can check its status:
```bash theme={null}
circle bridge status 0xabc... --chain BASE
```
</Step>
</Steps>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including specifying a different recipient address on
the destination chain.
# How-to: Set spending policies
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/custom-policies
Set transfer limits or address allowlists and blocklists on your agent wallet to control how it can move USDC and interact with contracts.
Spending policies let you cap your agent wallet's USDC transfers over a rolling
time window, or restrict the wallet to specific recipient or contract addresses.
Policies apply to mainnet agent wallets only.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
your agent wallet.
<Note>
Spending policies require a mainnet agent wallet. Testnet is not supported.
Setting a policy triggers a second email OTP to confirm the change. The OTP is
used once and not stored.
</Note>
## Steps
Choose the policy type that matches your goal.
<Tabs>
<Tab title="Transfer limits">
<Steps>
<Step title="Set the limits">
Run `circle wallet limit set` with per-transaction, daily, weekly, and
monthly caps:
```bash theme={null}
circle wallet limit set \
--address 0xYourWalletAddress \
--chain ARC \
--policy-type stablecoin \
--per-tx 100 \
--daily 500 \
--weekly 2000 \
--monthly 5000
```
Circle sends an email OTP to your agent session email to confirm the
policy change. Limits must satisfy: per-transaction ≤ daily ≤ weekly
≤ monthly.
</Step>
<Step title="Verify the policy">
Confirm the limits are in effect:
```bash theme={null}
circle wallet limit --address 0xYourWalletAddress --chain ARC
```
</Step>
</Steps>
</Tab>
<Tab title="Allowlists and blocklists">
Allowlists and blocklists restrict your wallet to specific recipient or
contract addresses.
<Steps>
<Step title="Set the rule">
Run `circle wallet limit set` with `--rule-type` and a bracketed,
comma-separated `--targets` list of EVM addresses. The example below
blocks transfers to two recipient addresses:
```bash theme={null}
circle wallet limit set \
--address 0xYourWalletAddress \
--chain ARC \
--policy-type stablecoin \
--rule-type recipient-blocklist \
--targets "[0xBAD1,0xBAD2]"
```
`--rule-type` accepts:
* `recipient-allowlist` / `recipient-blocklist`: allow or block USDC
transfers to specific addresses.
* `contract-allowlist` / `contract-blocklist`: allow or block contract
interactions with specific addresses.
Circle sends an email OTP to your agent session email to confirm the
policy change.
</Step>
<Step title="Verify the policy">
Confirm the rule is in effect:
```bash theme={null}
circle wallet limit --address 0xYourWalletAddress --chain ARC
```
</Step>
</Steps>
</Tab>
</Tabs>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.
# How-to: Execute a smart contract
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/execute-contract
Call a write function on a smart contract from your agent wallet.
Execute write functions on any smart contract from your agent wallet. Common
uses include approving token allowances, interacting with DeFi protocols, or
calling custom contract logic.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* Completed the
[Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
(authenticates and funds your wallet).
## Steps
Follow these steps to execute a smart contract function.
<Steps>
<Step title="Find the contract address">
For Circle contracts (USDC, CCTP, Gateway), look up the address for your
blockchain:
```bash theme={null}
circle contract address usdc --chain ARC
```
</Step>
<Step title="Execute the contract function">
Run `circle wallet execute` with the ABI function signature, parameters,
and contract address:
```bash theme={null}
circle wallet execute "approve(address,uint256)" 0xSpender 1000000 \
--contract 0xUSDC \
--address 0xYourWalletAddress \
--chain ARC
```
The CLI waits for the transaction to reach a terminal state and returns the
result:
```json theme={null}
{
"data": {
"id": "abc-123-...",
"state": "CONFIRMED",
"blockchain": "ARC",
"txHash": "0xabc...",
"operation": "CONTRACT_EXECUTION",
"contractAddress": "0xUSDC",
"abiFunctionSignature": "approve(address,uint256)"
}
}
```
If the transaction fails, the CLI prints the reason. Verify the contract
address, function signature, and parameters, then retry.
</Step>
</Steps>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--amount` to send native token value with
the call.
# How-to: Fund an agent wallet
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/fund
Add USDC to your agent wallet using a wallet transfer or fiat onramp.
Add USDC to your agent wallet before sending transfers or paying for services.
This is a prerequisite for
[transferring USDC](/agent-stack/agent-wallets/wallet-operations/transfer),
[bridging USDC](/agent-stack/agent-wallets/wallet-operations/bridge),
[paying for services](/agent-stack/agent-nanopayments/operations/pay-for-service),
and other operations that spend USDC.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
your agent wallet.
## Steps
<Steps>
<Step title="Fund your wallet">
Run `circle wallet fund` with your wallet address, blockchain, amount, and
method (crypto or fiat). Replace `0xYourWalletAddress` with your wallet
address.
<Tabs>
<Tab title="Crypto">
```bash theme={null}
circle wallet fund --address 0xYourWalletAddress \
--chain ARC --amount 10 --method crypto
```
The CLI prints a terminal QR code and an
[EIP-681](https://eips.ethereum.org/EIPS/eip-681) deposit URI. Scan
the QR code with your mobile wallet to send the funds. Pass
`--export <dir>` to save a PNG instead, or `--open` to render the QR
code in a browser tab.
</Tab>
<Tab title="Fiat">
```bash theme={null}
circle wallet fund --address 0xYourWalletAddress \
--chain ARC --amount 10 --method fiat
```
Your browser opens to the onramp provider where you can purchase USDC
with a card or bank transfer. Pass `--no-open` to print the URL
instead of opening the browser.
</Tab>
</Tabs>
<Note>
To use testnet, replace `BASE` with a testnet blockchain (for example,
`ARC-TESTNET`) and omit `--method` and `--amount`. On testnet, `circle wallet
fund` draws 20 USDC from the Circle faucet. See [supported
blockchains](/agent-stack/agent-wallets/supported-blockchains) for the full
list.
</Note>
</Step>
<Step title="Verify the funds arrived">
Check your balance to confirm the deposit:
```bash theme={null}
circle wallet balance --address 0xYourWalletAddress --chain ARC
```
</Step>
</Steps>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--token` to fund with ETH or native tokens.
# How-to: Sign a message
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/sign
Sign a plain text message or EIP-712 typed data with your agent wallet.
Sign messages or EIP-712 typed data with your agent wallet. Signing is commonly
used to prove wallet ownership or authorize offchain actions.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* [Authenticated](/agent-stack/agent-wallets/wallet-operations/authenticate)
your agent wallet.
## Sign a message
Run `circle wallet sign` with your message and wallet details. Each command
returns a signature (`0xabcdef1234...`):
```bash theme={null}
# Sign a plain text message
circle wallet sign message "hello world" --address 0xYourWalletAddress --chain ARC
# Sign a hex-encoded message
circle wallet sign message "0xdeadbeef" --hex --address 0xYourWalletAddress --chain ARC
# Sign EIP-712 typed data (EVM only)
circle wallet sign typed-data \
'{"types":{...},"primaryType":"Mail","domain":{...},"message":{...}}' \
--address 0xYourWalletAddress \
--chain ARC
```
<Note>Typed data signing is supported on EVM blockchains only.</Note>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options.
# How-to: Swap tokens
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/swap
Swap one token for another from your agent wallet.
Swap tokens from your agent wallet using `circle wallet swap`. Optionally get a
price quote first to verify the expected output before committing funds.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* Completed the
[Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
(authenticates and funds your wallet).
## Steps
<Steps>
<Step title="Get a quote (optional)">
Run `circle wallet swap` with `--quote` to see the estimated output without
executing the swap:
```bash theme={null}
circle wallet swap EURC 10 USDC --chain ARC --quote
```
```json theme={null}
{
"data": {
"message": "Quote: 10 EURC → ~9.95 USDC (min 0.000001) on ARC",
"sellToken": "EURC",
"sellAmount": "10",
"buyToken": "USDC",
"chain": "ARC",
"estimatedOutput": "9.95",
"stopLimit": "0.000001"
}
}
```
</Step>
<Step title="Swap tokens">
Run `circle wallet swap` with your wallet address and a `<buyAmount>`
stop-limit. If the estimated output falls below this value onchain, the swap
fails instead of settling at an unfavorable rate:
```bash theme={null}
circle wallet swap EURC 10 USDC 9.9 --address 0xYourWalletAddress --chain ARC
```
```json theme={null}
{
"data": {
"message": "Swap complete: 10 EURC → min 9.9 USDC on ARC",
"sellToken": "EURC",
"sellAmount": "10",
"buyToken": "USDC",
"buyMin": "9.9",
"chain": "ARC"
}
}
```
</Step>
</Steps>
See the [CLI command reference](/agent-stack/circle-cli/command-reference) for
full syntax and options, including `--slippage-bps` to set maximum slippage.
# How-to: Transfer USDC
Source: https://developers.circle.com/agent-stack/agent-wallets/wallet-operations/transfer
Send USDC from your agent wallet to another address on a supported blockchain.
The transfer confirms onchain before the command returns, so no manual polling
is required.
## Prerequisites
Before you begin, ensure you have:
* Installed [Node.js v20.18.2 or later](https://nodejs.org/).
* Installed Circle CLI:
```bash theme={null}
npm install -g @circle-fin/cli
```
* Completed the
[Agent Wallets quickstart](/agent-stack/agent-wallets/quickstart)
(authenticates and funds your wallet).
## Send USDC
Run `circle wallet transfer` with the recipient address, amount, and your wallet
details:
```bash theme={null}
circle wallet transfer 0xRecipient --amount 1.0 --address 0xYourWalletAddress --chain ARC
```
The command returns the result once the transaction reaches a terminal state:
```json theme={null}
{
"data": {
"id": "abc-123-...",
"state": "CONFIRMED",
"blockchain": "ARC",
"txHash": "0xabc...",
"sourceAddress": "0xYourWalletAddress",
"destinationAddress": "0xRecipient",
"amounts": ["1"],
"operat프로젝트로 돌아가기
