Swap tokens and bridge assets

What you’ll build

Swap quotes from multiple liquidity sources in a single call
Ready-to-sign approve and swap transactions, with no separate quote and execute steps
Cross-chain bridges (EVM ↔ EVM, EVM ↔ Solana)

Time

~15 minutes

You need

A Zerion API key
A wallet address with tokens to swap

Endpoints

GET/v1/swap/quotes/

How it works

Most swap APIs split quoting and executing into separate endpoints. Zerion API does both in a single call:

Call GET /v1/swap/quotes/ with the sender, recipient, input asset, output asset and amount.
Receive multiple quotes. Each includes the expected output, fees and, when executable, ready-to-sign transaction_approve and transaction_swap payloads.
Pick a quote and sign the transactions with your wallet.

Quotes come back best-first, sorted by the fiat value of output_amount_after_fees.

Steps

Get swap quotes

Request quotes from swap and bridge quotes.

const API_KEY = process.env.ZERION_API_KEY;
const headers = {
  accept: "application/json",
  authorization: `Basic ${btoa(API_KEY + ":")}`,
};

// Swap 0.05 ETH → DAI on Ethereum
const wallet = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";
const params = new URLSearchParams({
  from: wallet,
  to: wallet,
  "input[chain_id]": "ethereum",
  "input[fungible_id]": "eth",
  "input[amount]": "0.05", // human-readable decimal, not wei
  "output[fungible_id]": "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
});

const response = await fetch(
  `https://api.zerion.io/v1/swap/quotes/?${params}`,
  { headers }
);
const { data } = await response.json();

for (const quote of data) {
  const {
    liquidity_source,
    output_amount,
    minimum_output_amount,
    output_amount_after_fees,
    network_fee,
    error,
  } = quote.attributes;
  console.log(`\nQuote from ${liquidity_source.name}:`);
  console.log(`  Output:         ${output_amount.quantity}`);
  console.log(`  Min after slip: ${minimum_output_amount.quantity}`);
  console.log(`  Net of fees:    ${output_amount_after_fees.value} ${output_amount_after_fees.currency ?? ""}`);
  console.log(`  Network fee:    ${network_fee?.amount?.value ?? "n/a"}`);
  if (error) console.log(`  ⚠️  ${error.code}: ${error.message ?? error.hint}`);
}

import os, requests

api_key = os.environ["ZERION_API_KEY"]
wallet = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"

# Swap 0.05 ETH → DAI on Ethereum
response = requests.get(
    "https://api.zerion.io/v1/swap/quotes/",
    params={
        "from": wallet,
        "to": wallet,
        "input[chain_id]": "ethereum",
        "input[fungible_id]": "eth",
        "input[amount]": "0.05",  # human-readable decimal, not wei
        "output[fungible_id]": "0x6B175474E89094C44Da98b954EedeAC495271d0F",  # DAI
    },
    auth=(api_key, ""),
)

for quote in response.json()["data"]:
    attrs = quote["attributes"]
    print(f"\nQuote from {attrs['liquidity_source']['name']}:")
    print(f"  Output:         {attrs['output_amount']['quantity']}")
    print(f"  Min after slip: {attrs['minimum_output_amount']['quantity']}")
    after_fees = attrs["output_amount_after_fees"]
    print(f"  Net of fees:    {after_fees.get('value')} {after_fees.get('currency', '')}")
    if "error" in attrs:
        err = attrs["error"]
        print(f"  Note: {err['code']} - {err.get('message') or err['hint']}")

curl -g -u "YOUR_API_KEY:" \
  "https://api.zerion.io/v1/swap/quotes/?from=0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B&to=0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B&input[chain_id]=ethereum&input[fungible_id]=eth&input[amount]=0.05&output[fungible_id]=0x6B175474E89094C44Da98b954EedeAC495271d0F"

What each quote contains

liquidity_source - Provider id, display name and icon.
input_amount / output_amount - What you send and the estimated amount you receive before slippage. quantity is the human-readable decimal; value / usd_value are fiat conversions when available.
minimum_output_amount - Guaranteed output after slippage.
output_amount_after_fees - Net output once protocol, bridge and network fees are subtracted. Quotes are ranked by this field.
slippage_percent - Slippage actually applied: the slippage_percent query parameter when provided, otherwise auto-chosen.
protocol_fee / bridge_fee / network_fee - Fee breakdown. Each carries amount and an included_in_rate flag (whether it’s already deducted from the rate).
transaction_approve - ERC-20 approve transaction to sign first. Absent when not needed (Solana, EVM native-asset input, or sufficient allowance already granted).
transaction_swap - Swap transaction to sign. Absent when the quote is informational only (e.g., error is set).
error - Present when the quote can’t be executed as-is (e.g., not_enough_input_asset_balance).
estimated_time_seconds - Typically present on bridge routes.

Pick a quote and check for errors

Quotes are sorted best-first. Before signing, check that the chosen quote has no error and does have a transaction_swap.

const quote = data[0]; // best by output_amount_after_fees
const { error, transaction_approve, transaction_swap } = quote.attributes;

if (error) {
  console.log(`Cannot execute: ${error.code} (hint: ${error.hint})`);
  process.exit(1);
}
if (!transaction_swap) {
  console.log("No transaction payload - informational quote only");
  process.exit(1);
}

error.hint is a machine-readable next step (topup, add_wallet, unspecified) you can surface in your UI to guide the user.

Sign the approve transaction (if present)

If transaction_approve is present, sign and confirm it before submitting the swap. It’s a complete EVM transaction, so you don’t need a manual approve(spender, amount) call.

import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

async function sendEVM(payload) {
  // EVM numeric fields are hex strings - ethers accepts them directly
  const tx = await signer.sendTransaction({
    type: parseInt(payload.type, 16),
    to: payload.to,
    data: payload.data,
    value: payload.value,
    gasLimit: payload.gas,
    nonce: parseInt(payload.nonce, 16),
    chainId: parseInt(payload.chain_id, 16),
    ...(payload.max_fee
      ? { maxFeePerGas: payload.max_fee, maxPriorityFeePerGas: payload.max_priority_fee }
      : { gasPrice: payload.gas_price }),
  });
  return tx.wait();
}

if (transaction_approve?.evm) {
  console.log("Sending approval...");
  await sendEVM(transaction_approve.evm);
  console.log("Approval confirmed");
}

transaction_approve is omitted for Solana, for EVM swaps where the input is the chain’s native asset (ETH, MATIC, etc.), and when the wallet already has sufficient allowance.

Sign and send the swap transaction

const receipt = await sendEVM(transaction_swap.evm);
console.log(`Confirmed in block ${receipt.blockNumber}`);

For Solana quotes, transaction_swap.solana.raw is a base64-encoded raw transaction. Decode it and sign it with the Solana wallet of your choice (for example, @solana/web3.js).

Bridge assets across chains

To bridge, set a different output[chain_id]. to is the recipient on the destination chain: set it to your wallet on that chain, and use a base58 Solana address when bridging to Solana.

# Bridge 1 USDC from Ethereum to Polygon
curl -g -u "YOUR_API_KEY:" \
  "https://api.zerion.io/v1/swap/quotes/?from=YOUR_WALLET&to=YOUR_WALLET&input[chain_id]=ethereum&input[fungible_id]=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&input[amount]=1&output[chain_id]=polygon&output[fungible_id]=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"

Use the List fungibles available for bridging endpoint to discover which tokens can be bridged between two specific chains before requesting quotes.

Key parameters

Parameter	Description
`from`	Wallet performing the swap. Must match the chain type of `input[chain_id]` (EVM hex or Solana base58). Required.
`to`	Recipient of the output asset. Must match the chain type of `output[chain_id]`. For a same-chain swap to the same wallet, set equal to `from`. Required.
`input[chain_id]`	Source chain (e.g., `ethereum`, `polygon`, `solana`). Required.
`input[fungible_id]`	Input asset’s fungible ID - either a Zerion fungible ID (e.g., `eth`) or the token contract address. Required.
`input[amount]`	Human-readable input amount as a decimal string (e.g., `"0.05"`), not the smallest unit. Required.
`output[chain_id]`	Destination chain. Defaults to `input[chain_id]` (same-chain swap).
`output[fungible_id]`	Output asset’s fungible ID or token contract address. Required.
`slippage_percent`	Maximum acceptable slippage in percent. Auto-chosen when omitted.
`currency`	Currency for fiat values in the response (e.g., `usd`). Defaults to `usd`.

Next steps

Check balances before quoting, so you only request quotes the wallet can cover.
After the swap confirms, show it in the wallet’s transaction history.

Build a multi-chain portfolio tracker Total value, holdings and charts across chains. Portfolio Get a wallet’s transaction history Human-readable transaction types, transfers and fees. Transactions

​How it works

​Steps

​Key parameters

​Next steps

How it works

Steps

Key parameters

Next steps