Quick start

Overview

In this quickstart, you’ll execute a cross-chain swap that transfers 0.1 USDC from Polygon to Arbitrum. This example demonstrates the complete flow: creating an order, approving token spending, and submitting the bridge transaction.

Before you begin: Make sure you’ve completed the environment setup and have a small amount of USDC on Polygon plus MATIC for gas fees.

What you’ll learn

By the end of this guide, you’ll understand how to:

Create a cross-chain order using the deBridge API
Handle ERC-20 token approvals
Submit bridge transactions and track them on block explorers
Parse order estimations for fees and expected output

Run your first swap

Navigate to the project directory

Open your terminal and navigate to the cloned repository:

cd api-integrator-example

Run the example script

Execute the basic swap example using npx tsx:

npx tsx ./src/scripts/orders/example-swap.ts

You’ll see output similar to:

Loading environment variables...

Connecting to Polygon at https://polygon-mainnet.g.alchemy.com/v2/...
Connecting to Arbitrum at https://arb-mainnet.g.alchemy.com/v2/...
Polygon connected: matic (chainId=137)
Arbitrum connected: arbitrum (chainId=42161)

Signer address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Creating deBridge order with input:
{
  "srcChainId": "137",
  "srcChainTokenIn": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
  "srcChainTokenInAmount": "100000",
  "dstChainId": "42161",
  "dstChainTokenOut": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "dstChainTokenOutRecipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  ...
}

Order estimation: {
  srcChainTokenIn: { amount: '100000', decimals: 6, symbol: 'USDC' },
  dstChainTokenOut: { amount: '99750', decimals: 6, symbol: 'USDC' },
  fees: { srcChainTokenIn: '250', dstChainTokenOut: '0' }
}

Checking or setting token approval...
Current allowance: 0 USDC
Allowance insufficient—sending approval...
Approval tx hash: 0xabc123...
Waiting for confirmation on Polygonscan: https://polygonscan.com/tx/0xabc123...
Approval successful! ✅

Submitting bridge transaction...
Bridge tx hash: 0xdef456...
Explorer: https://polygonscan.com/tx/0xdef456...
Waiting for confirmation...
Bridge transaction mined.
Status: ✅ Success
Block: 12345678 | Gas used: 234567

Script execution complete.

Monitor your transaction

The script outputs Polygonscan links for both transactions:

Approval transaction: Allows deBridge to spend your USDC
Bridge transaction: Initiates the cross-chain transfer

Click the links to view transaction details on Polygonscan.

Track order fulfillment

Cross-chain transfers take 1-10 minutes depending on network conditions. Track your order on the deBridge Explorer using your wallet address or transaction hash.

This script uses real funds on mainnet! The example transfers 0.1 USDC. Make sure you have:

At least 0.15 USDC on Polygon (0.1 for the transfer + buffer for fees)
MATIC for gas fees (~0.01 MATIC is sufficient)

Understanding the code

Let’s break down what the example-swap.ts script does:

1. Load configuration and connect to providers

import 'dotenv/config';
import { ethers, Wallet, Contract } from 'ethers';

// Load environment variables
const { privateKey, polygonRpcUrl, arbRpcUrl } = getEnvConfig();

// Connect to blockchain providers
const polygonProvider = new JsonRpcProvider(polygonRpcUrl);
const arbitrumProvider = new JsonRpcProvider(arbRpcUrl);

// Initialize wallet
const wallet = new Wallet(privateKey);
const signer = wallet.connect(polygonProvider);

This loads your private key and RPC URLs from .env, then creates provider connections and a wallet signer.

2. Construct the order parameters

import { USDC } from '../../utils/tokens';
import { CHAIN_IDS } from '../../utils/chains';

const orderInput: deBridgeOrderInput = {
  srcChainId: CHAIN_IDS.Polygon.toString(),              // Source: Polygon (137)
  srcChainTokenIn: USDC.POLYGON,                         // Token: USDC
  srcChainTokenInAmount: "100000",                       // Amount: 0.1 USDC (6 decimals)
  dstChainId: CHAIN_IDS.Arbitrum.toString(),            // Destination: Arbitrum (42161)
  dstChainTokenOut: USDC.ARBITRUM,                      // Output: USDC
  dstChainTokenOutRecipient: senderAddress,             // Recipient: Your wallet
  account: senderAddress,                               // Sender: Your wallet
  srcChainOrderAuthorityAddress: wallet.address,        // Authority: Your wallet
  dstChainOrderAuthorityAddress: wallet.address         // Dest authority: Your wallet
};

Token amounts must be in atomic units (smallest denomination). USDC has 6 decimals, so 0.1 USDC = 100,000 atomic units. Use ethers.parseUnits("0.1", 6) to convert.

3. Create the order via deBridge API

const order = await createDebridgeBridgeOrder(orderInput);

console.log("Order estimation:", order.estimation);
// {
//   srcChainTokenIn: { amount: '100000', decimals: 6, symbol: 'USDC' },
//   dstChainTokenOut: { amount: '99750', decimals: 6, symbol: 'USDC' },
//   fees: { srcChainTokenIn: '250', dstChainTokenOut: '0' }
// }

The createDebridgeBridgeOrder function calls:

GET https://dln.debridge.finance/v1.0/dln/order/create-tx

It returns:

tx: Transaction object ready to submit
estimation: Expected input/output amounts and fees

4. Approve token spending

Before deBridge can transfer your USDC, you must approve the spending:

import { erc20Abi } from '../../constants';

const tokenContract = new Contract(
  USDC.POLYGON,
  erc20Abi,
  signer
);

// Check current allowance
const currentAllowance = await tokenContract.allowance(
  senderAddress,
  order.tx.to  // deBridge contract address
);

if (currentAllowance < requiredAmount) {
  // Send approval transaction
  const approveTx = await tokenContract.approve(
    order.tx.to,
    requiredAmount
  );
  
  await approveTx.wait();  // Wait for confirmation
  console.log("Approval successful! ✅");
}

The script includes an ERC-20 ABI with the essential functions:

export const erc20Abi = [
  "function balanceOf(address owner) view returns (uint256)",
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)",
  "function allowance(address owner, address spender) view returns (uint256)",
  "function approve(address spender, uint256 amount) returns (bool)",
];

5. Submit the bridge transaction

Once approved, submit the bridge transaction:

const txResponse = await signer.sendTransaction(order.tx);

console.log(`Bridge tx hash: ${txResponse.hash}`);
console.log(`Explorer: https://polygonscan.com/tx/${txResponse.hash}`);

// Wait for confirmation
const txReceipt = await txResponse.wait();

if (txReceipt.status === 1) {
  console.log("Bridge transaction mined. ✅");
}

Order parameters explained

Here are the key parameters you’ll use in every deBridge order:

Parameter	Type	Description	Example
`srcChainId`	string	Source chain ID	`"137"` (Polygon)
`srcChainTokenIn`	string	Input token address	`"0x3c499c542cEF5E..."` (USDC)
`srcChainTokenInAmount`	string	Input amount in atomic units	`"100000"` (0.1 USDC)
`dstChainId`	string	Destination chain ID	`"42161"` (Arbitrum)
`dstChainTokenOut`	string	Output token address	`"0xaf88d065e77c8c..."` (USDC)
`dstChainTokenOutRecipient`	string	Recipient address	`"0x742d35Cc663..."`
`account`	string	Sender address	`"0x742d35Cc663..."`
`srcChainOrderAuthorityAddress`	string	Who can cancel the order	`"0x742d35Cc663..."`

Optional parameters

{
  dstChainTokenOutAmount: "auto",           // Expected output (auto = best rate)
  slippage: 0.5,                            // Slippage tolerance in %
  referralCode: 31805,                      // Referral code (default included)
  affiliateFeePercent: 10,                  // Affiliate fee in basis points (10 = 0.1%)
  affiliateFeeRecipient: "0x...",           // Address to receive affiliate fees
  prependOperatingExpenses: true,           // Include operating expenses in input
}

Authority addresses

srcChainOrderAuthorityAddress: Who can cancel the order on source chain
dstChainOrderAuthorityAddress: Who can claim stuck funds on destination

Usually set both to your wallet address for safety.

Understanding fees

The estimation object shows all fees:

fees: {
  srcChainTokenIn: '250',        // Fee in source token (0.0025 USDC)
  dstChainTokenOut: '0'          // Fee in destination token
}

Fees cover:

deBridge protocol fee
Market maker rewards
Operating expenses (gas on destination)

Customize the example

Modify the script to try different scenarios:

// Swap 5 USDC instead of 0.1
const amountToSend = "5";
const amountInAtomicUnit = ethers.parseUnits(amountToSend, 6);

Common issues

Error: insufficient funds for intrinsic transaction cost

You don’t have enough MATIC for gas fees. Get at least 0.01 MATIC from an exchange:

Buy on Polygon Bridge
Transfer from Coinbase/Binance

Error: ERC20: transfer amount exceeds balance

You don’t have enough USDC on Polygon. Check your balance:

# The script will show your balance in the approval section

Get USDC by:

Bridging from another chain
Swapping MATIC for USDC on a DEX

Error: Source and destination chains must differ

You can’t swap on the same chain using the cross-chain API. For same-chain swaps, see /src/scripts/same-chain/ examples.

Transaction takes a long time

Cross-chain transfers typically complete in 1-10 minutes but can take longer during:

High network congestion
Low liquidity periods
Source or destination chain issues

Track your order at app.debridge.finance/orders

How to get testnet tokens?

These examples run on mainnet only. deBridge’s liquidity network operates on production chains. Use minimal amounts for testing:

Start with 0.1 USDC transfers
Keep $5-10 in tokens for multiple tests

Next steps

Explore more examples

Browse 20+ examples including Solana, TRON, hooks, and affiliate programs

Query order status

Learn how to track and manage orders programmatically

Add hooks

Execute custom logic after transfers, like supplying to Aave

API reference

Explore the complete deBridge API documentation

Get Started

Cross-Chain Orders

Same-Chain Swaps

Hooks

Order Management

Affiliate Operations

Reference

Overview

What you’ll learn

Run your first swap

Understanding the code

1. Load configuration and connect to providers

2. Construct the order parameters

3. Create the order via deBridge API

4. Approve token spending

5. Submit the bridge transaction

Order parameters explained

Customize the example

Common issues

Next steps

Explore more examples

Query order status

Add hooks

API reference

Additional resources

Build docs developers (and LLMs) love

Get Started

Cross-Chain Orders

Same-Chain Swaps

Hooks

Order Management

Affiliate Operations

Reference

​Overview

​What you’ll learn

​Run your first swap

​Understanding the code

​1. Load configuration and connect to providers

​2. Construct the order parameters

​3. Create the order via deBridge API

​4. Approve token spending

​5. Submit the bridge transaction

​Order parameters explained

​Customize the example

​Common issues

​Next steps

Explore more examples

Query order status

Add hooks

API reference

​Additional resources

Build docs developers (and LLMs) love

Overview

What you’ll learn

Run your first swap

Understanding the code

1. Load configuration and connect to providers

2. Construct the order parameters

3. Create the order via deBridge API

4. Approve token spending

5. Submit the bridge transaction

Order parameters explained

Customize the example

Common issues

Next steps

Additional resources