Build CCIP

This instruction type enables token bridging across different blockchain networks using Chainlink’s Cross-Chain Interoperability Protocol (CCIP). Provide source and destination tokens with the amount to generate a cross-chain bridging instruction via CCIP.

How It Works

The CCIP bridging flow:

Validates route - Ensures the source and destination chains are CCIP-compatible
Calculates fees - Determines the required CCIP fee in source chain’s native token
Locks/burns tokens - Secures tokens on the source chain
Mints/unlocks tokens - Releases tokens on the destination chain
Enables composition - Combines seamlessly with other flow types

Parameters

When using /instructions/build-ccip in your composeFlows array:

Parameter	Type	Required	Description
`srcChainId`	number	Yes	Source blockchain chain ID
`dstChainId`	number	Yes	Destination blockchain chain ID
`srcToken`	string	Yes	Token address on the source chain
`dstToken`	string	Yes	Token address on the destination chain
`amount`	string	Yes	Token amount in smallest unit (wei for 18 decimals)

CCIP Fee Payment: CCIP fees are always paid in the native token (ETH, MATIC, etc.) of the source chain. The fee is automatically calculated and handled based on your execution mode:

EOA Mode (Fusion): Tokens are funded into the Nexus Smart Account via funding transaction which will be then used to pay for CCIP fees.
Smart Account Mode: Funds must already exist in your Smart Account, including sufficient native tokens for CCIP fees.
EOA 7702 Mode: Your EOA acts as a Smart Account. Funds must already be present, including native tokens for fees.

If your source token is not the native token, the API automatically swaps a portion to cover CCIP fees if your smart account doesn’t already have sufficient native tokens.

Complete Workflow Examples

Basic Bridge
Swap & Bridge
Bridge with Withdrawal

Bridge USDC from Base to Optimism

import { createWalletClient, http, parseUnits } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http()
});

// Step 1: Build quote request
const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    {
      type: '/instructions/build-ccip',
      data: {
        srcChainId: 8453,                                         // Base
        dstChainId: 10,                                           // Optimism
        srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',   // USDC on Base
        dstToken: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',   // USDC on Optimism
        amount: parseUnits('100', 6).toString()                     // 100 USDC
      }
    }
  ]
};

// Step 2: Get quote
const quoteResponse = await fetch("https://api.biconomy.io/v1/quote", {
  method: "POST",
  headers: {
    "X-API-Key": meeApiKey,
    "Content-Type": "application/json",
  },
  body: stringify(quoteRequest),
});

const quote = await quoteResponse.json();

// Then sign and POST to /v1/execute

The CCIP finality time typically ranges between 15 to 22 minutes.
To ensure successful execution, always set the upperBoundTimestamp at least 22 minutes ahead (or more) to accommodate destination‐chain finality delays.

Best Practices

Verify Token Addresses

Always verify source and destination token addresses are correct and correspond to the same token on different chains:

// ✅ Good - Same token (USDC) on different chains
srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
dstToken: '0x0b2c639c533813f4aa9d7837caf62653d097ff85', // USDC on Optimism

// ❌ Bad - Mismatched tokens
srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
dstToken: '0xb0897686c545045aFc77CF20eC7A532E3120E0F1', // LINK on Polygon

Format Amounts Correctly

Ensure amounts are specified in the token’s smallest unit:

// For 18-decimal tokens (LINK, WETH)
amount: parseUnits('1', 18).toString()      // 1 token = 1000000000000000000 wei

// For 6-decimal tokens (USDC)
amount: parseUnits('100', 6).toString()     // 100 tokens = 100000000

// Always use string format
amount: '1000000000000000000'               // ✅ Correct
amount: 1000000000000000000                 // ❌ Wrong (number loses precision)

Account for CCIP Fees

CCIP fees are always paid in the source chain’s native token (ETH, MATIC, BNB, etc.) and are handled differently based on execution mode:EOA Mode (Fusion)

// Tokens are funded via funding transaction
// API automatically swaps portion to native token for fees if needed
const quoteRequest = {
  mode: 'eoa',
  ownerAddress: account.address,
  fundingTokens: [{
    tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
    chainId: 8453,
    amount: parseUnits('100', 6).toString()
    // API will swap some USDC → ETH for CCIP fees automatically
  }],
  composeFlows: [/* ... */]
};

Smart Account Mode

// Funds must already be in Smart Account
// Ensure sufficient native tokens are available for fees
const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  // No fundingTokens - funds must exist in SCA
  composeFlows: [/* ... */]
};

EOA 7702 Mode

// EOA acts as Smart Account
// Funds must already be present in EOA
const quoteRequest = {
  mode: 'eoa-7702',
  ownerAddress: account.address,
  // No fundingTokens - funds must exist in EOA
  composeFlows: [/* ... */]
};

Combine with Other Instructions

CCIP bridging can be combined with swaps, DeFi operations, and withdrawals:

composeFlows: [
  // Swap on source chain
  { type: '/instructions/intent-simple', ... },
  
  // Bridge to destination chain
  { type: '/instructions/build-ccip', ... },
  
  // Interact with DeFi on destination chain
  { type: '/instructions/build', ... }
]

Use Runtime Balance for Dynamic Amounts

When bridging after a swap, use runtime balance to transfer the exact output:

// After swapping, bridge the resulting balance
{
  type: '/instructions/build-ccip',
  data: {
    srcChainId: '8453',
    dstChainId: '137',
    srcToken: swapOutputToken,
    dstToken: correspondingTokenOnDst,
    amount: {
      type: 'runtimeErc20Balance',
      tokenAddress: swapOutputToken,
      constraints: { gte: '1' }
    }
  }
}

Common Use Cases

1. Portfolio Rebalancing

Automatically rebalance your portfolio across multiple chains and protocols.
Easily move assets to maintain target allocations, optimize exposure, and minimize gas fees.

2. Cross-Chain Yield Farming

Maximize returns by deploying assets to the highest-yield opportunities across chains.
Seamlessly bridge tokens and interact with DeFi protocols to compound rewards.

3. Cross-Chain Swaps

Swap tokens across chains in a single transaction.
Enjoy fast, secure, and low-cost swaps without manual bridging or complex setups.

4. Custom Use Cases

Build your own workflows with our SDK and APIs.
Whether it’s automated arbitrage, liquidity migration, or multi-chain dApps — the possibilities are endless.

Troubleshooting

Unsupported token pair

Ensure both tokens are supported on the CCIP lane:

Check CCIP supported tokens
Verify the token addresses are correct for each chain
Confirm the lane exists between source and destination chains

Insufficient native tokens for fees

CCIP fees are always paid in native tokens on the source chain. The handling depends on your execution mode:EOA Mode (Fusion)

The API automatically swaps a portion of your source token to native token for fees
No manual action needed - just ensure sufficient source token amount
Example: Bridging 100 USDC, API swaps ~1 USDC → ETH for fees automatically

Smart Account Mode

Native tokens must already be present in your Smart Account
Ensure you have ETH on Ethereum, MATIC on Polygon, etc.
If insufficient, fund your SCA with native tokens before bridging

EOA 7702 Mode

Native tokens must already be present in your EOA
Your EOA acts as a Smart Account, so pre-fund with native tokens
Check balance before initiating the bridge transaction

Bridge transaction pending

CCIP bridges typically take 10-20 minutes:

Cross-chain messages require finality on the source chain
Track status using CCIP Explorer with source chain transaction hash

Token amount mismatch

Verify you’re using the correct decimal places:

Most tokens use 18 decimals (LINK, WETH, DAI)
USDC and USDT use 6 decimals
Use parseUnits(amount, decimals) to avoid errors

Always verify chain IDs, token addresses, and amounts before executing a bridge transaction. Incorrect parameters may result in loss of funds. CCIP transactions are irreversible.

Example

Check out the full working example that demonstrates how to integrate CCIP with SuperTransaction API for token bridging. View on GitHub →

About Supertransaction API

Building Workflow Instructions

Executing Workflows

API Reference

How It Works

Parameters

Complete Workflow Examples

Best Practices

Common Use Cases

1. Portfolio Rebalancing

2. Cross-Chain Yield Farming

3. Cross-Chain Swaps

4. Custom Use Cases

Troubleshooting

Example

About Supertransaction API

Building Workflow Instructions

Executing Workflows

API Reference

​How It Works

​Parameters

​Complete Workflow Examples

​Best Practices

​Common Use Cases

​1. Portfolio Rebalancing

​2. Cross-Chain Yield Farming

​3. Cross-Chain Swaps

​4. Custom Use Cases

​Troubleshooting

​Example

How It Works

Parameters

Complete Workflow Examples

Best Practices

Common Use Cases

1. Portfolio Rebalancing

2. Cross-Chain Yield Farming

3. Cross-Chain Swaps

4. Custom Use Cases

Troubleshooting

Example