Bridging (CCTP)

The SDK bridges native USDC between Base and Solana using Circle CCTP V2. Burn-and-mint means no wrapped token, no pool, no slippage: USDC is burned on the source chain and freshly minted on the destination. Your integration is five calls; the user’s part is one signature on the source chain. Everything after that — attestation, the destination mint, destination gas — is Cesto’s background job.

quote       your server ─▶ Cesto     fees, ETA, net-out (nothing is created)
initiate    your server ─▶ Cesto     → { transferId, unsigned burn tx }
sign        user's wallet            signs + lands the burn on the SOURCE chain
submitBurn  your server ─▶ Cesto     Cesto verifies the burn against Circle
poll        your server ─▶ Cesto     attestation → relayer mint → COMPLETED

Bridging needs a write-scoped API key. It delivers USDC only — investing is a separate step and still needs a Solana wallet (see Bridge, then invest and Integration Models). Bridging runs on mainnet only — every example on this page moves real USDC; test with small amounts first.

Modes

	`standard` (default)	`fast`
Fee	0 — lossless	~1 bps, deducted at mint
Latency	~20s from Solana · ~15–20 min from EVM	~8–20 seconds

With fast, invest what arrived (netOut), not what you burned.

Networks

Bridging is currently mainnet-only, between two chain keys:

Chain key	Chain	Attestation
`base`	Base mainnet	Circle production Iris
`solana`	Solana mainnet	Circle production Iris

Additional chains will be added as they launch — quote / initiate reject unsupported chain keys with a 400.

Quickstart (EVM → Solana)

All amounts are USDC base units (6 decimals) as strings — "1000000" is 1 USDC.

import { Cesto } from '@cesto/sdk';

const cesto = new Cesto({ apiKey: process.env.CESTO_API_KEY }); // write-scoped key

// 1. Quote — fees, ETA, and whether the recipient's USDC ATA exists
const quote = await cesto.bridge.quote({
  sourceChain: 'base',
  destChain: 'solana',
  amount: '10000000', // 10 USDC
  recipient: userSolanaWallet,
  mode: 'fast',
});

// 2. Initiate — creates the transfer, returns the unsigned burn
const { transferId, burn } = await cesto.bridge.initiate({
  sourceChain: 'base',
  destChain: 'solana',
  amount: '10000000',
  recipient: userSolanaWallet,
  mode: 'fast',
  sourceAddress: userEvmAddress, // signs the burn
});

// 3. The user signs on the source chain (viem example)
if (burn && burn.kind === 'evm') {
  if (burn.approvalTx) {
    const hash = await walletClient.sendTransaction(burn.approvalTx);
    await publicClient.waitForTransactionReceipt({ hash });
    // Wait until the allowance is readable before burning — see the note below.
  }
  const burnTxHash = await walletClient.sendTransaction(burn.burnTx);

  // 4. Report the landed burn — Cesto verifies it against Circle
  await cesto.bridge.submitBurn(transferId, { burnTxHash });

  // 5. Wait for the destination mint
  const done = await cesto.bridge.waitForTransfer(transferId);
  done.netOut;      // USDC that arrived
  done.mintTxHash;  // destination mint transaction
}

Confirm the approval before burning. Wait for the approvalTx receipt and for the allowance to be readable on-chain before sending burnTx — load-balanced RPCs lag a few seconds, and an early burn reverts with ERC20: transfer amount exceeds allowance.

Solana-source burns

How a Solana-side burn gets signed depends on whose wallet is burning:

Managed wallet
BYOW

When sourceAddress is a Cesto-managed Solana wallet (provisioned via users.create under your API key), Cesto signs and lands the burn server-side — the sponsor pays the transaction fee and the CCTP message-account rent, so managed wallets need no SOL. initiate returns { status: 'BURN_SUBMITTED', burnTxHash, burn: null } instead of an unsigned burn, so skip submitBurn (re-submitting the same hash is safe/idempotent) and go straight to waitForTransfer:

const res = await cesto.bridge.initiate({
  sourceChain: 'solana',
  destChain: 'base',
  amount: '10000000', // 10 USDC
  recipient: userEvmAddress,
  sourceAddress: user.solanaAddress, // managed wallet → Cesto signs
});

// res.status === 'BURN_SUBMITTED', res.burn === null, res.burnTxHash is landed
const done = await cesto.bridge.waitForTransfer(res.transferId);

See Managed wallets — Withdrawing for the full withdrawal flow.

A self-custody or partner-controlled Solana wallet signs the burn itself. initiate returns burn.kind === 'solana': a base64 transaction plus additionalSignerSecrets — ephemeral, single-use keypairs (CCTP’s message account) that must co-sign alongside the user wallet. They hold no funds:

import { Keypair, Transaction } from '@solana/web3.js';
import bs58 from 'bs58';

const tx = Transaction.from(Buffer.from(burn.transaction, 'base64'));
const extra = burn.additionalSignerSecrets.map((s) => Keypair.fromSecretKey(bs58.decode(s)));
tx.sign(userKeypair, ...extra); // userKeypair loaded server-side from process.env
const burnTxHash = await connection.sendRawTransaction(tx.serialize());
await connection.confirmTransaction(burnTxHash, 'confirmed');
await cesto.bridge.submitBurn(transferId, { burnTxHash });

The signing wallet pays the burn’s costs. Unlike managed burns, BYOW Solana burns are not sponsor-paid: the signing wallet is the fee payer and the CCTP message-account rent payer, so it must hold ~0.005 SOL in addition to the USDC being burned. Without it the burn fails to land.

Treat additionalSignerSecrets like any key material: use them server-side, immediately, for this burn only — never log, persist, or ship them to a browser.

The recipient address

recipient is always a wallet — hex account on EVM, owner wallet on Solana. CCTP mints into a token account, so for Solana destinations Cesto derives the USDC ATA itself and, if it’s the user’s first transfer, creates it at mint time (relayer pays the rent — no SOL needed). quote’s ataExists tells you which case you’re in.

Bridge, then invest

Once a transfer completes, open the position with the arrived amount (netOut, not the burn amount — fast mode deducts its fee at mint):

Managed
BYOW

const done = await cesto.bridge.waitForTransfer(transferId);

const result = await cesto.open.startAndWait({
  user: user.solanaAddress, // the managed wallet that received the funds
  product: 'stable-genius',
  amount: BigInt(done.netOut!),
});

No signature needed — Cesto signs for the managed wallet. See Managed Wallets.

const done = await cesto.bridge.waitForTransfer(transferId);

const result = await cesto.open.execute({
  wallet: userSolanaWallet,
  product: 'stable-genius',
  amount: BigInt(done.netOut!), // not the burn amount — fast mode deducts its fee
  signTransactions: signWithKeypair(keypair), // keypair loaded server-side from process.env
});

See Open a Position for the full client-signed flow.

Withdrawing is the mirror image: close the position, then bridge solana → base back to the user’s EVM wallet (see Solana-source burns for who signs that burn).

Method reference

`bridge.quote(params)` → `BridgeQuote`

BridgeChain

required

base or solana (mainnet).

BridgeChain

required

Chain the USDC arrives on.

string

required

USDC base units (6 decimals) as a decimal string.

string

Destination wallet — enables ataExists for Solana destinations.

'standard' | 'fast'

default:"'standard'"

Speed / fee trade-off.

Returns { mode, amount, maxFee, estimatedFee, netOut, etaSeconds, minFinalityThreshold, ataExists? }. Creates nothing.

`bridge.initiate(params)` → `{ transferId, status, burn, burnTxHash? }`

All quote fields (recipient is required here), plus:

string

required

Source-chain wallet that will sign the burn — or a Cesto-managed Solana wallet, in which case Cesto signs for it.

string

Your user reference, stored on the transfer for reconciliation.

Two response shapes, distinguished by status:

status: 'BURN_TX_BUILT' (default) — burn is { kind: 'evm', chainId, approvalTx?, burnTx } or { kind: 'solana', transaction, additionalSignerSecrets }. approvalTx is present only when the current USDC allowance is insufficient — confirm it before burnTx.
status: 'BURN_SUBMITTED' (managed Solana source wallet) — Cesto signed and landed the burn itself, sponsor paying gas: burn is null and burnTxHash holds the landed burn signature. Skip submitBurn and poll waitForTransfer.

`bridge.submitBurn(transferId, { burnTxHash })`

Reports the landed burn. Cesto verifies it against Circle’s attestation (amount, chains, recipient) and drives the rest in the background.

Circle can take a few seconds to index a fresh burn — short lags are absorbed internally; on a 404, retry after a few seconds. Re-submitting the same hash is safe (it echoes the status), and submitBurn is never auto-retried — poll getTransfer instead of re-sending after a client-side timeout.

`bridge.getTransfer(transferId)` / `bridge.waitForTransfer(transferId, options?)`

Current status, tx hashes, and — once attested — feeExecuted / netOut decoded from the CCTP message. waitForTransfer resolves on COMPLETED and rejects with Cesto.BridgeTransferFailedError on FAILED.

number

default:"5000"

Delay between status polls.

number

default:"1800000"

Max total wait (30 min — beyond standard-mode worst case). A timeout doesn’t stop the transfer; keep polling getTransfer.

Transfer lifecycle

CREATED → BURN_TX_BUILT → BURN_SUBMITTED → ATTESTING → ATTESTED → MINTING → MINTED → COMPLETED
                                                                                     ↘ FAILED

Most of these pass in seconds on fast. The two you’ll surface to users: ATTESTING (“waiting for Circle”, up to ~20 min on standard) and COMPLETED (funds arrived — netOut, feeExecuted, mintTxHash are final). FAILED is terminal with the reason in error — a burned amount is never lost (attestations don’t expire); contact Cesto support with the transferId.

Common errors

Situation	What you get
Read-only key	`403 PermissionDeniedError`
Burn not indexed by Circle yet	`404` — retry `submitBurn` shortly
Burn doesn’t match the transfer	`409 ConflictError`, or `FAILED` if caught at attestation
Same burn attached to another transfer	`409 ConflictError` — nonces are single-use
Unsupported chain key or route	`400` at `quote` / `initiate`
Attestation deadline exceeded	transfer `FAILED`, reason in `error`

Security model

Non-custodial burn — Cesto builds the burn unsigned; only the user’s wallet signs. (Exception: Cesto-managed Solana wallets, which Cesto signs for by design — the key never leaves Cesto’s custody.)
Gas-only relayer — the destination mint is permissionless by protocol design; the relayer pays gas but can only deliver to the mintRecipient baked into the message.
Verified before driven — every burn is matched against Circle’s attested message before a mint is attempted; nonces make double-mints impossible.
Key-scoped — a transfer is visible only to the API key that created it.

Constraints

USDC only, base units as strings everywhere.
Relayer-dependent — mints need a configured relayer on the destination chain; without one, initiate works but the mint fails fast with a configuration error.
Funds only — positions are opened separately via Open a Position.

​Modes

​Networks

​Quickstart (EVM → Solana)

​Solana-source burns

​The recipient address

​Bridge, then invest

​Method reference

​bridge.quote(params) → BridgeQuote

​bridge.initiate(params) → { transferId, status, burn, burnTxHash? }

​bridge.submitBurn(transferId, { burnTxHash })

​bridge.getTransfer(transferId) / bridge.waitForTransfer(transferId, options?)

​Transfer lifecycle

​Common errors

​Security model

​Constraints

Modes

Networks

Quickstart (EVM → Solana)

Solana-source burns

The recipient address

Bridge, then invest

Method reference

`bridge.quote(params)` → `BridgeQuote`

`bridge.initiate(params)` → `{ transferId, status, burn, burnTxHash? }`

`bridge.submitBurn(transferId, { burnTxHash })`

`bridge.getTransfer(transferId)` / `bridge.waitForTransfer(transferId, options?)`

Transfer lifecycle

Common errors

Security model

Constraints