Skip to main content
This guide walks you through the process of creating Unified Crosschain USDC Balances on Solana using Circle Gateway, and performing transfers from EVM to Solana and from Solana to Solana.
Use Unified Balance Kit to simplify this integration.This quickstart uses a manual Gateway integration. It is for learning or for developers who need direct control.To simplify, use Unified Balance Kit to deposit and spend USDC in just a few lines of code.
Select a tab below for the Circle Wallets or self-managed wallet path.

​
Prerequisites

Before you begin, ensure that you’ve:If you want to try the EVM to Solana transfer, ensure that you’ve:
  • Created an Arc Testnet EVM Developer-Controlled Wallet
  • Created a Solana Devnet Developer-Controlled Wallet to receive the minted USDC
  • Completed the deposit flow from the EVM quickstart first

​
Add testnet funds to your wallet

To interact with Gateway, you need test USDC and native tokens in your wallet on each chain you deposit from. For direct mints on Solana, the wallet that submits the Solana transaction also needs SOL to create the recipient Associated Token Account and call the Gateway Minter program.
You can skip the destination mint transaction by using the Forwarding Service, which completes the Solana mint for you. The recipient ATA still needs to exist for this quickstart.
Use the Circle Faucet to get test USDC. If you have a Circle Developer Console account, you can use the Console Faucet to get testnet native tokens. In addition, the following faucets can also be used to fund your wallet with testnet native tokens:
Faucet: Arc Testnet (USDC + native tokens)
PropertyValue
Chain namearcTestnet
USDC address0x3600000000000000000000000000000000000000
Domain ID26

​
Step 1. Set up your project

​
1.1. Create the project and install dependencies

# Set up your directory and initialize a Node.js project
mkdir unified-gateway-balance-solana-circle-wallets
cd unified-gateway-balance-solana-circle-wallets
npm init -y

# Set up module type and run scripts
npm pkg set type=module
npm pkg set scripts.deposit="tsx --env-file=.env deposit.ts"
npm pkg set scripts.balances="tsx --env-file=.env balances.ts"
npm pkg set scripts.transfer-from-sol="tsx --env-file=.env transfer-from-sol.ts"
npm pkg set scripts.transfer-from-evm="tsx --env-file=.env transfer-from-evm.ts"

# Pin bigint-buffer to a patched version
npm pkg set overrides.bigint-buffer=npm:@trufflesuite/bigint-buffer@1.1.10

# Install runtime dependencies
npm install @circle-fin/developer-controlled-wallets @coral-xyz/anchor @solana/buffer-layout @solana/spl-token @solana/web3.js bs58 bn.js tsx typescript

# Install dev dependencies
npm install --save-dev @types/node @types/bn.js

​
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

Create a .env file in the project directory:
.env
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
DEPOSITOR_ADDRESS=YOUR_SOURCE_WALLET_ADDRESS
RECIPIENT_ADDRESS=YOUR_DESTINATION_WALLET_ADDRESS
  • CIRCLE_API_KEY is your Circle API key.
  • CIRCLE_ENTITY_SECRET is your Circle entity secret.
  • DEPOSITOR_ADDRESS is the source depositor wallet for the script you are running.
  • RECIPIENT_ADDRESS is the destination wallet that receives the minted USDC.
For transfer-from-sol.ts, both values are Solana addresses.For transfer-from-evm.ts, DEPOSITOR_ADDRESS is an EVM address and RECIPIENT_ADDRESS is a Solana address.
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.

​
Step 2. Set up the configuration file

The shared Solana configuration and helpers are used by the deposit and transfer scripts.

​
2.1. Create the configuration file

touch config.ts

​
2.2. Configure Solana settings and Gateway helpers

Add the shared Solana RPC configuration, Gateway addresses, IDLs, attestation decoding helpers, and Circle Wallets signing helpers to config.ts.The local IDL fragments in this example are only the subset needed by the sample code. For canonical static instruction and account definitions, use the onchain IDLs linked from Solana Programs and Interfaces.
config.ts
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
import { Connection, PublicKey, Transaction } from "@solana/web3.js";
import {
  u32be,
  nu64be,
  struct,
  seq,
  blob,
  offset,
  Layout,
} from "@solana/buffer-layout";
import bs58 from "bs58";

export const RPC_ENDPOINT = "https://api.devnet.solana.com";
export const SOLANA_DOMAIN = 5;
export const SOLANA_ZERO_ADDRESS = "11111111111111111111111111111111";

export const GATEWAY_WALLET_ADDRESS =
  "GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu";
export const GATEWAY_MINTER_ADDRESS =
  "GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr";
export const USDC_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";

const API_KEY = process.env.CIRCLE_API_KEY!;
const ENTITY_SECRET = process.env.CIRCLE_ENTITY_SECRET!;

if (!API_KEY || !ENTITY_SECRET) {
  console.error(
    "Missing required env vars: CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET",
  );
  process.exit(1);
}

export const client = initiateDeveloperControlledWalletsClient({
  apiKey: API_KEY,
  entitySecret: ENTITY_SECRET,
});

export class PublicKeyLayout extends Layout<PublicKey> {
  constructor(property: string) {
    super(32, property);
  }
  decode(b: Buffer, offset = 0): PublicKey {
    return new PublicKey(b.subarray(offset, offset + 32));
  }
  encode(src: PublicKey, b: Buffer, offset = 0): number {
    const pubkeyBuffer = src.toBuffer();
    pubkeyBuffer.copy(b, offset);
    return 32;
  }
}

export const publicKey = (property: string) => new PublicKeyLayout(property);

const MintAttestationElementLayout = struct([
  publicKey("destinationToken"),
  publicKey("destinationRecipient"),
  nu64be("value"),
  blob(32, "transferSpecHash"),
  u32be("hookDataLength"),
  blob(offset(u32be(), -4), "hookData"),
] as any);

const MintAttestationSetLayout = struct([
  u32be("magic"),
  u32be("version"),
  u32be("destinationDomain"),
  publicKey("destinationContract"),
  publicKey("destinationCaller"),
  nu64be("maxBlockHeight"),
  u32be("numAttestations"),
  seq(MintAttestationElementLayout, offset(u32be(), -4), "attestations"),
] as any);

// Sample-local IDL subset for this example.
export const gatewayWalletIdl = {
  address: GATEWAY_WALLET_ADDRESS,
  metadata: {
    name: "gatewayWallet",
    version: "0.1.0",
    spec: "0.1.0",
  },
  instructions: [
    {
      name: "deposit",
      discriminator: [22, 0],
      accounts: [
        { name: "payer", writable: true, signer: true },
        { name: "owner", signer: true },
        { name: "gatewayWallet" },
        { name: "ownerTokenAccount", writable: true },
        { name: "custodyTokenAccount", writable: true },
        { name: "deposit", writable: true },
        { name: "depositorDenylist" },
        { name: "tokenProgram" },
        { name: "systemProgram" },
        { name: "eventAuthority" },
        { name: "program" },
      ],
      args: [{ name: "amount", type: "u64" }],
    },
  ],
};

// Sample-local IDL subset for this example.
export const gatewayMinterIdl = {
  address: GATEWAY_MINTER_ADDRESS,
  metadata: { name: "gatewayMinter", version: "0.1.0", spec: "0.1.0" },
  instructions: [
    {
      name: "gatewayMint",
      discriminator: [12, 0],
      accounts: [
        { name: "payer", writable: true, signer: true },
        { name: "destinationCaller", signer: true },
        { name: "gatewayMinter" },
        { name: "systemProgram" },
        { name: "tokenProgram" },
        { name: "eventAuthority" },
        { name: "program" },
      ],
      args: [
        {
          name: "params",
          type: { defined: { name: "gatewayMintParams" } },
        },
      ],
    },
  ],
  types: [
    {
      name: "gatewayMintParams",
      type: {
        kind: "struct",
        fields: [
          { name: "attestation", type: "bytes" },
          { name: "signature", type: "bytes" },
        ],
      },
    },
  ],
};

export function findDepositPDAs(
  programId: PublicKey,
  usdcMint: PublicKey,
  owner: PublicKey,
) {
  return {
    wallet: PublicKey.findProgramAddressSync(
      [Buffer.from("gateway_wallet")],
      programId,
    )[0],
    custody: PublicKey.findProgramAddressSync(
      [Buffer.from("gateway_wallet_custody"), usdcMint.toBuffer()],
      programId,
    )[0],
    deposit: PublicKey.findProgramAddressSync(
      [Buffer.from("gateway_deposit"), usdcMint.toBuffer(), owner.toBuffer()],
      programId,
    )[0],
    denylist: PublicKey.findProgramAddressSync(
      [Buffer.from("denylist"), owner.toBuffer()],
      programId,
    )[0],
  };
}

export function findCustodyPda(
  mint: PublicKey,
  minterProgramId: PublicKey,
): PublicKey {
  return PublicKey.findProgramAddressSync(
    [Buffer.from("gateway_minter_custody"), mint.toBuffer()],
    minterProgramId,
  )[0];
}

export function findTransferSpecHashPda(
  transferSpecHash: Uint8Array | Buffer,
  minterProgramId: PublicKey,
): PublicKey {
  return PublicKey.findProgramAddressSync(
    [Buffer.from("used_transfer_spec_hash"), Buffer.from(transferSpecHash)],
    minterProgramId,
  )[0];
}

export function decodeAttestationSet(attestation: string) {
  const buffer = Buffer.from(attestation.slice(2), "hex");
  return MintAttestationSetLayout.decode(buffer) as {
    attestations: Array<{
      destinationToken: PublicKey;
      destinationRecipient: PublicKey;
      transferSpecHash: Uint8Array;
    }>;
  };
}

export function solanaAddressToBytes32(address: string): string {
  const decoded = Buffer.from(bs58.decode(address));
  return `0x${decoded.toString("hex")}`;
}

export function hexToPublicKey(hex: string): PublicKey {
  return new PublicKey(Buffer.from(hex.slice(2), "hex"));
}

export async function signAndBroadcast(
  circleClient: ReturnType<typeof initiateDeveloperControlledWalletsClient>,
  connection: Connection,
  transaction: Transaction,
  walletAddress: string,
  label: string,
): Promise<string> {
  const serialized = transaction.serialize({
    requireAllSignatures: false,
    verifySignatures: false,
  });

  console.log(`Signing ${label} via Circle Wallets...`);
  const signResult = await circleClient.signTransaction({
    walletAddress,
    blockchain: "SOL-DEVNET",
    rawTransaction: serialized.toString("base64"),
  });

  const signedTxBase64 = signResult.data?.signedTransaction;
  if (!signedTxBase64) throw new Error(`Failed to sign ${label}`);

  console.log(`Broadcasting ${label}...`);
  const signedTxBytes = Buffer.from(signedTxBase64, "base64");
  return connection.sendRawTransaction(signedTxBytes);
}

export function stringifyTypedData<T>(obj: T) {
  return JSON.stringify(obj, (_key, value) =>
    typeof value === "bigint" ? value.toString() : value,
  );
}

​
Step 3. Deposit into a unified crosschain balance (Circle Wallets)

The deposit script submits a Gateway deposit on Solana Devnet. You can skip to the full deposit script if you prefer.
Do not send USDC directly to the Gateway Wallet address or custody account. You must use a Gateway deposit instruction for the funds to be credited to your unified balance.

​
3.1. Create the deposit script

touch deposit.ts

​
3.2. Define constants and helpers

Set the deposit amount near the top of the file, then derive the owner ATA and load the account so the script can validate balance before it builds the Gateway instruction.
const DEPOSIT_AMOUNT = new BN(1_000_000);

​
3.3. Initialize connection, Anchor client, and validate balance

Initialize the connection, check the source wallet balance, then set up the Anchor client and derive the Gateway PDAs.
const connection = new Connection(RPC_ENDPOINT, "confirmed");
const usdcMint = new PublicKey(USDC_ADDRESS);
const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
const owner = new PublicKey(DEPOSITOR_ADDRESS);

const userTokenAccount = getAssociatedTokenAddressSync(usdcMint, owner);
const tokenAccountInfo = await getAccount(connection, userTokenAccount);

const dummyWallet = new Wallet(Keypair.generate());
const provider = new AnchorProvider(
  connection,
  dummyWallet,
  AnchorProvider.defaultOptions(),
);

​
3.4. Execute the deposit

After the balance check and PDA derivation, build the Gateway deposit instruction, sign it with Circle Wallets, broadcast it, and wait for Solana confirmation.
const depositIx = await program.methods
  .deposit(DEPOSIT_AMOUNT)
  .accountsPartial({
    payer: owner,
    owner: owner,
    gatewayWallet: pdas.wallet,
    ownerTokenAccount: userTokenAccount,
    custodyTokenAccount: pdas.custody,
    deposit: pdas.deposit,
    depositorDenylist: pdas.denylist,
    tokenProgram: TOKEN_PROGRAM_ID,
    systemProgram: SystemProgram.programId,
  })
  .instruction();

const txSignature = await signAndBroadcast(
  client,
  connection,
  transaction,
  DEPOSITOR_ADDRESS,
  "deposit",
);

​
3.5. Full deposit script (Circle Wallets)

The script validates the source balance, builds the Gateway deposit instruction, and confirms the deposit on Solana Devnet. Inline comments explain each stage.
deposit.ts
import {
  Wallet,
  AnchorProvider,
  setProvider,
  Program,
} from "@coral-xyz/anchor";
import {
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  Transaction,
} from "@solana/web3.js";
import {
  getAssociatedTokenAddressSync,
  getAccount,
  TOKEN_PROGRAM_ID,
} from "@solana/spl-token";
import BN from "bn.js";
import {
  RPC_ENDPOINT,
  GATEWAY_WALLET_ADDRESS,
  USDC_ADDRESS,
  client,
  gatewayWalletIdl,
  findDepositPDAs,
  signAndBroadcast,
} from "./config.js";

const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

if (!DEPOSITOR_ADDRESS) {
  console.error("Missing required env var: DEPOSITOR_ADDRESS");
  process.exit(1);
}

const DEPOSIT_AMOUNT = new BN(1_000_000);

async function main() {
  // Set up the Solana connection and core account addresses.
  const connection = new Connection(RPC_ENDPOINT, "confirmed");
  const usdcMint = new PublicKey(USDC_ADDRESS);
  const programId = new PublicKey(GATEWAY_WALLET_ADDRESS);
  const owner = new PublicKey(DEPOSITOR_ADDRESS);

  console.log(`Using account: ${owner.toBase58()}`);
  console.log(`\n=== Processing Solana Devnet ===`);

  // [1] Check the depositor's current USDC balance.
  const userTokenAccount = getAssociatedTokenAddressSync(usdcMint, owner);
  const tokenAccountInfo = await getAccount(connection, userTokenAccount);
  const currentBalance = Number(tokenAccountInfo.amount) / 1_000_000;
  console.log(`Current balance: ${currentBalance} USDC`);

  if (tokenAccountInfo.amount < BigInt(DEPOSIT_AMOUNT.toString())) {
    throw new Error(
      "Insufficient USDC balance. Please top up at https://faucet.circle.com",
    );
  }

  // [2] Set up the Anchor client and derive the Gateway deposit PDAs.
  const dummyWallet = new Wallet(Keypair.generate());
  const provider = new AnchorProvider(
    connection,
    dummyWallet,
    AnchorProvider.defaultOptions(),
  );
  setProvider(provider);
  const program = new Program(gatewayWalletIdl, provider);
  const pdas = findDepositPDAs(programId, usdcMint, owner);

  // [3] Build, sign, and confirm the Gateway deposit transaction.
  const depositIx = await program.methods
    .deposit(DEPOSIT_AMOUNT)
    .accountsPartial({
      payer: owner,
      owner: owner,
      gatewayWallet: pdas.wallet,
      ownerTokenAccount: userTokenAccount,
      custodyTokenAccount: pdas.custody,
      deposit: pdas.deposit,
      depositorDenylist: pdas.denylist,
      tokenProgram: TOKEN_PROGRAM_ID,
      systemProgram: SystemProgram.programId,
    })
    .instruction();

  const { blockhash, lastValidBlockHeight } =
    await connection.getLatestBlockhash();
  const transaction = new Transaction();
  transaction.add(depositIx);
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = owner;

  const txSignature = await signAndBroadcast(
    client,
    connection,
    transaction,
    DEPOSITOR_ADDRESS,
    "deposit",
  );

  await connection.confirmTransaction(
    { signature: txSignature, blockhash, lastValidBlockHeight },
    "confirmed",
  );

  console.log(`Done on Solana Devnet. Deposit tx: ${txSignature}`);
}

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

​
3.6. Run the deposit script

npm run deposit
Wait for the required number of block confirmations. Once the deposit transaction is final, your Gateway balance on Solana Devnet will be updated. Solana Devnet transactions typically reach finality in seconds.

​
3.7. Check the balances on the Gateway Wallet

Create a new file called balances.ts, and add the following code. This script retrieves the USDC balances available from your Gateway Wallet for the DEPOSITOR_ADDRESS currently set in .env.
balances.ts
interface GatewayBalancesResponse {
  balances: Array<{
    domain: number;
    balance: string;
  }>;
}

const EVM_DOMAINS = {
  ethereum: 0,
  avalanche: 1,
  optimism: 2,
  arbitrum: 3,
  base: 6,
  polygon: 7,
  unichain: 10,
  arc: 26,
};

const SOLANA_DOMAINS = {
  solana: 5,
};

const DOMAINS = { ...EVM_DOMAINS, ...SOLANA_DOMAINS };

const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;

if (!DEPOSITOR_ADDRESS) {
  console.error("Missing required env var: DEPOSITOR_ADDRESS");
  process.exit(1);
}

const isEvmAddress = DEPOSITOR_ADDRESS.startsWith("0x");

async function main() {
  console.log(`Depositor address: ${DEPOSITOR_ADDRESS}`);
  console.log(`Address type: ${isEvmAddress ? "EVM" : "Solana"}\n`);

  const activeDomains = isEvmAddress ? EVM_DOMAINS : SOLANA_DOMAINS;
  const domainIds = Object.values(activeDomains);
  const body = {
    token: "USDC",
    sources: domainIds.map((domain) => ({
      domain,
      depositor: DEPOSITOR_ADDRESS,
    })),
  };

  const res = await fetch(
    "https://gateway-api-testnet.circle.com/v1/balances",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    },
  );

  const result = (await res.json()) as GatewayBalancesResponse;

  let total = 0;
  for (const balance of result.balances) {
    const chain =
      Object.keys(DOMAINS).find(
        (k) => DOMAINS[k as keyof typeof DOMAINS] === balance.domain,
      ) || `Domain ${balance.domain}`;
    const amount = parseFloat(balance.balance);
    console.log(`${chain}: ${amount.toFixed(6)} USDC`);
    total += amount;
  }

  console.log(`\nTotal: ${total.toFixed(6)} USDC`);
}

main().catch((error) => {
  console.error("\nError:", error);
  process.exit(1);
});
You can run it to verify your balance on Gateway.
npm run balances

​
Step 4. Transfer USDC from Solana to Solana

This step transfers USDC from your Solana Devnet Gateway balance to a recipient on Solana Devnet. Both paths create and sign the Solana burn intent first. Direct mint then retrieves the Gateway attestation and calls gatewayMint(...) on Solana Devnet from your wallet, while Forwarding Service lets Circle complete the Solana mint for you.

​
4.1. Create the Solana transfer script

You can skip to the full transfer script if you prefer.
touch transfer-from-sol.ts

​
4.2. Define constants and types

This flow uses the same Solana burn intent layout as the standard Gateway quickstart, but swaps in Circle Wallet signing for both the burn intent and the mint transaction.
const TRANSFER_AMOUNT = 0.1;
const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
const MAX_FEE = 2_010000n;
const MAX_UINT64 = 2n ** 64n - 1n;

​
4.3. Add helper functions

The helper layer encodes the Solana burn intent, creates a lightweight Anchor provider, and exposes the address conversion utilities required for Gateway minting.
function createProvider(connection: Connection) {
  const dummyWallet = new Wallet(Keypair.generate());
  const provider = new AnchorProvider(
    connection,
    dummyWallet,
    AnchorProvider.defaultOptions(),
  );
  setProvider(provider);
  return provider;
}

​
4.4. Initialize connection and create recipient ATA

Before minting to the destination wallet, derive the recipient Associated Token Account and create it idempotently. In this script, the source Developer-Controlled Wallet pays for the account creation.
For transfers to Solana, the destinationRecipient must be an initialized USDC Token Account. If the intended recipient is a standard wallet address, use its Associated Token Account (ATA), not the recipient wallet address itself.
const provider = createProvider(connection);

const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
const ataTx = new Transaction();
ataTx.add(
  createAssociatedTokenAccountIdempotentInstruction(
    owner,
    recipientAta,
    recipientPubkey,
    usdcMint,
  ),
);

​
4.5. Create and sign burn intent

Encode the Solana burn intent, prefix the payload, and sign it with the source Developer-Controlled Wallet.
const burnIntent = createBurnIntent({
  sourceDepositor: owner.toBase58(),
  destinationRecipient: recipientAta.toBase58(),
  sourceSigner: owner.toBase58(),
});

const sigResult = await client.signMessage({
  walletAddress: DEPOSITOR_ADDRESS,
  blockchain: "SOL-DEVNET",
  encodedByHex: true,
  message: "0x" + prefixed.toString("hex"),
});

​
4.6. Request attestation from Gateway API

Submit the signed burn intent to the Gateway API and decode the attestation set that comes back from the response.
const response = await fetch(
  "https://gateway-api-testnet.circle.com/v1/transfer",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: stringifyTypedData(request),
  },
);

​
4.7. Set up minter client

Once the API returns the attestation, initialize the Gateway Minter program and derive the PDA accounts needed for the Solana mint.
The ordered remaining-account list and PDA derivations are documented in Solana Programs and Interfaces. For static instruction definitions, use the onchain IDLs linked from that page.
const minterProgram = new Program(gatewayMinterIdl, provider);
const [minterPda] = PublicKey.findProgramAddressSync(
  [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
  minterProgramId,
);

​
4.8. Mint on Solana

Create the mint instruction, sign the transaction with the source Developer-Controlled Wallet, and confirm it on Solana Devnet.This script uses the source Solana wallet as both payer and destinationCaller. The recipient wallet owns the recipient ATA that receives the minted USDC.In this quickstart’s client shape, the instruction accounts are assembled as the fixed gatewayMint accounts first, followed by one ordered triplet per attestation: custody_token_account, destination_recipient, and transfer_spec_hash_account.
const mintIx = await minterProgram.methods
  .gatewayMint({
    attestation: attestationBytes,
    signature: signatureBytes,
  })
  .accountsPartial({
    gatewayMinter: minterPda,
    destinationCaller: owner,
    payer: owner,
    systemProgram: SystemProgram.programId,
    tokenProgram: TOKEN_PROGRAM_ID,
  })
  .remainingAccounts(remainingAccounts)
  .instruction();

​
4.9. Full Solana transfer script (Circle Wallets)

The script creates the recipient ATA, signs a Solana burn intent, requests a Gateway attestation, and mints on Solana Devnet. Inline comments explain each stage.
transfer-from-sol.ts
import { randomBytes } from "node:crypto";
import {
  Wallet,
  AnchorProvider,
  setProvider,
  Program,
  utils,
} from "@coral-xyz/anchor";
import {
  Connection,
  Keypair,
  PublicKey,
  SystemProgram,
  Transaction,
} from "@solana/web3.js";
import {
  TOKEN_PROGRAM_ID,
  getAssociatedTokenAddressSync,
  createAssociatedTokenAccountIdempotentInstruction,
} from "@solana/spl-token";
import { u32be, struct, blob, offset, Layout } from "@solana/buffer-layout";
import {
  RPC_ENDPOINT,
  GATEWAY_WALLET_ADDRESS,
  GATEWAY_MINTER_ADDRESS,
  USDC_ADDRESS,
  SOLANA_DOMAIN,
  SOLANA_ZERO_ADDRESS,
  client,
  gatewayMinterIdl,
  publicKey,
  hexToPublicKey,
  solanaAddressToBytes32,
  decodeAttestationSet,
  findCustodyPda,
  findTransferSpecHashPda,
  signAndBroadcast,
  stringifyTypedData,
} from "./config.js";

const DEPOSITOR_ADDRESS = process.env.DEPOSITOR_ADDRESS!;
const RECIPIENT_ADDRESS = process.env.RECIPIENT_ADDRESS!;

if (!DEPOSITOR_ADDRESS || !RECIPIENT_ADDRESS) {
  console.error(
    "Missing required env vars: DEPOSITOR_ADDRESS, RECIPIENT_ADDRESS",
  );
  process.exit(1);
}

const TRANSFER_AMOUNT = 0.1;
const TRANSFER_VALUE = BigInt(Math.floor(TRANSFER_AMOUNT * 1e6));
const MAX_FEE = 2_010000n;
const MAX_UINT64 = 2n ** 64n - 1n;

const TRANSFER_SPEC_MAGIC = 0xca85def7;
const BURN_INTENT_MAGIC = 0x070afbc2;

// Custom layout for 256-bit unsigned integers.
class UInt256BE extends Layout<bigint> {
  constructor(property: string) {
    super(32, property);
  }
  decode(b: Buffer, offset = 0) {
    const buffer = b.subarray(offset, offset + 32);
    return buffer.readBigUInt64BE(24);
  }
  encode(src: bigint, b: Buffer, offset = 0) {
    const buffer = Buffer.alloc(32);
    buffer.writeBigUInt64BE(BigInt(src), 24);
    buffer.copy(b, offset);
    return 32;
  }
}

const uint256be = (property: string) => new UInt256BE(property);

const BurnIntentLayout = struct([
  u32be("magic"),
  uint256be("maxBlockHeight"),
  uint256be("maxFee"),
  u32be("transferSpecLength"),
  struct(
    [
      u32be("magic"),
      u32be("version"),
      u32be("sourceDomain"),
      u32be("destinationDomain"),
      publicKey("sourceContract"),
      publicKey("destinationContract"),
      publicKey("sourceToken"),
      publicKey("destinationToken"),
      publicKey("sourceDepositor"),
      publicKey("destinationRecipient"),
      publicKey("sourceSigner"),
      publicKey("destinationCaller"),
      uint256be("value"),
      blob(32, "salt"),
      u32be("hookDataLength"),
      blob(offset(u32be(), -4), "hookData"),
    ] as any,
    "spec",
  ),
] as any);

function createBurnIntent(params: {
  sourceDepositor: string;
  destinationRecipient: string;
  sourceSigner: string;
}) {
  const { sourceDepositor, destinationRecipient, sourceSigner } = params;

  return {
    maxBlockHeight: MAX_UINT64,
    maxFee: MAX_FEE,
    spec: {
      version: 1,
      sourceDomain: SOLANA_DOMAIN,
      destinationDomain: SOLANA_DOMAIN,
      sourceContract: solanaAddressToBytes32(GATEWAY_WALLET_ADDRESS),
      destinationContract: solanaAddressToBytes32(GATEWAY_MINTER_ADDRESS),
      sourceToken: solanaAddressToBytes32(USDC_ADDRESS),
      destinationToken: solanaAddressToBytes32(USDC_ADDRESS),
      sourceDepositor: solanaAddressToBytes32(sourceDepositor),
      destinationRecipient: solanaAddressToBytes32(destinationRecipient),
      sourceSigner: solanaAddressToBytes32(sourceSigner),
      destinationCaller: solanaAddressToBytes32(SOLANA_ZERO_ADDRESS),
      value: TRANSFER_VALUE,
      salt: "0x" + randomBytes(32).toString("hex"),
      hookData: "0x",
    },
  };
}

// Encode the burn intent into the binary layout expected by Gateway.
function encodeBurnIntent(bi: ReturnType<typeof createBurnIntent>): Buffer {
  const hookData = Buffer.from((bi.spec.hookData || "0x").slice(2), "hex");
  const prepared = {
    magic: BURN_INTENT_MAGIC,
    maxBlockHeight: bi.maxBlockHeight,
    maxFee: bi.maxFee,
    transferSpecLength: 340 + hookData.length,
    spec: {
      magic: TRANSFER_SPEC_MAGIC,
      version: bi.spec.version,
      sourceDomain: bi.spec.sourceDomain,
      destinationDomain: bi.spec.destinationDomain,
      sourceContract: hexToPublicKey(bi.spec.sourceContract),
      destinationContract: hexToPublicKey(bi.spec.destinationContract),
      sourceToken: hexToPublicKey(bi.spec.sourceToken),
      destinationToken: hexToPublicKey(bi.spec.destinationToken),
      sourceDepositor: hexToPublicKey(bi.spec.sourceDepositor),
      destinationRecipient: hexToPublicKey(bi.spec.destinationRecipient),
      sourceSigner: hexToPublicKey(bi.spec.sourceSigner),
      destinationCaller: hexToPublicKey(bi.spec.destinationCaller),
      value: bi.spec.value,
      salt: Buffer.from(bi.spec.salt.slice(2), "hex"),
      hookDataLength: hookData.length,
      hookData,
    },
  };
  const buffer = Buffer.alloc(72 + 340 + hookData.length);
  const bytesWritten = BurnIntentLayout.encode(prepared, buffer);
  return buffer.subarray(0, bytesWritten);
}

// Create a lightweight Anchor provider for PDA derivation and instruction building.
function createProvider(connection: Connection) {
  const dummyWallet = new Wallet(Keypair.generate());
  const provider = new AnchorProvider(
    connection,
    dummyWallet,
    AnchorProvider.defaultOptions(),
  );
  setProvider(provider);
  return provider;
}

async function main() {
  // Set up the Solana connection and destination accounts.
  const connection = new Connection(RPC_ENDPOINT, "confirmed");
  const usdcMint = new PublicKey(USDC_ADDRESS);
  const minterProgramId = new PublicKey(GATEWAY_MINTER_ADDRESS);
  const owner = new PublicKey(DEPOSITOR_ADDRESS);
  const recipientPubkey = new PublicKey(RECIPIENT_ADDRESS);

  console.log(`Using account: ${owner.toBase58()}`);
  console.log(`Transferring from: Solana Devnet -> Solana Devnet`);

  const provider = createProvider(connection);

  // [1] Create the recipient ATA if it does not already exist.
  const recipientAta = getAssociatedTokenAddressSync(usdcMint, recipientPubkey);
  const { blockhash: ataBlockhash, lastValidBlockHeight: ataBlockHeight } =
    await connection.getLatestBlockhash();
  const ataTx = new Transaction();
  ataTx.add(
    createAssociatedTokenAccountIdempotentInstruction(
      owner,
      recipientAta,
      recipientPubkey,
      usdcMint,
    ),
  );
  ataTx.recentBlockhash = ataBlockhash;
  ataTx.feePayer = owner;

  const ataSig = await signAndBroadcast(
    client,
    connection,
    ataTx,
    DEPOSITOR_ADDRESS,
    "ATA creation",
  );
  await connection.confirmTransaction(
    {
      signature: ataSig,
      blockhash: ataBlockhash,
      lastValidBlockHeight: ataBlockHeight,
    },
    "confirmed",
  );

  // [2] Create and sign the Solana burn intent.
  const burnIntent = createBurnIntent({
    sourceDepositor: owner.toBase58(),
    destinationRecipient: recipientAta.toBase58(),
    sourceSigner: owner.toBase58(),
  });

  const encoded = encodeBurnIntent(burnIntent);
  const prefixed = Buffer.concat([
    Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
    encoded,
  ]);

  const sigResult = await client.signMessage({
    walletAddress: DEPOSITOR_ADDRESS,
    blockchain: "SOL-DEVNET",
    encodedByHex: true,
    message: "0x" + prefixed.toString("hex"),
  });

  const burnIntentSignature = sigResult.data?.signature;
  if (!burnIntentSignature) throw new Error("Failed to sign burn intent");

  const formattedSignature = burnIntentSignature.startsWith("0x")
    ? burnIntentSignature
    : `0x${burnIntentSignature}`;

  const request = [{ burnIntent, signature: formattedSignature }];
  console.log("Signed burn intent.");

  // [3] Request the attestation set from Gateway API.
  const response = await fetch(
    "https://gateway-api-testnet.circle.com/v1/transfer",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: stringifyTypedData(request),
    },
  );

  const json = (await response.json()) as {
    attestation: string;
    signature: string;
    success?: boolean;
    message?: string;
  };
  if (json.success === false) {
    throw new Error(`Gateway API error: ${json.message}`);
  }
  console.log("Gateway API response:", JSON.stringify(json, null, 2));

  const { attestation, signature: mintSignature } = json;
  const decoded = decodeAttestationSet(attestation);

  // [4] Set up the Gateway Minter client and remaining accounts.
  const minterProgram = new Program(gatewayMinterIdl, provider);
  const [minterPda] = PublicKey.findProgramAddressSync(
    [Buffer.from(utils.bytes.utf8.encode("gateway_minter"))],
    minterProgramId,
  );

  const remainingAccounts = decoded.attestations.flatMap((e) => [
    {
      pubkey: findCustodyPda(e.destinationToken, minterProgramId),
      isWritable: true,
      isSigner: false,
    },
    { pubkey: e.destinationRecipient, isWritable: true, isSigner: false },
    {
      pubkey: findTransferSpecHashPda(e.transferSpecHash, minterProgramId),
      isWritable: true,
      isSigner: false,
    },
  ]);

  const attestationBytes = Buffer.from(attestation.slice(2), "hex");
  const signatureBytes = Buffer.from(mintSignature.slice(2), "hex");

  // [5] Mint on Solana with the returned attestation.
  console.log("Minting funds on Solana Devnet...");
  const mintIx = await minterProgram.methods
    .gatewayMint({
      attestation: attestationBytes,
      signature: signatureBytes,
    })
    .accountsPartial({
      gatewayMinter: minterPda,
      destinationCaller: owner,
      payer: owner,
      systemProgram: SystemProgram.programId,
      tokenProgram: TOKEN_PROGRAM_ID,
    })
    .remainingAccounts(remainingAccounts)
    .instruction();

  const { blockhash, lastValidBlockHeight } =
    await connection.getLatestBlockhash();
  const mintTx = new Transaction();
  mintTx.add(mintIx);
  mintTx.recentBlockhash = blockhash;
  mintTx.feePayer = owner;

  const mintSig = await signAndBroadcast(
    client,
    connection,
    mintTx,
    DEPOSITOR_ADDRESS,
    "mint",
  );

  await connection.confirmTransaction(
    { signature: mintSig, blockhash, lastValidBlockHeight },
    "confirmed",
  );

  console.log(`Minted ${Number(TRANSFER_VALUE) / 1_000_000} USDC`);
  console.log(`Mint transaction hash (Solana Devnet):`, mintSig);
}

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

​
4.10. Run the Solana direct-mint script

Run the script to burn from your Solana Devnet Gateway balance and mint to the recipient ATA on Solana Devnet.Confirm these values before running:
  • DEPOSITOR_ADDRESS is the source Solana Devnet wallet
  • RECIPIENT_ADDRESS is the destination Solana Devnet wallet
  • the source depositor has a Gateway balance on Solana Devnet
  • the source Solana wallet can submit the ATA creation and mint transactions on Solana Devnet
Gateway fees are charged per burn intent and are based on the source blockchain you burn from. Choosing where to hold and burn Gateway balances can affect transfer costs. For fee details, see Gateway Fees.
npm run transfer-from-sol
When the transfer succeeds, the script logs the minted amount and Solana Devnet mint transaction hash.