Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Node.js 18 or higher

This project requires Node.js v18 or higher. The recommended version is specified in .nvmrc:
v20.19.6
Check your Node.js version:
node --version
If you’re using nvm, switch to the correct version:
nvm use
Otherwise, download Node.js from nodejs.org
2

Package manager

This project uses npm, which comes bundled with Node.js. Verify your installation:
npm --version
3

RPC provider accounts

You’ll need RPC endpoints for the chains you want to interact with. We recommend Alchemy or Infura.Sign up and create API keys for:
  • Polygon
  • Arbitrum
  • BNB Chain
  • Solana
Free tier RPC endpoints are sufficient for testing. You can add more chains later as needed.
4

Private keys with funds

You’ll need private keys with small amounts of tokens for testing:
  • EVM chains: Private key in hex format (0x...) with gas tokens (MATIC, ETH, BNB)
  • Solana: Private key in base58 format with SOL for gas
  • Test tokens: Small amounts of USDC/USDT on source chains
Never use production private keys! Create new wallets specifically for testing. These examples execute real transactions on mainnet.

​
Installation

1

Clone the repository

Clone the deBridge API Integrator Examples repository:
git clone https://github.com/debridge-finance/api-integrator-example.git
cd api-integrator-example
2

Install dependencies

Install all required npm packages:
npm install
This will install:
  • ethers - Ethereum library for EVM chains
  • @solana/web3.js - Solana web3 library
  • @debridge-finance/dln-client - Official deBridge client
  • tronweb - TRON blockchain library
  • dotenv - Environment variable management
  • typescript - TypeScript compiler
3

Configure environment variables

Create a .env file in the project root by copying the example:
cp .env.example .env
Open .env and configure your credentials:
.env
# EVM private key (hex format with 0x prefix)
SIGNER_PK="0x1234567890abcdef..."

# Solana private key (base58 format)
SOL_PK="your-base58-private-key"

# RPC endpoints - replace <api_key> with your actual keys
POLYGON_RPC_URL="https://polygon-mainnet.g.alchemy.com/v2/<api_key>"
ARB_RPC_URL="https://arb-mainnet.g.alchemy.com/v2/<api_key>"
BNB_RPC_URL="https://bnb-mainnet.g.alchemy.com/v2/<api_key>"
BASE_RPC_URL="https://base-mainnet.g.alchemy.com/v2/<api_key>"
SOL_RPC_URL="https://solana-mainnet.g.alchemy.com/v2/<api_key>"

# TRON configuration (optional)
TRON_RPC_URL="https://api.trongrid.io"
TRON_PK="your-tron-private-key"
TRONGRID_API_KEY="your-trongrid-api-key"

# MegaETH (optional, for specific examples)
MEGA_ETH_RPC_URL="https://your-megaeth-rpc-url"
The .env file is git-ignored to prevent accidentally committing secrets. Never commit your private keys to version control.

​
Environment variables reference

Here’s a complete breakdown of all environment variables:
VariableRequiredDescription
SIGNER_PKYesEVM private key in hex format with 0x prefix. Used for Ethereum, Polygon, Arbitrum, BNB, Base, etc.
SOL_PKFor SolanaSolana private key in base58 format. Required for any Solana-related examples
POLYGON_RPC_URLFor PolygonPolygon mainnet RPC endpoint. Get from Alchemy, Infura, or other providers
ARB_RPC_URLFor ArbitrumArbitrum One mainnet RPC endpoint
BNB_RPC_URLFor BNB ChainBNB Smart Chain mainnet RPC endpoint
BASE_RPC_URLFor BaseBase mainnet RPC endpoint
SOL_RPC_URLFor SolanaSolana mainnet RPC endpoint
TRON_RPC_URLFor TRONTRON mainnet RPC endpoint (usually https://api.trongrid.io)
TRON_PKFor TRONTRON private key
TRONGRID_API_KEYFor TRONTronGrid API key (optional but recommended for rate limits)
MEGA_ETH_RPC_URLFor MegaETHMegaETH RPC endpoint (only needed for MegaETH examples)
You only need to configure RPC URLs for the chains you plan to use. Most examples use Polygon and Arbitrum, so start with those two at minimum.

​
Verify your setup

Test that your environment is configured correctly: 
node --version
# Should output v18+ (recommended: v20.19.6)

​
Project structure

Familiarize yourself with the key directories: 
api-integrator-example/
├── .env                    # Your environment variables (create this)
├── .env.example            # Template for environment variables
├── .nvmrc                  # Node version specification
├── package.json            # Project dependencies
├── tsconfig.json           # TypeScript configuration
└── src/
    ├── constants.ts        # Shared constants (ERC20 ABI, API endpoints)
    ├── types/              # TypeScript type definitions
    ├── utils/              # Utility functions
    │   ├── chains.ts       # Chain ID constants
    │   ├── tokens.ts       # Token addresses across chains
    │   ├── deBridge/       # deBridge API wrapper functions
    │   └── hooks/          # Hook generation utilities
    └── scripts/            # Runnable example scripts
        ├── orders/         # Basic cross-chain swaps
        ├── hooks/          # Advanced hook examples
        ├── affiliates/     # Affiliate program examples
        └── same-chain/     # Same-chain operations

​
Common issues

This means dependencies weren’t installed correctly. Run:
npm install
You either didn’t create a .env file or it’s missing required variables. Copy .env.example to .env and fill in your credentials:
cp .env.example .env
nano .env  # or use your preferred editor
Your wallet needs native tokens for gas fees:
  • Polygon: Need MATIC
  • Arbitrum: Need ETH
  • BNB Chain: Need BNB
  • Solana: Need SOL
Get small amounts from exchanges or faucets.
If you see “Failed to initialize providers” or connection timeout errors:
  • Verify your RPC URLs are correct
  • Check that your API keys are active
  • Ensure you haven’t exceeded free tier rate limits
  • Try using a different RPC provider as a fallback
If you see errors about unsupported Node features:
# Using nvm:
nvm install 20.19.6
nvm use 20.19.6

# Or download from nodejs.org

​
Next steps

Now that your environment is set up, you’re ready to run your first example:

Quick start guide

Execute your first cross-chain swap from Polygon to Arbitrum

​
Additional resources

Build docs developers (and LLMs) love

Get started for freeTalk to us