API Integration

Move tokens across chains with the Layerswap API: discover routes, quote, create a swap, execute the deposit, and track it to completion.

Overview

The Layerswap API moves tokens across chains programmatically. The flow is the same for every route: discover a route, request a quote, create a swap, submit one on-chain deposit on the source chain, and Layerswap delivers the funds on the destination chain — then you track the swap to completion.

• Base URL: https://api.layerswap.io
• API key (optional): include your key in the X-LS-APIKEY header to attribute swaps to your account (for analytics and reporting). Create one on the API Keys page.
• Endpoints: every endpoint, with request/response schemas, is in the Endpoints section of this tab — and is linked inline throughout this guide.

Core concepts

Term	Meaning
Network	A blockchain, identified by name (ETHEREUM_MAINNET, ARBITRUM_MAINNET, …). EVM networks also accept their numeric chain_id.
Token	An asset on a network, identified by symbol or contract address. Prefer the contract address — see the warning in step 1.
Route	A supported (source network, source token) → (destination network, destination token) pair.
Quote	The expected output amount, fees, and duration for a given input amount.
Swap	A single cross-chain transfer you create. It moves through a lifecycle from creation to completion.
Deposit action	The exact on-chain transaction to submit on the source chain to fund a swap. Returned with the swap — see Deposit Actions.
Depository	An optional Layerswap contract you can fund through instead of a plain transfer — ideal for smart-contract, server, and programmable wallets. See Depository.

1. Discover routes & tokens

Find which networks and tokens you can bridge between, and the amount limits for a route.

Endpoint	Returns
GET /api/v2/sources	Source networks and their tokens (optionally filtered by destination_network / destination_token)
GET /api/v2/destinations	Destination networks and their tokens (optionally filtered by source_network / source_token)
GET /api/v2/limits	min_amount / max_amount (and their USD values) for a specific route

Each token in the /sources and /destinations response includes symbol, contract, decimals, price_in_usd, status, and group — the token family (e.g. ETH, USDC, USDT) that ties a token’s variants together across networks.

Identify tokens by contract address, not by a hard-coded symbol. A token’s symbol is a display label and can change — Arbitrum’s USDT was renamed to USDT0, so a hard-coded "source_token": "USDT" silently stops matching. The contract address is stable. Either pass the contract address as source_token / destination_token, or fetch the live token list from /sources and resolve by the group field. Don’t hard-code symbols, contract addresses, or decimals — discover them.

const sources = await fetch("https://api.layerswap.io/api/v2/sources", {
  headers: { "X-LS-APIKEY": process.env.LAYERSWAP_API_KEY },
}).then((r) => r.json());

// Resolve the USDT-family token on Arbitrum by its `group`, not its symbol —
// this stays correct even though Arbitrum's USDT is now displayed as USDT0.
const arbitrum = sources.data.find((n) => n.name === "ARBITRUM_MAINNET");
const usdt = arbitrum.tokens.find((t) => t.group === "USDT");

usdt.symbol;   // "USDT0"  → display label, may change
usdt.contract; // "0x..."  → stable identifier, use this as source_token

The full catalog is also browsable at Networks & Tokens.

2. Get a quote

GET /api/v2/quote returns the expected output, fees, and duration for a given amount, without creating a swap — provide the route plus an amount. Example response:

{
  "data": {
    "quote": {
      "receive_amount": 99.5,
      "min_receive_amount": 98.5,
      "total_fee": 0.5,
      "total_fee_in_usd": 0.5,
      "blockchain_fee": 0.15,
      "service_fee": 0.35,
      "avg_completion_time": "00:02:00",
      "rate": 0.995,
      "slippage": 0.5
    }
  }
}

See Fees for how fees are composed.

3. Create the swap

POST /api/v2/swaps creates the swap and returns it together with the deposit_actions you’ll execute next. Choose one funding method:

Funding method	Set	Best for
Direct transfer (default)	neither flag	Simple EOA wallets transferring to the solver
Deposit address	use_deposit_address: true	Exchanges, custodial flows, users sending from anywhere
Depository contract	use_depository: true	Aggregators; smart-contract, server, and programmable wallets — see Depository

use_depository and use_deposit_address are mutually exclusive.

curl -X POST https://api.layerswap.io/api/v2/swaps \
  -H "X-LS-APIKEY: $LAYERSWAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_network": "ARBITRUM_MAINNET",
    "source_token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "destination_network": "BASE_MAINNET",
    "destination_token": "USDC",
    "destination_address": "0xRecipient",
    "amount": 100,
    "use_depository": true
  }'

The response contains the created swap (with its id and status), the quote, and the deposit_actions array.

4. Execute the deposit action

A deposit action is the exact on-chain transaction to submit on the source chain. Read it from the swap response (or re-fetch via GET /api/v2/swaps/{swapId}/deposit_actions):

const action = swap.deposit_actions[0];
// action.to_address, action.amount_in_base_units, action.call_data, action.network, action.token

How you submit it depends on the source chain — the call_data format differs per network (EVM calldata, a Bitcoin OP_RETURN memo, a Solana transaction, etc.). Follow the chain-specific guide:

• Deposit Actions — per-chain execution (EVM, Bitcoin, Solana, Starknet, TON, Tron, Fuel).
• Depository — when you created the swap with use_depository: true.

Submit the returned call_data verbatim. It encodes the swap id and the assigned receiver; altering it means Layerswap can’t match your on-chain deposit to the swap.

After broadcasting, you can optionally speed up matching by reporting the transaction hash to POST /api/v2/swaps/{swapId}/deposit_speedup.

5. Track the transfer

Poll the swap to follow it to completion:

• GET /api/v2/swaps/{swapId} — the swap and its transactions (input = your source deposit, output = the destination delivery).
• GET /api/v2/swaps/by_transaction_hash/{transactionHash} — look up a swap by its source transaction hash.

A typical swap moves user_transfer_pending → ls_transfer_pending → completed. Other terminal states are failed, expired, pending_refund, and refunded. See the Swap Lifecycle for every state and transition, and Refunds for failure handling.

Next steps

Deposit Actions

Execute the deposit on each supported chain.

Depository

Fund a swap by calling our on-chain contract.

Swap Lifecycle

Every swap state and how to react to it.

Fees

How quotes and fees are calculated.