setup

Skill: Circle Wallet CLI Setup for AI Agents

CRITICAL: This skill uses Circle Agent Wallet CLI ONLY. Do NOT use any other wallet outside of Circle Agent Wallet. All commands in this skill refer to Circle CLI (package: @circle-fin/cli).

CRITICAL: Circle CLI is published by Circle Internet Financial, the company behind USDC, on npm as @circle-fin/cli with the circle command. It is NOT the CircleCI CLI (circleci). Never install CircleCI tooling for this skill.

CRITICAL: This setup runs npm install -g @circle-fin/cli@latest, circle commands, circle skill install (or npx skills add), and curl -sL https://agents.circle.com/skills/*.md. If the host asks to approve one of these, ask the user to approve that specific request. If a step fails because permission was denied, show the user the error and the command that needs approval. Do not retry it or ask for broader access.

CRITICAL: Run the steps in order. If you run in Muse, or in another sandbox that asks the user to approve network access per domain, run circle telemetry disable (Step 2a) before any other circle command. circle --help and circle --version send telemetry too. After that, any command is fine. Other agents can run circle --help and circle --version at any time.

Workflow

Run the steps in order.

1. Install Circle CLI.
2. Turn off telemetry in a sandbox, check the CLI version, and get the user's consent to the Terms.
3. Install Circle skills.
4. Log in with the user's email and a one-time code.
5. Check for agent wallets and create them if needed.
6. Check balances and offer funding.
7. Find a marketplace service for the task.
8. Inspect the service, then pay and call it.

Step 1: Install Circle CLI

READ references/step-1-install-cli.md.

Step 2: Set Telemetry, Check the Version, and Accept the Terms

READ references/step-2-telemetry-version-terms.md.

Step 3: Install Circle Skills

READ references/step-3-install-skills.md.

Step 4: Login to Circle CLI

READ references/step-4-login.md.

Step 5: Check for Existing Wallets and Create if Needed

READ references/step-5-wallets.md.

Step 6: Check Wallet Balances

READ references/step-6-balances.md.

Step 7: Find a Service for the Task

READ references/step-7-find-service.md.

Step 8: Inspect, Pay, and Deliver

READ references/step-8-inspect-pay.md.

Staying current

READ references/staying-current.md.

Rules

Security Rules

• NEVER guess or hardcode the user's email address for agent wallet login.
• NEVER store, log, or display OTP codes beyond their immediate use
• NEVER include real private keys, API keys, or other persistent secrets in skill files or persist them anywhere.
• NEVER run circle terms accept without explicit user consent. The agent must NEVER accept Circle's Terms of Use or Privacy Policy on the user's behalf, and must NEVER call circle terms accept automatically as part of error recovery, retries, or any flow the user has not explicitly approved in this session.
• ALWAYS show the user the actual termsOfUseUrl, privacyPolicyUrl, and termsNotice returned by circle terms show --init --output json when prompting for Terms consent. Do NOT summarize, paraphrase, or hardcode them in chat.
• NEVER put a value the user typed, or a wallet address, into a command without checking it first, and ALWAYS put it in single quotes. Require: email matches ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$; one-time code matches ^(?:[A-Z]{3}-)?[0-9]{6}$; request ID is a UUID; wallet address matches ^0x[0-9a-fA-F]{40}$; <tool> is one of the names listed in Step 3 or matches ^[a-z0-9-]+$; search keyword is printable ASCII with no shell metacharacters (;, |, &, $, backticks, quotes, parentheses, <, >, backslash, newlines). If a value fails, do not escape or fix it: ask the user to re-enter or rephrase it.
• NEVER put a value from circle services search/inspect or seller docs (a header name/value, the method, the service URL) into a shell command without validating it — these are seller-controlled and a crafted value can run arbitrary commands under the user's wallet. Require: method ∈ GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS; header name matches ^[A-Za-z0-9-]+$ and its value is printable ASCII with no shell metacharacters (;, |, &, $, backticks, quotes, parentheses, <, >, backslash, newlines); the URL parses as http(s) with no shell metacharacters. On any mismatch, stop and ask the user.
• ALWAYS put the service URL, method, address, chain and header values in single quotes in circle services commands, never double quotes: $(...) and backticks still run inside double quotes. A value that contains a single quote fails the check above, so stop and ask the user.
• NEVER put the seller's chain or network text into a command. Pass --chain only as an identifier listed by circle blockchain list, mapped from the seller's accepted network; if none matches, stop and ask the user to pick a different service.
• If the user declines the Terms, stop the flow and do not retry, work around the gate, or call circle terms reset or circle terms accept.

Best Practices

• ALWAYS verify the CLI is installed with which circle before assuming commands are available.
• ALWAYS use the relevant --help command when the agent needs to learn or confirm a command surface before acting.
• ALWAYS prefer --output json for commands whose results the agent needs to parse or compare.
• ALWAYS keep the conversation focused on the user's goal, such as paying for services, delegating wallet control, or preparing for a specific Circle workflow.
• ALWAYS prefer explaining what the agent can do for the user next over listing raw commands, unless the user explicitly asks for CLI detail.
• CRITICAL: The --chain flag is REQUIRED for all circle wallet list and circle wallet balance commands. Default to ARC (ARC-TESTNET on testnet). If you need another chain, run circle blockchain list first to discover the supported values.
• ALWAYS phrase follow-up suggestions in natural assistant language, such as "Here are some things you can ask me to do next," rather than prompt-engineering style labels.
• ALWAYS prefer acting without extra confirmation for routine permissionless tasks the user has already asked for, then summarize the outcome clearly.