How-to: Manage delegates for Gateway transfers

Gateway lets you delegate your deposit so that another account can authorize transfers on your behalf. Adding a delegate grants that account a full allowance to sign burn intents for your deposited USDC, which is useful when you want a separate account to initiate transfers, or when you’d rather sign with a different account than the one that holds the deposit. A delegate can be any account whose signatures Gateway accepts, such as an Externally Owned Account (EOA) or a smart contract using ERC-1271.

A smart contract account (SCA) can also authorize transfers directly through ERC-1271, without adding a delegate at all. See How-to: Transfer USDC from a smart contract account.

This guide demonstrates how to add and remove delegates for Gateway transfers using Circle developer-controlled wallets.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22.6+
Created a Circle Console account
Obtained an API key and registered your Entity Secret
Created two wallets via Circle developer-controlled wallets:
- The depositor wallet holds your Gateway USDC deposits
- The delegate wallet will sign burn intents on behalf of the depositor
Deposited USDC into the Gateway Wallet from your depositor wallet
Created a TypeScript project with the Developer-Controlled Wallets SDK installed

Set up a .env file with the following variables:

.env

CIRCLE_API_KEY={YOUR_API_KEY}
CIRCLE_ENTITY_SECRET={YOUR_ENTITY_SECRET}
DEPOSITOR_ADDRESS={YOUR_DEPOSITOR_WALLET_ADDRESS}
DELEGATE_WALLET_ADDRESS={YOUR_DELEGATE_WALLET_ADDRESS}

Add a delegate

Follow these steps to authorize a delegate to sign burn intents on behalf of your depositor wallet.

Step 1. Create the add delegate script

Create a new file called add-delegate.ts in the root of your project and add the following code. This calls the addDelegate() method on the Gateway Wallet contract on Arc Testnet.

add-delegate.ts

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
const USDC_ADDRESS = "0x3600000000000000000000000000000000000000"; // Arc Testnet
const BLOCKCHAIN = "ARC-TESTNET";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

async function waitForTx(txId: string) {
  while (true) {
    const { data } = await client.getTransaction({ id: txId });
    const state = data?.transaction?.state;
    if (["COMPLETE", "CONFIRMED"].includes(state!)) return;
    if (["FAILED", "DENIED", "CANCELLED"].includes(state!))
      throw new Error(`Failed: ${state}`);
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

async function main() {
  console.log(`\n=== Processing ${BLOCKCHAIN} ===`);
  console.log(`Adding delegate: ${process.env.DELEGATE_WALLET_ADDRESS}`);

  const tx = await client.createContractExecutionTransaction({
    walletAddress: process.env.DEPOSITOR_ADDRESS!,
    blockchain: BLOCKCHAIN,
    contractAddress: GATEWAY_WALLET,
    abiFunctionSignature: "addDelegate(address,address)",
    abiParameters: [USDC_ADDRESS, process.env.DELEGATE_WALLET_ADDRESS!],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  await waitForTx(tx.data?.id!);
  console.log(`Done on ${BLOCKCHAIN}`);
}

main().catch((error) => {
  console.error("\nError:", error);
  process.exit(1);
});

Step 2. Run the script

Run the script with the following command:

node --env-file=.env add-delegate.ts

The script output shows “Done on <SELECTED_BLOCKCHAIN>” when the delegate is successfully authorized. You can now use the delegate to sign burn intents on behalf of your depositor wallet when making Gateway transfers.

Step 3. Repeat for other blockchains

To add the delegate on additional blockchains where the depositor holds Gateway deposits, repeat Steps 1-2 with different BLOCKCHAIN and USDC_ADDRESS values for your target blockchains. Check the USDC contract addresses for the correct values.

The delegate authorization remains valid until explicitly removed with the removeDelegate() method.

Remove a delegate

Follow these steps to revoke a delegate’s authorization to sign burn intents on behalf of your depositor wallet. After removing a delegate, note that:

The delegate can no longer create new burn intents for the depositor wallet
Burn intents that were already signed by the delegate remain valid and can still be executed onchain
This ensures that burns may be executed safely even in the event of a revocation
The Gateway API reflects revocations once they are finalized onchain

This behavior is by design to prevent race conditions where a valid burn intent becomes unusable mid-flight.

Step 1. Create the remove delegate script

Create a new file called remove-delegate.ts in the root of your project and add the following code. This is nearly identical to the add delegate script, but calls removeDelegate() instead.

remove-delegate.ts

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const GATEWAY_WALLET = "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
const USDC_ADDRESS = "0x3600000000000000000000000000000000000000"; // Arc Testnet
const BLOCKCHAIN = "ARC-TESTNET";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

async function waitForTx(txId: string) {
  while (true) {
    const { data } = await client.getTransaction({ id: txId });
    const state = data?.transaction?.state;
    if (["COMPLETE", "CONFIRMED"].includes(state!)) return;
    if (["FAILED", "DENIED", "CANCELLED"].includes(state!))
      throw new Error(`Failed: ${state}`);
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

async function main() {
  console.log(`\n=== Processing ${BLOCKCHAIN} ===`);
  console.log(`Removing delegate: ${process.env.DELEGATE_WALLET_ADDRESS}`);

  const tx = await client.createContractExecutionTransaction({
    walletAddress: process.env.DEPOSITOR_ADDRESS!,
    blockchain: BLOCKCHAIN,
    contractAddress: GATEWAY_WALLET,
    abiFunctionSignature: "removeDelegate(address,address)",
    abiParameters: [USDC_ADDRESS, process.env.DELEGATE_WALLET_ADDRESS!],
    fee: { type: "level", config: { feeLevel: "MEDIUM" } },
  });

  await waitForTx(tx.data?.id!);
  console.log(`Done on ${BLOCKCHAIN}`);
}

main().catch((error) => {
  console.error("\nError:", error);
  process.exit(1);
});

Step 2. Run the script

Run the script with the following command:

node --env-file=.env remove-delegate.ts

​Prerequisites

​Add a delegate

​Step 1. Create the add delegate script

​Step 2. Run the script

​Step 3. Repeat for other blockchains

​Remove a delegate

​Step 1. Create the remove delegate script

​Step 2. Run the script

Prerequisites

Add a delegate

Step 1. Create the add delegate script

Step 2. Run the script

Step 3. Repeat for other blockchains

Remove a delegate

Step 1. Create the remove delegate script

Step 2. Run the script