Back to Details

use-gateway

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Overview

概述

Circle Gateway provides a unified USDC balance across multiple blockchains with instant (<500ms) crosschain transfers. Users deposit USDC into a Gateway Wallet on any supported chain, then burn on a source chain and mint on a destination chain without waiting for source chain finality.
Circle Gateway可在多条区块链上提供统一的USDC余额，并支持即时（<500毫秒）跨链转账。用户可在任意支持链上将USDC存入Gateway Wallet，随后在源链销毁USDC，无需等待源链终局性即可在目标链铸造USDC。

Prerequisites / Setup

前提条件/设置

Gateway is a contract-level integration -- there is no SDK to install. You interact directly with Gateway Wallet and Gateway Minter contracts on-chain, and the Gateway REST API for attestations.
Gateway是合约级别的集成——无需安装SDK。你可以直接与链上的Gateway Wallet和Gateway Minter合约交互，并通过Gateway REST API获取证明。

Chain Configuration

链配置

You must read and refer to 
references/config.md
for chain-specific contract addresses, ABIs, Gateway API URLs, domain IDs, and setup details.
你必须阅读并参考
references/config.md
，获取各链专属的合约地址、ABI、Gateway API URL、域ID和设置细节。

Quick Reference

快速参考

Key Addresses

关键地址

EVM Mainnet (All Chains)
  • Gateway Wallet: 
    0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE
  • Gateway Minter: 
    0x2222222d7164433c4C09B0b0D809a9b52C04C205
EVM Testnet (All Chains)
  • Gateway Wallet: 
    0x0077777d7EBA4688BDeF3E311b846F25870A19B9
  • Gateway Minter: 
    0x0022222ABE238Cc2C7Bb1f21003F0a260052475B
Solana Mainnet
  • Gateway Wallet: 
    GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ
  • Gateway Minter: 
    GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ
Solana Devnet
  • Gateway Wallet: 
    GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu
  • Gateway Minter: 
    GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr
  • USDC Mint: 
    4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
EVM主网（所有链）
  • Gateway Wallet: 
    0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE
  • Gateway Minter: 
    0x2222222d7164433c4C09B0b0D809a9b52C04C205
EVM测试网（所有链）
  • Gateway Wallet: 
    0x0077777d7EBA4688BDeF3E311b846F25870A19B9
  • Gateway Minter: 
    0x0022222ABE238Cc2C7Bb1f21003F0a260052475B
Solana主网
  • Gateway Wallet: 
    GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ
  • Gateway Minter: 
    GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ
Solana Devnet
  • Gateway Wallet: 
    GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu
  • Gateway Minter: 
    GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr
  • USDC Mint: 
    4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

Domain IDs (Mainnet)

域ID（主网）

ChainDomain
Ethereum0
Avalanche1
OP2
Arbitrum3
Solana5
Base6
Polygon PoS7
Unichain10
Sonic13
World Chain14
Sei16
HyperEVM19
区块链域ID
Ethereum0
Avalanche1
OP2
Arbitrum3
Solana5
Base6
Polygon PoS7
Unichain10
Sonic13
World Chain14
Sei16
HyperEVM19

Domain IDs (Testnet)

域ID（测试网）

ChainDomain
Ethereum Sepolia0
Avalanche Fuji1
OP Sepolia2
Arbitrum Sepolia3
Solana Devnet5
Base Sepolia6
Polygon Amoy7
Unichain Sepolia10
Sonic Testnet13
World Chain Sepolia14
Sei Atlantic16
HyperEVM Testnet19
Arc Testnet26
区块链域ID
Ethereum Sepolia0
Avalanche Fuji1
OP Sepolia2
Arbitrum Sepolia3
Solana Devnet5
Base Sepolia6
Polygon Amoy7
Unichain Sepolia10
Sonic Testnet13
World Chain Sepolia14
Sei Atlantic16
HyperEVM Testnet19
Arc Testnet26

Core Concepts

核心概念

Unified Balance

统一余额

Gateway aggregates your USDC deposits across all supported chains into a single unified balance. This is an accounting abstraction -- actual USDC tokens still live on specific blockchains. Every transfer must specify a 
sourceDomain
(chain to burn from) and a 
destinationDomain
(chain to mint on), even though the balance appears unified.
Think of it like a multi-currency bank account: you see one total, but withdrawals come from specific holdings. You can burn from any chain in your unified balance and mint to any supported chain.
Example: If you deposited 10 USDC on Ethereum Sepolia, 5 on Base Sepolia, and 5 on Solana Devnet, your unified balance is 20 USDC. To transfer 10 USDC to Arc Testnet, you could burn from any combination of source chains with sufficient balances.
Gateway会将你在所有支持链上的USDC存款汇总为单一的统一余额。这是一种会计抽象——实际的USDC代币仍存储在特定区块链上。每笔转账都必须指定
sourceDomain
（销毁代币的链）和
destinationDomain
（铸造代币的链），即使余额显示为统一的。
可以把它想象成多币种银行账户：你看到的是一个总余额，但取款来自特定的持仓。你可以从统一余额中的任意链销毁代币，并在任意支持链上铸造代币。
**示例：**如果你在Ethereum Sepolia存入10 USDC，在Base Sepolia存入5 USDC，在Solana Devnet存入5 USDC，你的统一余额就是20 USDC。要转账10 USDC到Arc Testnet，你可以从余额充足的任意源链组合中销毁代币。

Transfer Flow

转账流程

  1. Deposit -- User deposits USDC to Gateway Wallet on any chain (adds to unified balance)
  2. Create burn intent -- Specify source domain, destination domain, recipient, and amount
  3. Sign -- EIP-712 for EVM sources, Ed25519 for Solana sources
  4. Submit to Gateway API -- POST burn intent, receive attestation
  5. Mint on destination -- Call 
    gatewayMint
    with attestation on the destination chain
  1. 存入——用户在任意链上将USDC存入Gateway Wallet（增加统一余额）
  2. 创建销毁意向——指定源域、目标域、收款人和金额
  3. 签名——EVM源链使用EIP-712签名，Solana源链使用Ed25519签名
  4. 提交至Gateway API——POST销毁意向，获取证明
  5. 在目标链铸造——在目标链调用
    gatewayMint
    并传入证明

Implementation Patterns

实现模式

READ the reference files for the scenario(s) that apply. All vanilla EVM examples use 
wagmi@^3
.
  • references/deposit-evm.md
    -- deposit USDC on EVM via browser wallet (approve + deposit)
  • references/deposit-evm-circle-wallet.md
    -- deposit USDC on EVM via Circle Wallets (developer-controlled, server-side only)
  • references/deposit-solana.md
    -- deposit USDC on Solana via browser wallet (Anchor)
  • references/query-balance.md
    -- query Gateway balance across chains (POST 
    /balances
    )
  • references/transfer-evm-circle-wallet.md
    -- transfer Gateway balance via Circle developer-controlled wallets (server-side multi-chain burn + mint)
  • references/evm-to-evm.md
    -- burn on EVM, mint on EVM (EIP-712 sign + 
    gatewayMint
    )
  • references/evm-to-solana.md
    -- burn on EVM, mint on Solana
  • references/solana-to-evm.md
    -- burn on Solana, mint on EVM
  • references/solana-to-solana.md
    -- burn on Solana, mint on Solana
阅读与你场景匹配的参考文件。所有原生EVM示例均使用
wagmi@^3
。
  • references/deposit-evm.md
    ——通过浏览器钱包在EVM链存入USDC（授权+存入）
  • references/deposit-evm-circle-wallet.md
    ——通过Circle钱包在EVM链存入USDC（仅开发者可控，服务端专用）
  • references/deposit-solana.md
    ——通过浏览器钱包在Solana链存入USDC（基于Anchor）
  • references/query-balance.md
    ——跨链查询Gateway余额（POST 
    /balances
    ）
  • references/transfer-evm-circle-wallet.md
    ——通过Circle开发者可控钱包转账Gateway余额（服务端多链销毁+铸造）
  • references/evm-to-evm.md
    ——在EVM链销毁，在EVM链铸造（EIP-712签名+
    gatewayMint
    ）
  • references/evm-to-solana.md
    ——在EVM链销毁，在Solana链铸造
  • references/solana-to-evm.md
    ——在Solana链销毁，在EVM链铸造
  • references/solana-to-solana.md
    ——在Solana链销毁，在Solana链铸造

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, signing keys). ALWAYS use environment variables or a secrets manager. Add 
    .gitignore
    entries for 
    .env*
    and secret files when scaffolding.
  • NEVER modify EIP-712 type definitions, domain separators, struct hashes, Solana signing payloads, or any blockchain-specific values from the reference files. Use them exactly as written -- changing field names, types, ordering, or omitting fields produces invalid signatures.
  • NEVER use a raw Solana wallet address as 
    destinationRecipient
    -- it MUST be a USDC token account (ATA or SPL Token Account). Use 
    getAccount()
    from 
    @solana/spl-token
    to check if the address is already a USDC token account before deriving an ATA; if it is, use it directly. Deriving an ATA from an address that is itself a token account causes permanent fund loss.
  • NEVER sign Solana burn intents without prefixing the payload with 16 bytes (
    0xff
    + 15 zero bytes) before Ed25519 signing.
  • ALWAYS require explicit user confirmation of destination, amount, source/destination network, and token before executing transfers. NEVER auto-execute fund movements on mainnet.
  • ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
  • ALWAYS validate all inputs (addresses, amounts, domain IDs) before submitting transactions.
  • ALWAYS warn before interacting with unaudited or unknown contracts.
  • 绝对不要硬编码、提交或记录密钥（私钥、签名密钥）。务必使用环境变量或密钥管理器。在搭建项目时，将
    .env*
    和密钥文件添加到
    .gitignore
    中。
  • 绝对不要修改参考文件中的EIP-712类型定义、域分隔符、结构体哈希、Solana签名负载或任何区块链专属值。严格按照原文使用——修改字段名称、类型、顺序或省略字段会生成无效签名。
  • 绝对不要将原始Solana钱包地址作为
    destinationRecipient
    ——必须使用USDC代币账户（ATA或SPL代币账户）。在派生ATA之前，使用
    @solana/spl-token
    中的
    getAccount()
    检查地址是否已为USDC代币账户；如果是，则直接使用该地址。从本身已是代币账户的地址派生ATA会导致资金永久损失。
  • 在对Solana销毁意向进行Ed25519签名之前，绝对不要忘记在负载前添加16字节（
    0xff
    +15个零字节）。
  • 在执行转账前，务必要求用户明确确认目标地址、金额、源/目标网络和代币。绝对不要在主网自动执行资金划转。
  • 当目标为主网或超过安全阈值（例如>100 USDC）时，务必发出警告。
  • 在提交交易前，务必验证所有输入（地址、金额、域ID）。
  • 在与未审计或未知合约交互前，务必发出警告。

Best Practices

最佳实践

  • ALWAYS read the correct reference files before implementing.
  • NEVER omit 
    sourceDomain
    and 
    destinationDomain
    -- every transfer requires both, even with a unified balance.
  • NEVER use 18 decimals for USDC. ALWAYS use 6 decimals (
    parseUnits(amount, 6)
    ).
  • NEVER use 
    window.ethereum
    directly with wagmi -- use 
    connector.getProvider()
    .
  • ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
  • 在实现前，务必阅读正确的参考文件。
  • 绝对不要省略
    sourceDomain
    和
    destinationDomain
    ——每笔转账都需要这两个参数，即使使用统一余额也不例外。
  • 绝对不要为USDC使用18位小数。务必使用6位小数（
    parseUnits(amount, 6)
    ）。
  • 绝对不要在wagmi中直接使用
    window.ethereum
    ——使用
    connector.getProvider()
    。
  • 务必默认使用测试网。在目标为主网前，需要用户明确确认。

Alternatives

替代方案

  • Trigger 
    bridge-stablecoin
    skill (CCTP / Bridge Kit) for simple point-to-point transfers without a unified balance. Bridge Kit handles approve, burn, attestation, and mint in a single 
    kit.bridge()
    call and supports more chains than Gateway.
  • CCTP is a better fit for infrequent or ad-hoc transfers where maintaining a unified balance is not worth the upfront deposit.
  • Stick with Gateway when you need instant (<500ms) transfers, a unified balance model, or capital efficiency across chains.
WARNING: Solana wallet compatibility is limited for Gateway. Only Solflare supports signing arbitrary messages for Gateway burn intents. Phantom and most other Solana wallets will reject the signing request.
  • 若无需统一余额，仅需简单的点对点转账，可触发
    bridge-stablecoin
    技能（CCTP / Bridge Kit）。Bridge Kit通过单次
    kit.bridge()
    调用处理授权、销毁、证明和铸造，且支持的链比Gateway更多。
  • 对于不频繁或临时的转账，CCTP是更好的选择，因为无需为维护统一余额而预先存入资金。
  • 当你需要即时（<500毫秒）转账、统一余额模型或跨链资本效率时，请选择Gateway。
警告：Gateway对Solana钱包的兼容性有限。仅Solflare支持为Gateway销毁意向签署任意消息。Phantom和大多数其他Solana钱包会拒绝该签名请求。

Reference Links

参考链接

  • Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.
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.
免责声明：本技能按“现状”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。