use-usdc

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.

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.

Dependencies

EVM:

npm install viem

Solana:

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.

Quick Reference

USDC Contract Addresses

Canonical source: https://developers.circle.com/stablecoins/usdc-contract-addresses

EVM Testnet

Get testnet USDC: https://faucet.circle.com

EVM Mainnet

Solana

The 6-Decimal Rule

USDC uses 6 decimals on all ecosystems.

// 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)

Arc USDC Duality

On Arc, USDC is both the native gas token and an ERC-20 at 0x3600.... Same underlying balance, different decimal exposure.

For Arc-specific setup and configuration, see the 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)

Troubleshooting

Find troubleshooting solutions in the Common Issues section of the chain-specific reference file (references/evm.md or references/solana.md).

EVM vs Solana at a Glance

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

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

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

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.

Reference Links / Files

• EVM Operations Guide: references/evm.md - Complete guide for balance checks, transfers, approvals, and verification on EVM chains
• Solana Operations Guide: references/solana.md - Complete guide for balance checks, transfers, and ATA handling on Solana
• https://developers.circle.com/stablecoins/usdc-contract-addresses
• https://developers.circle.com
• https://faucet.circle.com
• https://faucet.solana.com
• https://viem.sh
• https://github.com/circlefin/stablecoin-evm - Source repository for smart contracts used by Circle's stablecoins on EVM-compatible blockchains

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.