How-to: Transfer USDC with upfront fees

This example transfers 10 USDC from Base Sepolia to Arc Testnet, paying both the Fast Transfer and Forwarding Service fees upfront so the recipient receives the full transfer amount on the destination blockchain. You can use the same steps for any EVM source blockchain where both upfront fees and Fast Transfer are available, and any destination blockchain that the Forwarding Service supports.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22+
Created a TypeScript project and installed the viem package
Created a wallet with the private key accessible from your local development environment
Funded the wallet on Base Sepolia with:
- Base Sepolia ETH for gas from a public faucet
- Base Sepolia USDC from the Circle Faucet
Created a .env file with your private key

Keep your private key secret. Store it in a .env file that’s listed in .gitignore, and never commit it or expose it in logs or shell history.

Steps

Step 1: Request a signed quote from the Quote API

Request a quote from the Quote API for the fees you want to pay upfront. This example requests both FORWARD (Forwarding Service) and PRE_FINALITY (Fast Transfer) fees, and sets feeToken to the source blockchain’s USDC address to pay the fee in USDC. The following request uses source domain 6 (Base Sepolia) and destination domain 26 (Arc Testnet). The USDC address and decimals come from the token definition in viem/tokens, so you don’t hardcode either one:

import { parseUnits } from "viem";
import { baseSepolia } from "viem/chains";
import { usdc } from "viem/tokens";

// USDC on the source blockchain, including its address and decimals
const sourceUsdc = usdc(baseSepolia.id);

// The quote binds to this amount, so reuse it for the onchain burn
const transferAmount = parseUnits("10", sourceUsdc.decimals);

const response = await fetch(
  "https://iris-api-sandbox.circle.com/v2/quote/burn/usdc/6/26",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: transferAmount.toString(), // minor units
      feeToken: sourceUsdc.address, // omit to pay the fee in the native gas token
      requests: [
        { type: "FORWARD" },
        // Omit if the source blockchain doesn't support Fast Transfer
        { type: "PRE_FINALITY" },
      ],
    }),
  },
);

const quote = await response.json();
console.log("Quote:", JSON.stringify(quote, null, 2));

Example response:

{
  "signedQuote": "0x0100000000000000000000000000000000000000000000000000000000000000...c9afdd35731b00",
  "issuedAt": 1783407750,
  "expiry": {
    "mode": "BLOCK_NUMBER",
    "expiresAtBlock": 43819792,
    "blockEstimatedAt": 1783407872
  },
  "feeTotalAmount": "24453",
  "feeToken": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "items": [
    {
      "type": "FORWARD",
      "amount": "23153",
      "args": ["..."],
      "argsHash": "0x6cea1d25ab9b4b9edfc5c788082c28c6669c6fc2f35fa8e047c7774e60c66d4c"
    },
    {
      "type": "PRE_FINALITY",
      "amount": "1300",
      "args": ["..."],
      "argsHash": "0x5743df2ad8e9696c8a5e70bfced256f3160e68d49ce305f8c7fcd0c90b035496"
    }
  ],
  "nonce": "0",
  "metadata": {
    "exchangeRates": {
      "feeTokenUsd": "1.000000",
      "destinationTokenUsd": "1.000000"
    }
  }
}

The signedQuote is the blob you submit onchain (truncated here for brevity). The feeTotalAmount is the total fee in feeToken minor units, and items breaks it down per fee type. This quote uses BLOCK_NUMBER expiry, so it stays valid until expiresAtBlock on the source blockchain.

Quotes expire after a short, per-blockchain window (see Quote expiry). Request the quote immediately before you submit the transfer, and submit before it expires.

Step 2: Calculate the approval amount

To pay the fee in USDC, approve the TokenMessengerWithFees contract to spend both the transfer amount and the quoted fee. The contract pulls the transfer amount for the burn and the fee for collection.

import { formatUnits } from "viem";

// Total fee from the quote response
const feeAmount = BigInt(quote.feeTotalAmount);

// Approve the transfer amount (from Step 1) plus the fee
const approvalAmount = transferAmount + feeAmount;

const { decimals, symbol } = sourceUsdc;
console.log("Transfer:", formatUnits(transferAmount, decimals), symbol);
console.log("Fee:", formatUnits(feeAmount, decimals), symbol);
console.log("Approval:", formatUnits(approvalAmount, decimals), symbol);

Because you pay the fee upfront, the recipient receives the full transferAmount on Arc Testnet. The fee is charged separately from the amount minted.

Step 3: Approve the USDC transfer

Grant approval for the TokenMessengerWithFees contract on Base Sepolia to spend USDC from your wallet. Approve at least the approvalAmount calculated in Step 2. Registering the usdc token on the wallet client gives you the client.token.approve action, so you don’t have to supply the ERC-20 ABI yourself:

import { createPublicClient, createWalletClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { usdc } from "viem/tokens";

// Configuration
// TokenMessengerWithFees has this same address on every supported testnet
// blockchain, including Base Sepolia.
const TESTNET_TOKEN_MESSENGER_WITH_FEES =
  "0x8745D906D67C346E5eb1aEEED38Eb87F34DF0C0A";

// Set up wallet and public clients
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  chain: baseSepolia,
  tokens: [usdc],
  transport: http(),
  account,
});
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

async function approveUSDC(amount: bigint) {
  console.log("Approving USDC...");
  const approveTx = await client.token.approve({
    amount,
    spender: TESTNET_TOKEN_MESSENGER_WITH_FEES,
    token: "usdc",
  });
  console.log("USDC Approval Tx:", approveTx);

  // Wait for the approval to be mined before you submit the burn
  await publicClient.waitForTransactionReceipt({ hash: approveTx });
  return approveTx;
}

// Approve the transfer amount plus the fee (from Step 2)
await approveUSDC(approvalAmount);

sendTransaction resolves once the node accepts the transaction, not once it’s mined. Without the wait, a burn submitted immediately after the approval can revert because the allowance isn’t set yet.

Step 4: Sign and broadcast a `depositForBurnWithFees` transaction

Call depositForBurnWithFees on the TokenMessengerWithFees contract, passing a QuoteClaim that bundles the signedQuote with your refundAddress. The contract infers Fast Transfer from the PRE_FINALITY fee and adds the default cctp-forward hook because the quote includes a FORWARD fee, so you don’t pass maxFee, minFinalityThreshold, or hook data. This example uses the QuoteClaim overload, which takes the opaque signedQuote bytes directly. The contract also exposes a DecodedQuoteClaim overload for advanced cases where you decode the quote in your own code; see the full ABI in Contract interfaces.

Use transferAmount (not the amount plus fee) for the amount parameter. The fee is collected separately, and the recipient receives the full transferAmount.

import { pad, encodeFunctionData } from "viem";

// Configuration
const ARC_TESTNET_DOMAIN = 26;

// This example mints back to your own wallet. Set this to any address you want
// to receive the USDC on the destination blockchain.
const DESTINATION_ADDRESS = account.address;

// Convert the recipient address to bytes32
const mintRecipientBytes32 = pad(DESTINATION_ADDRESS, { size: 32 });

// Use your own address to attribute any future fee refund to
const refundAddress = account.address;

async function depositForBurnWithFees() {
  console.log("Burning USDC on Base Sepolia with upfront fees...");

  const burnTx = await client.sendTransaction({
    to: TESTNET_TOKEN_MESSENGER_WITH_FEES,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "depositForBurnWithFees",
          stateMutability: "payable",
          inputs: [
            { name: "amount", type: "uint256" },
            { name: "destinationDomain", type: "uint32" },
            { name: "mintRecipient", type: "bytes32" },
            { name: "burnToken", type: "address" },
            { name: "destinationCaller", type: "bytes32" },
            {
              name: "claim",
              type: "tuple",
              components: [
                { name: "signedQuote", type: "bytes" },
                { name: "refundAddress", type: "address" },
              ],
            },
          ],
          outputs: [],
        },
      ],
      functionName: "depositForBurnWithFees",
      args: [
        transferAmount,
        ARC_TESTNET_DOMAIN,
        mintRecipientBytes32,
        sourceUsdc.address,
        pad("0x", { size: 32 }), // destinationCaller (empty = any caller)
        { signedQuote: quote.signedQuote, refundAddress },
      ],
    }),
  });
  console.log("Burn Tx:", burnTx);

  // Wait for the burn to be mined before you poll for the attestation
  await publicClient.waitForTransactionReceipt({ hash: burnTx });
  return burnTx;
}

const burnTx = await depositForBurnWithFees();

Pay the fee in the native gas token

To pay the fee in the source blockchain’s native gas token instead of USDC, omit feeToken from the quote request in Step 1. Then approve only the transferAmount in Step 3, and attach the quoted fee as the transaction’s native value in Step 4:

const burnTx = await client.sendTransaction({
  to: TESTNET_TOKEN_MESSENGER_WITH_FEES,
  value: feeAmount, // pay the quoted fee in native currency
  data: encodeFunctionData({
    // ...same abi and args as above
  }),
});

Because the quote binds to your call arguments, a mismatch reverts onchain and costs you gas. Request the quote with the same amount, destination domain, and burn token you submit onchain so the values match. Once the burn transaction is confirmed on Base Sepolia, Circle attests the burn and the Forwarding Service mints USDC on Arc Testnet. Because the fee is paid upfront, the recipient receives the full transferAmount.

Step 5: Verify the mint transaction

After the burn is confirmed, query the Circle Iris API to retrieve the forwarding details. The API returns the forwardTxHash, which is the mint transaction hash on the destination blockchain. The attestation may take time to become available, so poll the API until the message is ready:

// Configuration
const BASE_SEPOLIA_DOMAIN = 6;

process.stdout.write("Waiting for attestation...");

let mintTx;
while (!mintTx) {
  const messageResponse = await fetch(
    `https://iris-api-sandbox.circle.com/v2/messages/${BASE_SEPOLIA_DOMAIN}?transactionHash=${burnTx}`,
  );
  const data = await messageResponse.json();

  if (data.messages?.[0]?.forwardTxHash) {
    mintTx = data.messages[0].forwardTxHash;
    console.log(); // New line after dots
  } else {
    process.stdout.write(".");
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

console.log("Mint Tx:", mintTx);

Full example code

The following is a complete example of how to transfer USDC from Base Sepolia to Arc Testnet with upfront fees. Remember to set the PRIVATE_KEY environment variable.

script.ts

import {
  createPublicClient,
  createWalletClient,
  http,
  encodeFunctionData,
  formatUnits,
  pad,
  parseUnits,
} from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { usdc } from "viem/tokens";

// Validate environment variables
if (!process.env.PRIVATE_KEY) {
  throw new Error("PRIVATE_KEY environment variable is required");
}

// Configuration
const sourceUsdc = usdc(baseSepolia.id);
// TokenMessengerWithFees has this same address on every supported testnet
// blockchain, including Base Sepolia. Mainnet uses a different shared address.
// See: https://developers.circle.com/cctp/references/contract-addresses#tokenmessengerwithfees-testnet
const TESTNET_TOKEN_MESSENGER_WITH_FEES =
  "0x8745D906D67C346E5eb1aEEED38Eb87F34DF0C0A";
const BASE_SEPOLIA_DOMAIN = 6;
const ARC_TESTNET_DOMAIN = 26;

// The quote binds to this amount, so the same value is used for the burn
const transferAmount = parseUnits("10", sourceUsdc.decimals);

// Set up wallet and public clients
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  chain: baseSepolia,
  tokens: [usdc],
  transport: http(),
  account,
});
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

// This example mints back to your own wallet. Set this to any address you want
// to receive the USDC on the destination blockchain.
const DESTINATION_ADDRESS = account.address;

async function main() {
  console.log("Wallet address:", account.address);
  console.log("Destination address:", DESTINATION_ADDRESS);

  // Step 1: Request a signed quote
  console.log("\nStep 1: Requesting a signed quote...");
  const quoteResponse = await fetch(
    `https://iris-api-sandbox.circle.com/v2/quote/burn/usdc/${BASE_SEPOLIA_DOMAIN}/${ARC_TESTNET_DOMAIN}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        amount: transferAmount.toString(), // minor units
        feeToken: sourceUsdc.address, // pay the fee in USDC
        requests: [
          { type: "FORWARD" },
          // Omit if the source blockchain doesn't support Fast Transfer
          { type: "PRE_FINALITY" },
        ],
      }),
    },
  );
  const quote = await quoteResponse.json();
  console.log("Quote:", JSON.stringify(quote, null, 2));

  // Step 2: Calculate amounts
  console.log("\nStep 2: Calculating amounts...");
  const feeAmount = BigInt(quote.feeTotalAmount);
  const approvalAmount = transferAmount + feeAmount;

  const { decimals, symbol } = sourceUsdc;
  console.log("Transfer:", formatUnits(transferAmount, decimals), symbol);
  console.log("Fee:", formatUnits(feeAmount, decimals), symbol);
  console.log("Approval:", formatUnits(approvalAmount, decimals), symbol);

  // Step 3: Approve USDC (transfer amount + fee)
  console.log("\nStep 3: Approving USDC...");
  const approveTx = await client.token.approve({
    amount: approvalAmount,
    spender: TESTNET_TOKEN_MESSENGER_WITH_FEES,
    token: "usdc",
  });
  console.log("Approval Tx:", approveTx);

  // Wait for the approval to be mined so the burn doesn't revert
  await publicClient.waitForTransactionReceipt({ hash: approveTx });

  // Step 4: Burn USDC with upfront fees
  console.log("\nStep 4: Burning USDC with upfront fees...");
  const burnTx = await client.sendTransaction({
    to: TESTNET_TOKEN_MESSENGER_WITH_FEES,
    data: encodeFunctionData({
      abi: [
        {
          type: "function",
          name: "depositForBurnWithFees",
          stateMutability: "payable",
          inputs: [
            { name: "amount", type: "uint256" },
            { name: "destinationDomain", type: "uint32" },
            { name: "mintRecipient", type: "bytes32" },
            { name: "burnToken", type: "address" },
            { name: "destinationCaller", type: "bytes32" },
            {
              name: "claim",
              type: "tuple",
              components: [
                { name: "signedQuote", type: "bytes" },
                { name: "refundAddress", type: "address" },
              ],
            },
          ],
          outputs: [],
        },
      ],
      functionName: "depositForBurnWithFees",
      args: [
        transferAmount,
        ARC_TESTNET_DOMAIN,
        pad(DESTINATION_ADDRESS, { size: 32 }),
        sourceUsdc.address,
        pad("0x", { size: 32 }), // destinationCaller (empty = any caller)
        { signedQuote: quote.signedQuote, refundAddress: account.address },
      ],
    }),
  });
  console.log("Burn Tx:", burnTx);

  // Wait for the burn to be mined before polling for the attestation
  await publicClient.waitForTransactionReceipt({ hash: burnTx });

  console.log(
    "\nTransfer initiated. The Forwarding Service will mint the full amount on Arc Testnet.",
  );

  // Step 5: Verify the mint transaction
  console.log("\nStep 5: Verifying mint transaction...");
  process.stdout.write("Waiting for attestation...");

  let mintTx;
  while (!mintTx) {
    const messageResponse = await fetch(
      `https://iris-api-sandbox.circle.com/v2/messages/${BASE_SEPOLIA_DOMAIN}?transactionHash=${burnTx}`,
    );
    const data = await messageResponse.json();

    if (data.messages?.[0]?.forwardTxHash) {
      mintTx = data.messages[0].forwardTxHash;
      console.log(); // New line after dots
    } else {
      process.stdout.write(".");
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }

  console.log("Mint Tx:", mintTx);
}

main().catch(console.error);

Run the script:

npx tsx script.ts

Pay fees upfront with a custom hook

The preceding steps use depositForBurnWithFees, which builds the default cctp-forward hook for you. To attach your own hook data on the destination blockchain, alongside forwarding, use depositForBurnWithHookAndFees and provide the hook data explicitly.

The quote binds to your call parameters, including the hook data. Request the quote with the same hook data you submit onchain. A quote requested with custom hook data is rejected by depositForBurnWithFees (which applies the default hook), and a quote requested without custom hook data is rejected by depositForBurnWithHookAndFees. Always pair the entry point with a matching quote.

Build the hook data

Hook data is a sequence of hooks, each with a fixed 32-byte header followed by its payload:

Bytes	Type	Data
0-23	`bytes24`	Hook name (magic)
24-27	`uint32`	Version
28-31	`uint32`	Payload length in bytes (`n`)
32+	`bytes`	Payload (`n` bytes)

The first hook must be the cctp-forward hook so that forwarding runs. You append your own hook as another complete, correctly framed entry: appending raw, unframed bytes causes the destination to reject the hook data. For the cctp-forward layout, see Forwarding Service hook format.

import { concat, stringToHex, toHex } from "viem";

// cctp-forward hook, framed with the shared 32-byte header
const forwardHook = concat([
  stringToHex("cctp-forward", { size: 24 }), // hook name
  toHex(1, { size: 4 }), // version
  toHex(0, { size: 4 }), // payload length (no payload)
]);

// A placeholder custom hook, framed the same way. The destination ignores it
// unless it recognizes the hook name; replace it with a hook your destination
// logic supports.
const customPayload = "0xdeadbeef";
const customHook = concat([
  stringToHex("my-custom-hook", { size: 24 }), // hook name
  toHex(1, { size: 4 }), // version
  toHex(4, { size: 4 }), // payload length (4 bytes)
  customPayload,
]);

const hookData = concat([forwardHook, customHook]);
console.log("Hook data:", hookData);

Request a matching quote

Include the same hookData in the FORWARD request’s params so the quote binds to it:

const quoteResponse = await fetch(
  "https://iris-api-sandbox.circle.com/v2/quote/burn/usdc/6/26",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: transferAmount.toString(),
      feeToken: sourceUsdc.address,
      requests: [
        { type: "FORWARD", params: { hookData } },
        { type: "PRE_FINALITY" },
      ],
    }),
  },
);
const quote = await quoteResponse.json();
console.log("Quote:", JSON.stringify(quote, null, 2));

Submit the transfer with `depositForBurnWithHookAndFees`

Pass the same hookData as a parameter, along with the QuoteClaim:

import { pad, encodeFunctionData } from "viem";

const burnTx = await client.sendTransaction({
  to: TESTNET_TOKEN_MESSENGER_WITH_FEES,
  data: encodeFunctionData({
    abi: [
      {
        type: "function",
        name: "depositForBurnWithHookAndFees",
        stateMutability: "payable",
        inputs: [
          { name: "amount", type: "uint256" },
          { name: "destinationDomain", type: "uint32" },
          { name: "mintRecipient", type: "bytes32" },
          { name: "burnToken", type: "address" },
          { name: "destinationCaller", type: "bytes32" },
          { name: "hookData", type: "bytes" },
          {
            name: "claim",
            type: "tuple",
            components: [
              { name: "signedQuote", type: "bytes" },
              { name: "refundAddress", type: "address" },
            ],
          },
        ],
        outputs: [],
      },
    ],
    functionName: "depositForBurnWithHookAndFees",
    args: [
      transferAmount,
      ARC_TESTNET_DOMAIN,
      pad(DESTINATION_ADDRESS, { size: 32 }),
      sourceUsdc.address,
      pad("0x", { size: 32 }), // destinationCaller (empty = any caller)
      hookData,
      { signedQuote: quote.signedQuote, refundAddress: account.address },
    ],
  }),
});
console.log("Burn Tx:", burnTx);

Approve USDC and verify the mint the same way as Step 3 and Step 5.

CCTP

Gateway

How-to: Transfer USDC with upfront fees

Prerequisites

Steps

Step 1: Request a signed quote from the Quote API

Step 2: Calculate the approval amount

Step 3: Approve the USDC transfer

Step 4: Sign and broadcast a `depositForBurnWithFees` transaction

Step 5: Verify the mint transaction

Full example code

Pay fees upfront with a custom hook

Build the hook data

Request a matching quote

Submit the transfer with `depositForBurnWithHookAndFees`

​Prerequisites

​Steps

​Step 1: Request a signed quote from the Quote API

​Step 2: Calculate the approval amount

​Step 3: Approve the USDC transfer

​Step 4: Sign and broadcast a depositForBurnWithFees transaction

​Step 5: Verify the mint transaction

​Full example code

​Pay fees upfront with a custom hook

​Build the hook data

​Request a matching quote

​Submit the transfer with depositForBurnWithHookAndFees

Prerequisites

Steps

Step 1: Request a signed quote from the Quote API

Step 2: Calculate the approval amount

Step 3: Approve the USDC transfer

Step 4: Sign and broadcast a `depositForBurnWithFees` transaction

Step 5: Verify the mint transaction

Full example code

Pay fees upfront with a custom hook

Build the hook data

Request a matching quote

Submit the transfer with `depositForBurnWithHookAndFees`