Deploy a native crosschain token

Deploying a native crosschain token creates a brand-new ERC-20 that the protocol manages across multiple blockchains, with no pre-existing contract required. The service uses CREATE3 to deploy a CrossChainToken ERC-20 and a NATIVE_CROSSCHAIN_TOKEN TokenManager at deterministic addresses derived from your deployment wallet and a salt you choose. This quickstart walks you through deploying on Ethereum Sepolia and extending the token to Base Sepolia.

Three conditions silently block or break deployment if not met:

Same wallet and salt on every blockchain: The tokenId is derived from (deployer address, salt). Using a different wallet or a different salt on any blockchain produces a different tokenId—no error is thrown, and the bridge connection is silently broken.
Rate limit starts at zero: Every TokenManager deploys with rateLimit = 0, which blocks all transfers. You must call setRateLimit with a non-zero value on each blockchain before any transfer can proceed.
name, symbol, and decimals must match on every blockchain: The protocol does not enforce consistency. A mismatch breaks user experience and indexers silently—there is no onchain error.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22+
Prepared an Ethereum-compatible testnet wallet whose private key you have available—this is the deployment wallet, and it must be the same wallet used on every blockchain
Funded the wallet with Sepolia ETH and Base Sepolia ETH for gas
Obtained access to the Iris fee-quote endpoint (POST /v2/quote/cctpx/{tokenId}/{sourceDomain}/{destinationDomain})

Step 1: Set up the project

1.1. Create the project and install dependencies

mkdir cctpx-deploy
cd cctpx-deploy
npm init -y

npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env index.ts"

npm install viem
npm install --save-dev @types/node tsx typescript

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file:

npx tsc --init

Then, update the tsconfig.json file:

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Open .env in your editor and add:

PRIVATE_KEY=YOUR_DEPLOYER_PRIVATE_KEY

PRIVATE_KEY is the private key for the wallet that deploys the token. You must use this same wallet on every blockchain where you deploy.

Open .env in your editor rather than writing values with shell commands, and add .env to your .gitignore. This prevents credentials from leaking into your shell history or version control.

The npm run start command loads variables from .env using Node.js native env-file support.

This example uses one or more private keys for local testing. In production, use a secure key management solution and never expose or share private keys.

Step 2: Configure clients and define token metadata

Create index.ts. Set up public and wallet clients for both blockchains, then define your token metadata and a bytes32 salt. The salt, together with your deployer address, determines your token’s tokenId—it must be identical on every blockchain.

import {
  createPublicClient,
  createWalletClient,
  encodePacked,
  http,
  keccak256,
  toBytes,
  zeroAddress,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, sepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const sepoliaPublic = createPublicClient({
  chain: sepolia,
  transport: http(),
});

const sepoliaWallet = createWalletClient({
  account,
  chain: sepolia,
  transport: http(),
});

const basePublic = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

const baseWallet = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

// CrossChainTokenService — same address on all testnets
const CCTS_ADDRESS = "0x63753E722bd2C2A5DF6EE19C5106662208B81077" as const;

const IRIS_BASE = "https://iris-api-sandbox.circle.com";

// Token metadata — must be identical on every blockchain you deploy to
const TOKEN_NAME = "My Token";
const TOKEN_SYMBOL = "MTKN";
const TOKEN_DECIMALS = 6;

// bytes32 salt — must be the same on every blockchain you deploy to.
// Use any unique bytes32 value; hashing a descriptive string is one approach.
const salt: `0x${string}` = keccak256(toBytes("my-token-v1"));

Compute your tokenId using the crossChainTokenId view call. Pass the raw salt directly—not customTokenDeploySalt, which is only used by registerCustomToken.

const serviceAbi = [
  {
    name: "crossChainTokenId",
    type: "function",
    stateMutability: "pure",
    inputs: [
      { name: "deployer", type: "address" },
      { name: "salt", type: "bytes32" },
    ],
    outputs: [{ name: "tokenId", type: "bytes32" }],
  },
  {
    name: "resolveTokenAddress",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "tokenId", type: "bytes32" }],
    outputs: [{ name: "token", type: "address" }],
  },
  {
    name: "resolveTokenManager",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "tokenId", type: "bytes32" }],
    outputs: [{ name: "tokenManager", type: "address" }],
  },
] as const;

const tokenId = await sepoliaPublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "crossChainTokenId",
  args: [account.address, salt],
});

console.log("Your tokenId:", tokenId);
// Note this value — it will be identical on every blockchain you deploy to.

Step 3: Deploy on Ethereum Sepolia

Call deployCrossChainToken on Ethereum Sepolia. No fee quote is needed—this is a local CREATE3 deploy. The protocol creates the CrossChainToken ERC-20 and a NATIVE_CROSSCHAIN_TOKEN TokenManager in the same transaction.

Verify the live ABI before copying this struct. The sandbox contract’s DeploymentParams may omit initialSupply while the production contract includes it, or vice versa. A struct with the wrong number of fields causes the transaction to revert. Fetch the ABI from the contract source for the blockchain you are targeting before submitting, and add or remove initialSupply accordingly. The following code includes it based on the documented production struct.

deployCrossChainToken is payable. No fee is charged on testnet, so you can omit value. If you are deploying on mainnet, verify whether a fee applies before submitting.

const deployAbi = [
  {
    name: "deployCrossChainToken",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "salt", type: "bytes32" },
      { name: "name", type: "string" },
      { name: "symbol", type: "string" },
      { name: "decimals", type: "uint8" },
      {
        name: "params",
        type: "tuple",
        components: [
          { name: "tokenManagerType", type: "uint8" },
          { name: "tokenManagerOwner", type: "bytes" },
          { name: "tokenManagerOperator", type: "bytes" },
          { name: "tokenOwner", type: "bytes" },
          { name: "tokenMinter", type: "bytes" },
          // WARNING: may be absent in the sandbox ABI — verify before submitting
          { name: "initialSupply", type: "uint256" },
          {
            name: "tokenManagerSettings",
            type: "tuple",
            components: [
              { name: "rateLimit", type: "uint256" },
              { name: "maxTransferAmount", type: "uint256" },
            ],
          },
        ],
      },
    ],
    outputs: [{ name: "tokenId", type: "bytes32" }],
  },
] as const;

// Encode addresses as 20-byte packed bytes.
// Do NOT use encodeAbiParameters, which pads to 32 bytes and is incompatible
// with the contract's address decoding.
const ownerBytes = encodePacked(["address"], [account.address]);
const operatorBytes = encodePacked(["address"], [account.address]);

const sepoliaDeployHash = await sepoliaWallet.writeContract({
  address: CCTS_ADDRESS,
  abi: deployAbi,
  functionName: "deployCrossChainToken",
  args: [
    salt,
    TOKEN_NAME,
    TOKEN_SYMBOL,
    TOKEN_DECIMALS,
    {
      tokenManagerType: 0, // NATIVE_CROSSCHAIN_TOKEN
      tokenManagerOwner: ownerBytes,
      tokenManagerOperator: operatorBytes,
      tokenOwner: ownerBytes,
      tokenMinter: ownerBytes,
      initialSupply: 0n, // see ABI warning above
      tokenManagerSettings: {
        rateLimit: 0n, // intentionally 0; you set a non-zero value in step 7
        maxTransferAmount: 0n, // 0 = no per-transfer cap
      },
    },
  ],
});

await sepoliaPublic.waitForTransactionReceipt({ hash: sepoliaDeployHash });

const sepoliaTokenAddress = await sepoliaPublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "resolveTokenAddress",
  args: [tokenId],
});

console.log("Deployed on Ethereum Sepolia:", sepoliaDeployHash);
console.log("CrossChainToken address:", sepoliaTokenAddress);

The CrossChainTokenIdClaimed event emits tokenAddress as address(0) for native deploys—this is expected behavior, not an error. Use resolveTokenAddress to read the real token address after the receipt confirms.

Step 4: Fetch a fee quote for the remote deploy

Before calling deployRemoteCrossChainToken, fetch a fee quote from Iris. The quote covers destination gas and Circle’s message delivery. Pass DeployTokenMessage as the message type so Iris prices a deploy operation rather than a transfer. If your deployment wallet has funds on Base Sepolia, you can instead call deployCrossChainToken directly on Base Sepolia with the same wallet, salt, and token metadata, then skip to step 7. This avoids the CCTP message entirely and is useful when you have funds available on each blockchain.

const quoteRes = await fetch(`${IRIS_BASE}/v2/quote/cctpx/${tokenId}/0/6`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    amount: "1",
    feeToken: zeroAddress,
    requests: [
      {
        type: "FORWARD",
        params: {
          msgType: "DeployTokenMessage",
          autoExecuteHookData: false,
        },
      },
    ],
  }),
});
if (!quoteRes.ok) throw new Error(await quoteRes.text());
const { signedQuote, feeTotalAmount } = await quoteRes.json();

const claim = {
  signedQuote,
  refundAddress: zeroAddress,
};

Step 5: Deploy to Base Sepolia

Call deployRemoteCrossChainToken on Ethereum Sepolia, targeting Base Sepolia (domain 6). Pass the same salt, token metadata, and DeploymentParams as in step 3—any mismatch produces a different tokenId on the destination.

const remoteDeployAbi = [
  {
    name: "deployRemoteCrossChainToken",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "salt", type: "bytes32" },
      { name: "destinationDomain", type: "uint32" },
      { name: "name", type: "string" },
      { name: "symbol", type: "string" },
      { name: "decimals", type: "uint8" },
      {
        name: "params",
        type: "tuple",
        components: [
          { name: "tokenManagerType", type: "uint8" },
          { name: "tokenManagerOwner", type: "bytes" },
          { name: "tokenManagerOperator", type: "bytes" },
          { name: "tokenOwner", type: "bytes" },
          { name: "tokenMinter", type: "bytes" },
          // WARNING: may be absent in the sandbox ABI — verify before submitting
          { name: "initialSupply", type: "uint256" },
          {
            name: "tokenManagerSettings",
            type: "tuple",
            components: [
              { name: "rateLimit", type: "uint256" },
              { name: "maxTransferAmount", type: "uint256" },
            ],
          },
        ],
      },
      {
        name: "signedFeeQuote",
        type: "tuple",
        components: [
          { name: "signedQuote", type: "bytes" },
          { name: "refundAddress", type: "address" },
        ],
      },
    ],
    outputs: [],
  },
] as const;

const remoteDeployHash = await sepoliaWallet.writeContract({
  address: CCTS_ADDRESS,
  abi: remoteDeployAbi,
  functionName: "deployRemoteCrossChainToken",
  args: [
    salt,
    6, // Base Sepolia domain
    TOKEN_NAME,
    TOKEN_SYMBOL,
    TOKEN_DECIMALS,
    {
      tokenManagerType: 0, // NATIVE_CROSSCHAIN_TOKEN
      tokenManagerOwner: ownerBytes,
      tokenManagerOperator: operatorBytes,
      tokenOwner: ownerBytes,
      tokenMinter: ownerBytes,
      initialSupply: 0n,
      tokenManagerSettings: {
        rateLimit: 0n,
        maxTransferAmount: 0n,
      },
    },
    claim,
  ],
  value: BigInt(feeTotalAmount),
});

await sepoliaPublic.waitForTransactionReceipt({ hash: remoteDeployHash });
console.log("Remote deploy message sent:", remoteDeployHash);

Step 6: Confirm delivery on Base Sepolia

Poll resolveTokenAddress on the Base Sepolia service until it returns a non-zero address. Circle typically delivers the message in a few minutes after the Ethereum Sepolia transaction confirms.

const zeroAddr = "0x0000000000000000000000000000000000000000" as `0x${string}`;
let baseTokenAddress: `0x${string}` = zeroAddr;

while (baseTokenAddress === zeroAddr) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  baseTokenAddress = await basePublic.readContract({
    address: CCTS_ADDRESS,
    abi: serviceAbi,
    functionName: "resolveTokenAddress",
    args: [tokenId],
  });
}

console.log("CrossChainToken deployed on Base Sepolia:", baseTokenAddress);

Step 7: Set rate limits

Every TokenManager deploys with rateLimit = 0, which blocks all transfers. Call setRateLimit on each TokenManager with a non-zero value. Only the operator can call setRateLimit—if you encoded your address as the operator in DeploymentParams, you can call it directly.

const tokenManagerAbi = [
  {
    name: "setRateLimit",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [{ name: "rateLimit", type: "uint256" }],
    outputs: [],
  },
] as const;

const sepoliaTokenManager = await sepoliaPublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "resolveTokenManager",
  args: [tokenId],
});

const baseTokenManager = await basePublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "resolveTokenManager",
  args: [tokenId],
});

// Replace with an appropriate limit for your token and expected transfer volume.
// This example sets a limit of 1 million tokens assuming 6 decimal places.
const rateLimit = 1_000_000n * 10n ** 6n;

const sepoliaRateLimitHash = await sepoliaWallet.writeContract({
  address: sepoliaTokenManager,
  abi: tokenManagerAbi,
  functionName: "setRateLimit",
  args: [rateLimit],
});
await sepoliaPublic.waitForTransactionReceipt({ hash: sepoliaRateLimitHash });

const baseRateLimitHash = await baseWallet.writeContract({
  address: baseTokenManager,
  abi: tokenManagerAbi,
  functionName: "setRateLimit",
  args: [rateLimit],
});
await basePublic.waitForTransactionReceipt({ hash: baseRateLimitHash });

console.log("Rate limits set on both blockchains");

Step 8: Verify

Call resolveTokenAddress and resolveTokenManager on both blockchains to confirm the tokenId resolves correctly.

const sepoliaResolved = await sepoliaPublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "resolveTokenAddress",
  args: [tokenId],
});

const baseResolved = await basePublic.readContract({
  address: CCTS_ADDRESS,
  abi: serviceAbi,
  functionName: "resolveTokenAddress",
  args: [tokenId],
});

console.log("Sepolia CrossChainToken:", sepoliaResolved);
console.log("Base Sepolia CrossChainToken:", baseResolved);
console.log("Sepolia TokenManager:", sepoliaTokenManager);
console.log("Base Sepolia TokenManager:", baseTokenManager);

Your token is now deployed on both blockchains and ready for crosschain transfers. Before enabling fast transfers, note that fast transfers require additional Circle coordination—FX pricing and backend indexing must be configured by Circle before fast transfers work for newly deployed tokens. Once the token is deployed and rate limits are set, transferring it follows the same pattern as Transfer EURC from Ethereum to Arc—swap in your new tokenId.

CCTP for USDC

CCTP for non-USDC

Gateway

Deploy a native crosschain token

Prerequisites

Step 1: Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2: Configure clients and define token metadata

Step 3: Deploy on Ethereum Sepolia

Step 4: Fetch a fee quote for the remote deploy

Step 5: Deploy to Base Sepolia

Step 6: Confirm delivery on Base Sepolia

Step 7: Set rate limits

Step 8: Verify

​Prerequisites

​Step 1: Set up the project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​1.3. Set environment variables

​Step 2: Configure clients and define token metadata

​Step 3: Deploy on Ethereum Sepolia

​Step 4: Fetch a fee quote for the remote deploy

​Step 5: Deploy to Base Sepolia

​Step 6: Confirm delivery on Base Sepolia

​Step 7: Set rate limits

​Step 8: Verify

Prerequisites

Step 1: Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2: Configure clients and define token metadata

Step 3: Deploy on Ethereum Sepolia

Step 4: Fetch a fee quote for the remote deploy

Step 5: Deploy to Base Sepolia

Step 6: Confirm delivery on Base Sepolia

Step 7: Set rate limits

Step 8: Verify