Skip to main content
The CCTP CLI provides a powerful, user-friendly command-line interface for transferring USDC across multiple blockchain networks using Circle’s Cross-Chain Transfer Protocol V2.

​
What is the CCTP CLI?

The CCTP CLI is an interactive terminal application that enables you to:
  • Transfer USDC seamlessly across 16 mainnet chains and 17 testnet chains
  • Choose between Fast Transfer (~8-20 seconds with fee) or Standard Transfer (~13-19 minutes, no fee)
  • Resume interrupted transfers using transaction hashes
  • Manage wallets through private keys or Ethereum keystore files
  • Configure custom RPC endpoints and default transfer values

​
Key Features

​
Interactive Terminal UI

The CLI features a rich terminal user interface (TUI) built with Bubble Tea that provides:
  • Real-time transfer status updates
  • Step-by-step guidance through the transfer process
  • Chain selection with automatic capability detection
  • Wallet account selection from keystore
  • Mouse and keyboard navigation support

​
Dual Transfer Modes

Fast Transfer

Complete transfers in 8-20 seconds using Circle’s Fast Transfer Allowance. Small fee applies (1-14 bps depending on chain).

Standard Transfer

Wait for hard finality (~13-19 minutes for most chains, ~8 seconds for instant finality chains). No fee - currently 0 bps.

​
Flexible Wallet Support

Authenticate using either:
  • Private Key: Set via PRIVATE_KEY environment variable
  • Keystore File: Point to your Ethereum keystore directory with password protection

​
Configuration Management

Powered by Viper, the CLI supports multiple configuration sources with clear precedence:
  1. Command-line flags (highest priority)
  2. Environment variables (with CCTP_ prefix)
  3. Configuration file (~/.cctp/config.yaml)
  4. Default values

​
Transfer Types Explained

How it works: Uses Circle’s Fast Transfer Allowance to enable faster-than-finality transfers.Timing: ~8-20 secondsFee: 1-14 bps (0.01%-0.14%) depending on source chain
  • Most chains: 1 bps (0.01%)
  • Linea: 14 bps (0.14%) - highest fee
  • Ink, Plume: 2 bps (0.02%)
Availability: Not available when instant finality chains are used as source (Avalanche, Polygon, Sei, Sonic, XDC, HyperEVM, Arc)Best for: Time-sensitive transfers where speed is critical
How it works: Waits for hard finality on the source chain before Circle provides attestation.Timing:
  • Most chains: ~13-19 minutes
  • Instant finality chains: ~8 seconds (Avalanche, Polygon, Sei, Sonic, XDC, HyperEVM, Arc)
Fee: 0 bps (no fee)Availability: Available on all chainsBest for: Cost-conscious transfers or when using instant finality source chains
How it works: Automatically selects the best transfer type based on chain capabilities.Logic:
  • Uses Fast Transfer when available (non-instant finality source chains)
  • Falls back to Standard Transfer for instant finality source chains
Best for: Most users who want the CLI to choose the optimal transfer type

​
Supported Chains

The CLI supports:
  • 16 Mainnet chains: Ethereum, Avalanche, OP Mainnet, Arbitrum, Base, Polygon PoS, Unichain, Linea, Codex, Sonic, World Chain, Sei, XDC, HyperEVM, Ink, Plume, and more
  • 17 Testnet chains: Including Sepolia variants and dedicated testnets
Instant finality chains (Avalanche, Polygon, Sei, Sonic, XDC, HyperEVM, Arc) only support Standard Transfer when used as the source chain, but complete in ~8 seconds with no fee.

​
Command Structure

The CLI uses Cobra for command organization: 
cctp [command] [flags]

​
Available Commands

  • transfer - Start a new USDC transfer
  • resume - Resume an existing transfer by transaction hash
  • version - Print CLI version information
  • help - Display help for any command
  • completion - Generate shell completion scripts

​
Global Flags

These flags work with all commands:
  • --config - Path to config file (default: $HOME/.cctp/config.yaml)
  • --testnet - Use testnet instead of mainnet
  • --keystore - Path to Ethereum keystore directory

​
Typical Workflow

1

Install the CLI

Install using Go’s package manager:
go install github.com/circlefin/cctp-go/cmd/cctp@latest
2

Set up wallet authentication

Choose your preferred method:
# Option 1: Private key
export PRIVATE_KEY=0x...

# Option 2: Keystore
cctp transfer --keystore ~/.ethereum/keystore
3

Start a transfer

Launch the interactive TUI:
cctp transfer
Or pre-populate parameters:
cctp transfer --source ethereum --dest arbitrum --amount 100
4

Follow the interactive prompts

The TUI guides you through:
  • Selecting source and destination chains
  • Choosing transfer type (fast/standard/auto)
  • Entering amount and recipient address
  • Confirming transaction details
5

Monitor transfer status

The CLI displays real-time status updates showing:
  • Transaction submission
  • Attestation progress
  • Completion confirmation

​
Version Information

Current CLI version: 0.2.0 Check your installed version: 
cctp version

​
Next Steps

Installation

Install the CLI using Go’s package manager

Commands

Learn all available CLI commands and flags

Configuration

Set up config files, keystores, and RPC endpoints

Quick Start

Complete tutorial from installation to first transfer

Build docs developers (and LLMs) love

Get started for freeTalk to us