Back to Details

use-usdc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Overview

概述

USDC is Circle's stablecoin deployed across multiple blockchain ecosystems. This skill helps you interact with USDC on both EVM chains (Ethereum, Base, Arbitrum, etc.) and Solana. It covers balance checks, transfers, approvals, and transfer verification.
USDC是Circle推出的稳定币，部署在多个区块链生态系统中。此Skill可帮助你在EVM链（Ethereum、Base、Arbitrum等）和Solana上与USDC进行交互，涵盖余额查询、转账、授权以及转账验证功能。

Prerequisites / Setup

前提条件/设置

Determine Ecosystem

确定生态系统

First, identify which ecosystem the user is working with:
  • EVM: User has an Ethereum-style address (
    0x...
    ) or mentions Ethereum, Base, Arbitrum, Polygon, etc.
  • Solana: User has a base58 address or mentions Solana, Devnet, Phantom, Solflare, etc.
  • Unclear: Ask which ecosystem before proceeding.
首先，确定用户所使用的生态系统：
  • EVM：用户拥有以太坊风格地址（
    0x...
    ），或提及Ethereum、Base、Arbitrum、Polygon等。
  • Solana：用户拥有base58格式地址，或提及Solana、Devnet、Phantom、Solflare等。
  • 不明确：在继续操作前询问用户使用的是哪个生态系统。

Dependencies

依赖项

EVM:
bash
npm install viem
Solana:
bash
npm install @solana/kit @solana-program/token ws dotenv bs58
EVM：
bash
npm install viem
Solana：
bash
npm install @solana/kit @solana-program/token ws dotenv bs58

Environment Variables

环境变量

See ecosystem-specific guides:
  • EVM: Private key handling covered in 
    references/evm.md
  • Solana: Private key handling covered in 
    references/solana.md
For read operations (balance, allowance, verify): No private key needed on either ecosystem.
请查看各生态系统的专属指南：
  • EVM：私钥处理相关内容请查阅
    references/evm.md
  • Solana：私钥处理相关内容请查阅
    references/solana.md
对于只读操作（余额查询、授权额度查询、验证）： 两个生态系统均无需私钥。

Quick Reference

快速参考

USDC Contract Addresses

USDC合约地址

Canonical source: https://developers.circle.com/stablecoins/usdc-contract-addresses
官方来源：https://developers.circle.com/stablecoins/usdc-contract-addresses

EVM Testnet

EVM测试网

ChainChain IDUSDC Address
Arc Testnet5042002
0x3600000000000000000000000000000000000000
Ethereum Sepolia11155111
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Base Sepolia84532
0x036CbD53842c5426634e7929541eC2318f3dCF7e
Arbitrum Sepolia421614
0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d
Avalanche Fuji43113
0x5425890298aed601595a70AB815c96711a31Bc65
Polygon Amoy80002
0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582
OP Sepolia11155420
0x5fd84259d66Cd46123540766Be93DFE6D43130D7
Get testnet USDC: https://faucet.circle.com
链链IDUSDC地址
Arc Testnet5042002
0x3600000000000000000000000000000000000000
Ethereum Sepolia11155111
0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Base Sepolia84532
0x036CbD53842c5426634e7929541eC2318f3dCF7e
Arbitrum Sepolia421614
0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d
Avalanche Fuji43113
0x5425890298aed601595a70AB815c96711a31Bc65
Polygon Amoy80002
0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582
OP Sepolia11155420
0x5fd84259d66Cd46123540766Be93DFE6D43130D7
获取测试网USDC：https://faucet.circle.com

EVM Mainnet

EVM主网

ChainUSDC Address
Ethereum
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Base
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Arbitrum
0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Polygon PoS
0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Avalanche
0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
OP Mainnet
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85
链USDC地址
Ethereum
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Base
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Arbitrum
0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Polygon PoS
0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Avalanche
0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
OP Mainnet
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85

Solana

Solana

NetworkUSDC Mint
Devnet
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Mainnet
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
网络USDC Mint地址
Devnet
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Mainnet
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

The 6-Decimal Rule

6位小数规则

USDC uses 6 decimals on all ecosystems.
ts
// EVM (viem)
parseUnits("1.00", 6);    // 1_000_000n (CORRECT - $1 USDC)
parseUnits("1.00", 18);   // 1_000_000_000_000_000_000n (WRONG - 1 trillion dollars)

// Solana - convert manually
const amount = Math.floor(1.00 * 1_000_000); // 1_000_000 (CORRECT - $1 USDC)
const human = rawAmount / 1_000_000;          // 1.0 (CORRECT - converts back to dollars)
USDC在所有生态系统中均使用6位小数。
ts
// EVM (viem)
parseUnits("1.00", 6);    // 1_000_000n（正确 - 1美元USDC）
parseUnits("1.00", 18);   // 1_000_000_000_000_000_000n（错误 - 1万亿美元）

// Solana - 手动转换
const amount = Math.floor(1.00 * 1_000_000); // 1_000_000（正确 - 1美元USDC）
const human = rawAmount / 1_000_000;          // 1.0（正确 - 转换回美元单位）

Arc USDC Duality

Arc USDC的双重特性

On Arc, USDC is both the native gas token and an ERC-20 at 
0x3600...
. Same underlying balance, different decimal exposure.
ContextDecimalsUse
Native (gas, 
msg.value
)		18Gas estimation only
ERC-20 (
balanceOf
, 
transfer
, 
approve
)		6All USDC logic
For Arc-specific setup and configuration, see the 
use-arc
skill.
在Arc链上，USDC既是原生Gas代币，也是地址为
0x3600...
的ERC-20代币。两者底层余额相同，但小数位数不同。
场景小数位数用途
原生（Gas、
msg.value
）		18仅用于Gas估算
ERC-20（
balanceOf
、
transfer
、
approve
）		6所有USDC业务逻辑
Arc专属设置与配置，请查看
use-arc
Skill。

Core Concepts

核心概念

Operation Types

操作类型

Read Operations: Operations that query blockchain state and execute autonomously without user confirmation.
  • Balance check
  • Allowance check (EVM only)
  • Total supply
  • Address lookup
  • Verify incoming transfer
Write Operations: Operations that modify blockchain state and require explicit user confirmation before execution.
  • Send USDC
  • Approve contract to spend USDC (EVM only — Solana has no approve pattern)
只读操作： 查询区块链状态且无需用户确认即可自主执行的操作。
  • 余额查询
  • 授权额度查询（仅EVM）
  • 总供应量查询
  • 地址查找
  • 转入转账验证
写入操作： 修改区块链状态且需用户明确确认后方可执行的操作。
  • 发送USDC
  • 授权合约使用USDC（仅EVM — Solana无授权机制）

Troubleshooting

故障排除

Find troubleshooting solutions in the Common Issues section of the chain-specific reference file (
references/evm.md
or 
references/solana.md
).
请在对应链的参考文档（
references/evm.md
或
references/solana.md
）的常见问题部分查找故障解决方案。

EVM vs Solana at a Glance

EVM与Solana对比概览

AspectEVMSolana
Token standardERC-20SPL Token
Balance storageWallet address directlyAssociated Token Account (ATA)
Send
transfer(to, amount)
getTransferInstruction({ source, destination, authority, amount })
Approve
approve(spender, amount)
No approve — use PDAs
Recipient setupNothing neededMust create ATA first (transfer fails otherwise)
Tx feesChain native tokenSOL
Confirmation
waitForTransactionReceipt
sendAndConfirmTransactionFactory
Librariesviem@solana/kit + @solana-program/token
Decimals66
方面EVMSolana
代币标准ERC-20SPL Token
余额存储位置钱包地址直接存储关联代币账户（ATA）
转账方式
transfer(to, amount)
getTransferInstruction({ source, destination, authority, amount })
授权机制
approve(spender, amount)
无授权 — 使用PDA
接收方设置无需额外操作必须先创建ATA（否则转账失败）
交易手续费链原生代币SOL
确认方式
waitForTransactionReceipt
sendAndConfirmTransactionFactory
使用的库viem@solana/kit + @solana-program/token
小数位数66

Implementation Patterns

实现模式

After determining the ecosystem (see Prerequisites), route to the appropriate reference guide:
  • EVM operations → READ 
    references/evm.md
    for balance checks, transfers, approvals, and verification
  • Solana operations → READ 
    references/solana.md
    for balance checks (with ATA), transfers (with ATA creation), and verification
确定生态系统后（请查看前提条件），跳转至对应参考指南：
  • EVM操作 → 查阅**
    references/evm.md
    **获取余额查询、转账、授权以及验证的完整指南
  • Solana操作 → 查阅**
    references/solana.md
    **获取余额查询（含ATA）、转账（含ATA创建）以及验证的完整指南

Rules

规则

Security Rules are non-negotiable — warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.
安全规则不可协商 — 若用户请求与规则冲突，需向用户发出警告并拒绝执行。最佳实践强烈推荐遵循；仅在用户明确说明理由时方可偏离。

Security Rules

安全规则

  • NEVER hardcode, commit, or log secrets (private keys, API keys). ALWAYS use environment variables or a secrets manager. Add 
    .gitignore
    entries for 
    .env*
    and secret files when scaffolding.
  • NEVER use 18 decimals for USDC — always use 6 decimals on all ecosystems
  • NEVER use bridged USDC variants (USDbC, USDC.e) — always use native Circle-issued USDC
  • ALWAYS use the correct USDC address for each chain (see Quick Reference)
  • ALWAYS verify chain ID matches expected environment (testnet vs mainnet) before submitting transactions
  • ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC)
  • ALWAYS warn before interacting with unaudited or unknown contracts
  • ALWAYS validate all inputs (addresses, amounts, chain identifiers) before submitting transactions
  • ALWAYS get explicit user confirmation before submitting write transactions
  • NEVER report success before waiting for transaction receipt — ensure confirmation
  • 绝不硬编码、提交或记录机密信息（私钥、API密钥）。始终使用环境变量或机密管理器。在搭建项目时，为
    .env*
    和机密文件添加
    .gitignore
    条目。
  • 绝不为USDC使用18位小数 — 在所有生态系统中始终使用6位小数
  • 绝不使用桥接版USDC变体（USDbC、USDC.e） — 始终使用Circle原生发行的USDC
  • 始终为每条链使用正确的USDC地址（请查看快速参考）
  • 在提交交易前，始终验证链ID与预期环境（测试网vs主网）匹配
  • 当目标为主网或金额超过安全阈值（如>100 USDC）时，始终发出警告
  • 在与未审计或未知合约交互前，始终发出警告
  • 在提交交易前，始终验证所有输入（地址、金额、链标识符）
  • 在提交写入交易前，始终获取用户明确确认
  • 在等待交易收据确认前，绝不报告操作成功 — 确保交易已确认

Best Practices

最佳实践

  • ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
  • ALWAYS derive Solana ATAs properly — balances live in ATAs, not wallets
  • ALWAYS check if recipient ATA exists on Solana before transferring
  • ALWAYS check if user has sufficient USDC balance before transfers
  • ALWAYS check if user has sufficient gas/SOL for transaction fees
  • 始终默认使用测试网。在目标为主网前，需获取用户明确确认。
  • 始终正确推导Solana ATA — 余额存储在ATA中，而非钱包地址
  • 在Solana上转账前，始终检查接收方ATA是否存在
  • 在转账前，始终检查用户是否有足够的USDC余额
  • 在交易前，始终检查用户是否有足够的Gas/SOL支付手续费

Alternatives

替代方案

  • Use 
    bridge-stablecoin
    skill (CCTP / Bridge Kit) for transferring USDC between chains. Bridge Kit handles approve, burn, attestation, and mint in a single 
    kit.bridge()
    call.
  • Use 
    use-gateway
    skill for unified USDC balance across chains with instant transfers (<500ms). Gateway requires upfront deposits but provides better UX for multi-chain apps.
  • Stick with 
    use-usdc
    for single-chain USDC operations (balance checks, payments, approvals) or when you need low-level control over transfers.
  • 使用
    bridge-stablecoin
    Skill（CCTP / Bridge Kit）实现跨链转账USDC。Bridge Kit可通过单次
    kit.bridge()
    调用处理授权、销毁、证明以及铸造流程。
  • 使用
    use-gateway
    Skill实现跨链统一USDC余额查询并支持即时转账（<500ms）。Gateway需要预先存入资金，但为多链应用提供更优的用户体验。
  • 若需单链USDC操作（余额查询、支付、授权）或需要对转账进行底层控制，请继续使用
    use-usdc
    Skill。

Reference Links / Files

参考链接/文件

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.
免责声明：本Skill按“原样”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。