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.
Prerequisites / Setup
This skill integrates at the contract level: call the Gateway Wallet and Gateway Minter contracts directly and use the Gateway REST API for attestations. For the @circle-fin/unified-balance-kit SDK that wraps these flows, use the unify-balance skill.
Chain Configuration
Go straight to the matching scenario reference. Verify these only when you need to confirm them:
- Gateway REST base URL
- testnet:
https://gateway-api-testnet.circle.com/v1/
- mainnet:
https://gateway-api.circle.com/v1/
- chain-specific USDC addresses:
https://developers.circle.com/stablecoins/usdc-contract-addresses.md
- Circle Wallet blockchain identifiers:
https://developers.circle.com/wallets/supported-blockchains.md
Canonical source docs for verification:
- Gateway how-tos:
https://developers.circle.com/gateway/howtos/create-unified-usdc-balance.md
https://developers.circle.com/gateway/howtos/manage-delegates.md
https://developers.circle.com/gateway/howtos/transfer-unified-usdc-balance.md
- Gateway quickstarts:
https://developers.circle.com/gateway/quickstarts/unified-balance-evm.md
https://developers.circle.com/gateway/quickstarts/unified-balance-solana.md
- Arc tutorial:
https://docs.arc.io/arc/tutorials/access-usdc-crosschain.md
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
Domain IDs (Mainnet)
| Chain |
Domain |
| Ethereum |
0 |
| Avalanche |
1 |
| OP |
2 |
| Arbitrum |
3 |
| Solana |
5 |
| Base |
6 |
| Polygon PoS |
7 |
| Unichain |
10 |
| Sonic |
13 |
| World Chain |
14 |
| Sei |
16 |
| HyperEVM |
19 |
| Arc |
26 |
Domain IDs (Testnet)
| Chain |
Domain |
| Ethereum Sepolia |
0 |
| Avalanche Fuji |
1 |
| OP Sepolia |
2 |
| Arbitrum Sepolia |
3 |
| Solana Devnet |
5 |
| Base Sepolia |
6 |
| Polygon Amoy |
7 |
| Unichain Sepolia |
10 |
| Sonic Testnet |
13 |
| World Chain Sepolia |
14 |
| Sei Atlantic |
16 |
| HyperEVM Testnet |
19 |
| Arc Testnet |
26 |
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.
Transfer Flow
- Deposit -- User deposits USDC to Gateway Wallet on any chain (adds to unified balance)
- Create burn intent -- Specify source domain, destination domain, recipient, and amount
- Sign -- EIP-712 for EVM sources, Ed25519 for Solana sources
- Submit to Gateway API -- POST burn intent, receive attestation
- Mint on destination -- Call
gatewayMint with attestation on the destination chain
Implementation Patterns
READ the reference files for the scenario(s) that apply.
- Self-managed EVM refs use
viem in Node/TypeScript scripts.
- Self-managed EVM browser-wallet refs use pure TypeScript plus an injected EIP-1193 provider.
- Circle Wallets refs use
@circle-fin/developer-controlled-wallets.
- Solana refs use Anchor plus the relevant Solana tooling.
Deposits
references/deposit-evm.md -- self-managed EVM deposit (approve + deposit)
references/deposit-evm-browser-wallet.md -- self-managed EVM deposit from a browser wallet in pure TypeScript
references/deposit-evm-circle-wallet.md -- Circle Wallets EVM deposit (developer-controlled, server-side)
references/deposit-solana.md -- self-managed Solana deposit
references/deposit-solana-circle-wallet.md -- Circle Wallets Solana deposit
Transfers from EVM
references/evm-to-evm.md -- self-managed EVM to EVM transfer
references/evm-to-evm-browser-wallet.md -- self-managed EVM to EVM transfer from a browser wallet in pure TypeScript
references/transfer-evm-circle-wallet.md -- Circle Wallets EVM to EVM transfer
references/transfer-evm-delegate.md -- SCA depositor on EVM whose burn intents an EOA delegate signs (see SCA source depositors)
references/evm-to-solana.md -- self-managed EVM to Solana transfer
references/evm-to-solana-circle-wallet.md -- Circle Wallets EVM to Solana transfer
Transfers from Solana
references/solana-to-evm.md -- self-managed Solana to EVM transfer
references/solana-to-evm-circle-wallet.md -- Circle Wallets Solana to EVM transfer
references/solana-to-solana.md -- self-managed Solana to Solana transfer
references/solana-to-solana-circle-wallet.md -- Circle Wallets Solana to Solana transfer
Balance queries
references/query-balance.md -- query unified Gateway balances across chains (POST /balances)
Routing
Route to the single best-matching reference by: (1) wallet model -- self-managed or Circle Wallets; (2) source network family -- EVM or Solana; (3) destination network family -- EVM or Solana. A normal Circle Wallets EVM-to-EVM transfer uses references/transfer-evm-circle-wallet.md. Adapt the matched reference; do not scaffold a parallel implementation.
SCA source depositors
An SCA depositor signs burn intents in one of two ways:
- ERC-1271 (no delegate) -- the SCA signs its own burn intent. Set
sourceDepositor = sourceSigner = the SCA, pass the opaque signature bytes that make isValidSignature return 0x1626ba7e (do not split into v, r, s), and POST { burnIntent, signature, contractSigner: true }. No reference file covers this path; follow https://developers.circle.com/gateway/howtos/transfer-with-erc-1271.md. Use it for any SCA, including Circle Developer-Controlled Wallets SCAs (sign with client.signTypedData from the SCA wallet). Not supported for Gateway Nanopayments or x402 batch settlement.
- EOA delegate (optional alternative) -- an SCA that has added an EOA delegate on the source chain, which signs its burn intents ->
references/transfer-evm-delegate.md. Do NOT use it for an ordinary (EOA) Circle Wallets transfer.
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.
Best Practices
- ALWAYS read the matching scenario reference before implementing; load extra verification context only when it lacks something.
- 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)).
- In React apps that already use wagmi, prefer the existing wagmi/provider pattern instead of introducing a parallel wallet connection stack.
- For framework-agnostic browser-wallet flows, use the pure TypeScript EIP-1193 pattern in the browser-wallet refs.
- ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
Alternatives
- Trigger
bridge-tokens 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: a Solana burn intent is a binary message (0xff-prefixed, not UTF-8 text) signed with the wallet's signMessage. Some browser wallets refuse non-text messages, so confirm the target wallet signs one on devnet before relying on it.
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.
1---2name: use-gateway3description: "Integrate Circle Gateway to hold a unified USDC balance across multiple blockchains and transfer USDC instantly (<500ms) via permissionless deposit, burn, and mint workflows. Available on 11 EVM chains + Solana (mainnet and testnet), plus Arc (mainnet and testnet). Use when: enabling chain-agnostic user experiences, low-latency or instant next-block finality is required, capital needs to be pooled across chains for greater capital efficiency, or building apps with consolidated crosschain balances. Triggers on: Gateway, Gateway Wallet, Gateway Minter, gatewayMint, burn intent, unified balance, instant crosschain transfer."4requirements:5 runtimes: []6 connectors: []7metadata:8 source: https://skillmd.com/skills/jiayaoqijia/use-gateway9---1011## Overview1213Circle 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.1415## Prerequisites / Setup1617This skill integrates at the contract level: call the Gateway Wallet and Gateway Minter contracts directly and use the Gateway REST API for attestations. For the `@circle-fin/unified-balance-kit` SDK that wraps these flows, use the `unify-balance` skill.1819### Chain Configuration2021Go straight to the matching scenario reference. Verify these only when you need to confirm them:2223- Gateway REST base URL24 - testnet: `https://gateway-api-testnet.circle.com/v1/`25 - mainnet: `https://gateway-api.circle.com/v1/`26- chain-specific USDC addresses: `https://developers.circle.com/stablecoins/usdc-contract-addresses.md`27- Circle Wallet blockchain identifiers: `https://developers.circle.com/wallets/supported-blockchains.md`2829Canonical source docs for verification:3031- Gateway how-tos:32 - `https://developers.circle.com/gateway/howtos/create-unified-usdc-balance.md`33 - `https://developers.circle.com/gateway/howtos/manage-delegates.md`34 - `https://developers.circle.com/gateway/howtos/transfer-unified-usdc-balance.md`35- Gateway quickstarts:36 - `https://developers.circle.com/gateway/quickstarts/unified-balance-evm.md`37 - `https://developers.circle.com/gateway/quickstarts/unified-balance-solana.md`38- Arc tutorial: `https://docs.arc.io/arc/tutorials/access-usdc-crosschain.md`3940## Quick Reference4142### Key Addresses4344**EVM Mainnet (All Chains)**45- Gateway Wallet: `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`46- Gateway Minter: `0x2222222d7164433c4C09B0b0D809a9b52C04C205`4748**EVM Testnet (All Chains)**49- Gateway Wallet: `0x0077777d7EBA4688BDeF3E311b846F25870A19B9`50- Gateway Minter: `0x0022222ABE238Cc2C7Bb1f21003F0a260052475B`5152**Solana Mainnet**53- Gateway Wallet: `GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ`54- Gateway Minter: `GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ`5556**Solana Devnet**57- Gateway Wallet: `GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu`58- Gateway Minter: `GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr`59- USDC Mint: `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`6061### Domain IDs (Mainnet)6263| Chain | Domain |64| --- | --- |65| Ethereum | 0 |66| Avalanche | 1 |67| OP | 2 |68| Arbitrum | 3 |69| Solana | 5 |70| Base | 6 |71| Polygon PoS | 7 |72| Unichain | 10 |73| Sonic | 13 |74| World Chain | 14 |75| Sei | 16 |76| HyperEVM | 19 |77| Arc | 26 |7879### Domain IDs (Testnet)8081| Chain | Domain |82| --- | --- |83| Ethereum Sepolia | 0 |84| Avalanche Fuji | 1 |85| OP Sepolia | 2 |86| Arbitrum Sepolia | 3 |87| Solana Devnet | 5 |88| Base Sepolia | 6 |89| Polygon Amoy | 7 |90| Unichain Sepolia | 10 |91| Sonic Testnet | 13 |92| World Chain Sepolia | 14 |93| Sei Atlantic | 16 |94| HyperEVM Testnet | 19 |95| Arc Testnet | 26 |9697## Core Concepts9899### Unified Balance100101Gateway 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.102103Think 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.104105**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.106107### Transfer Flow1081091. **Deposit** -- User deposits USDC to Gateway Wallet on any chain (adds to unified balance)1102. **Create burn intent** -- Specify source domain, destination domain, recipient, and amount1113. **Sign** -- EIP-712 for EVM sources, Ed25519 for Solana sources1124. **Submit to Gateway API** -- POST burn intent, receive attestation1135. **Mint on destination** -- Call `gatewayMint` with attestation on the destination chain114115## Implementation Patterns116117**READ** the reference files for the scenario(s) that apply.118119- Self-managed EVM refs use `viem` in Node/TypeScript scripts.120- Self-managed EVM browser-wallet refs use pure TypeScript plus an injected EIP-1193 provider.121- Circle Wallets refs use `@circle-fin/developer-controlled-wallets`.122- Solana refs use Anchor plus the relevant Solana tooling.123124### Deposits125- `references/deposit-evm.md` -- self-managed EVM deposit (approve + deposit)126- `references/deposit-evm-browser-wallet.md` -- self-managed EVM deposit from a browser wallet in pure TypeScript127- `references/deposit-evm-circle-wallet.md` -- Circle Wallets EVM deposit (developer-controlled, server-side)128- `references/deposit-solana.md` -- self-managed Solana deposit129- `references/deposit-solana-circle-wallet.md` -- Circle Wallets Solana deposit130### Transfers from EVM131- `references/evm-to-evm.md` -- self-managed EVM to EVM transfer132- `references/evm-to-evm-browser-wallet.md` -- self-managed EVM to EVM transfer from a browser wallet in pure TypeScript133- `references/transfer-evm-circle-wallet.md` -- Circle Wallets EVM to EVM transfer134- `references/transfer-evm-delegate.md` -- SCA depositor on EVM whose burn intents an EOA delegate signs (see SCA source depositors)135- `references/evm-to-solana.md` -- self-managed EVM to Solana transfer136- `references/evm-to-solana-circle-wallet.md` -- Circle Wallets EVM to Solana transfer137### Transfers from Solana138- `references/solana-to-evm.md` -- self-managed Solana to EVM transfer139- `references/solana-to-evm-circle-wallet.md` -- Circle Wallets Solana to EVM transfer140- `references/solana-to-solana.md` -- self-managed Solana to Solana transfer141- `references/solana-to-solana-circle-wallet.md` -- Circle Wallets Solana to Solana transfer142### Balance queries143- `references/query-balance.md` -- query unified Gateway balances across chains (POST `/balances`)144145### Routing146147Route to the single best-matching reference by: (1) wallet model -- self-managed or Circle Wallets; (2) source network family -- EVM or Solana; (3) destination network family -- EVM or Solana. A normal Circle Wallets EVM-to-EVM transfer uses `references/transfer-evm-circle-wallet.md`. Adapt the matched reference; do not scaffold a parallel implementation.148149### SCA source depositors150151An SCA depositor signs burn intents in one of two ways:152153- **ERC-1271 (no delegate)** -- the SCA signs its own burn intent. Set `sourceDepositor` = `sourceSigner` = the SCA, pass the opaque signature bytes that make `isValidSignature` return `0x1626ba7e` (do not split into `v`, `r`, `s`), and POST `{ burnIntent, signature, contractSigner: true }`. No reference file covers this path; follow `https://developers.circle.com/gateway/howtos/transfer-with-erc-1271.md`. Use it for any SCA, including Circle Developer-Controlled Wallets SCAs (sign with `client.signTypedData` from the SCA wallet). Not supported for Gateway Nanopayments or x402 batch settlement.154- **EOA delegate (optional alternative)** -- an SCA that has added an EOA delegate on the source chain, which signs its burn intents -> `references/transfer-evm-delegate.md`. Do NOT use it for an ordinary (EOA) Circle Wallets transfer.155156## Rules157158**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.159160### Security Rules161162- 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.163- 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.164- 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.165- NEVER sign Solana burn intents without prefixing the payload with 16 bytes (`0xff` + 15 zero bytes) before Ed25519 signing.166- ALWAYS require explicit user confirmation of destination, amount, source/destination network, and token before executing transfers. NEVER auto-execute fund movements on mainnet.167- ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).168- ALWAYS validate all inputs (addresses, amounts, domain IDs) before submitting transactions.169- ALWAYS warn before interacting with unaudited or unknown contracts.170171### Best Practices172173- ALWAYS read the matching scenario reference before implementing; load extra verification context only when it lacks something.174- NEVER omit `sourceDomain` and `destinationDomain` -- every transfer requires both, even with a unified balance.175- NEVER use 18 decimals for USDC. ALWAYS use 6 decimals (`parseUnits(amount, 6)`).176- In React apps that already use wagmi, prefer the existing wagmi/provider pattern instead of introducing a parallel wallet connection stack.177- For framework-agnostic browser-wallet flows, use the pure TypeScript EIP-1193 pattern in the browser-wallet refs.178- ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.179180## Alternatives181182- Trigger `bridge-tokens` 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.183- CCTP is a better fit for **infrequent or ad-hoc** transfers where maintaining a unified balance is not worth the upfront deposit.184- Stick with Gateway when you need instant (<500ms) transfers, a unified balance model, or capital efficiency across chains.185186WARNING: a Solana burn intent is a binary message (`0xff`-prefixed, not UTF-8 text) signed with the wallet's `signMessage`. Some browser wallets refuse non-text messages, so confirm the target wallet signs one on devnet before relying on it.187188## Reference Links189190- [Circle Developer Docs](https://developers.circle.com/llms.txt) -- **Always read this first** when looking for relevant documentation from the source website.191192---193194DISCLAIMER: This skill is provided "as is" without warranties, is subject to the [Circle Developer Terms](https://console.circle.com/legal/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](https://github.com/circlefin/skills/blob/master/README.md).