Swap - DZap

Swap one token for another on the same chain. DZap gets quotes from the DEXs and aggregators it supports, recommends a route, and builds the transaction for it. You sign it with your own wallet, then check its status until the swap settles. Pick EVM or Solana in any tab, and the rest of the page switches with it.

Setup

EVM
Solana

This example swaps 100 USDC for WETH on Arbitrum. The SDK signs and sends transactions with walletClient, a viem wallet client built from the private key in the PRIVATE_KEY environment variable. In a browser app, pass the connected wallet’s client instead. No API key is needed.Amounts are whole numbers in the token’s smallest unit, written as strings. USDC has 6 decimals, so 100 USDC is 100000000.

import { DZapClient, Services, ApprovalModes, TxnStatus, type TradeStatusResponse } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const walletClient = createWalletClient({
  account,
  chain: arbitrum,
  transport: http(),
});

const dzap = DZapClient.getInstance();

const USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const WETH = '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1';
const AMOUNT = '100000000';                           // 100 USDC (6 decimals)

This example swaps 100 USDC for SOL. It signs with the keypair in the SOLANA_SECRET_KEY environment variable (the JSON array that solana-keygen saves), using @solana/web3.js, which you install alongside the SDK. No API key is needed.Amounts are whole numbers in the token’s smallest unit, written as strings. USDC has 6 decimals, so 100 USDC is 100000000.

import { DZapClient, TxnStatus, type TradeStatusResponse } from '@dzapio/sdk';
import { Keypair, VersionedTransaction } from '@solana/web3.js';

const dzap = DZapClient.getInstance();
const keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(process.env.SOLANA_SECRET_KEY!)));

const account = keypair.publicKey.toBase58() as `0x${string}`; // SDK types expect hex; base58 works
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const SOL = '11111111111111111111111111111111';                 // native SOL
const AMOUNT = '100000000';                                     // 100 USDC (6 decimals)

Steps

EVM
Solana

Quote

getTradeQuotes asks the DEXs and aggregators DZap supports for a price. The response holds one entry per token pair, read into pair: its quoteRates lists every route that can fill the swap, and recommendedSource names the one DZap recommends. slippage: 1 accepts up to 1% less WETH than quoted; below that, the swap fails.

const quotes = await dzap.getTradeQuotes({
  fromChain: 42161,
  account: account.address,
  data: [{
    srcToken: USDC,
    destToken: WETH,
    amount: AMOUNT,
    toChain: 42161,        // same chain as fromChain = swap
    slippage: 1,           // 1 = 1%
  }],
});

const [pair] = Object.values(quotes);
console.log(pair.quoteRates?.[pair.recommendedSource]?.destAmount); // WETH out, in wei

Approve

The DZap router, the contract that performs the swap, needs your permission to move your USDC. getAllowance reads how much it may spend now; if that’s less than the swap amount, approve() sends an approval for exactly that amount, which costs a little ETH in gas.

const { data } = await dzap.getAllowance({
  chainId: 42161,
  sender: account.address,
  tokens: [{ address: USDC, amount: AMOUNT }],
  service: Services.trade,
  mode: ApprovalModes.Default,
});

if (data[USDC].allowance < BigInt(AMOUNT)) {
  await dzap.approve({
    chainId: 42161,
    signer: walletClient,
    tokens: [{ address: USDC, amount: AMOUNT }],
    service: Services.trade,
    mode: ApprovalModes.Default,
  });
}

Permit2 vs EIP-2612 vs plain approvals, and gasless permit signing, are in Check allowance and Approval mechanisms.

Build & send

trade() asks DZap to build the transaction for the recommended route, then signs it with your wallet and sends it. DZap simulates it first: if it would fail, for example because your USDC balance or allowance is too low, nothing is sent and result says why. recipient gets the WETH and refundee any refund; gasless: false means you pay the gas.

const request = {
  fromChain: 42161,
  sender: account.address,
  refundee: account.address,
  gasless: false,
  data: [{
    srcToken: USDC,
    destToken: WETH,
    amount: AMOUNT,
    toChain: 42161,
    protocol: pair.recommendedSource,
    recipient: account.address,
    slippage: 1,
  }],
};

const result = await dzap.trade({ request, signer: walletClient });
if (result.status !== TxnStatus.success) throw new Error(result.errorMsg);

Status

trade() returns as soon as the transaction is sent, so check getTradeTxnStatus every 15 seconds until the status leaves PENDING; COMPLETED means the swap went through. DZap answers 404 until it has picked up the transaction, and 429 once the keyless limit of 5 requests a minute is used up, so the catch skips only those two and rethrows anything else. The loop gives up after 5 minutes, and the check after it throws unless the status is COMPLETED.

let status: TradeStatusResponse | undefined;
for (let i = 0; i < 20; i++) {  // gives up after 5 minutes
  await new Promise((r) => setTimeout(r, 15_000));
  try {
    status = await dzap.getTradeTxnStatus({ txHash: result.txnHash!, chainId: 42161 });
  } catch (e: any) {
    if (![404, 429].includes(e.response?.status)) throw e;
  }
  if (status && status.status !== 'PENDING') break;
}
if (status?.status !== 'COMPLETED') throw new Error(`Not completed: ${status?.status ?? 'no status'}`);

console.log(status.status); // 'COMPLETED'

Quote

getTradeQuotes asks the DEXs and aggregators DZap supports on Solana (chain ID 7565164 in DZap) for a price. The response holds one entry per token pair, read into pair: its quoteRates lists every route that can fill the swap, and recommendedSource names the one DZap recommends. destAmount is in lamports (1 SOL = 1,000,000,000 lamports), and slippage: 1 accepts up to 1% less SOL than quoted before the swap fails.

const quotes = await dzap.getTradeQuotes({
  fromChain: 7565164,
  account,
  data: [{
    srcToken: USDC,
    destToken: SOL,
    amount: AMOUNT,
    toChain: 7565164,      // same chain as fromChain = swap
    slippage: 1,           // 1 = 1%
  }],
});

const [pair] = Object.values(quotes);
console.log(pair.quoteRates?.[pair.recommendedSource]?.destAmount); // SOL out, in lamports

Build

Solana has no approval step: signing the swap transaction is what lets it move your USDC. buildTradeTxn asks DZap to build the transaction for the recommended route and simulates it first, throwing if it would fail, for example when the wallet has no SOL for fees. It returns the transaction unsigned and base64-encoded, plus a txId for sending it. recipient gets the SOL and refundee any refund.

const built = await dzap.buildTradeTxn({
  fromChain: 7565164,
  sender: account,
  refundee: account,
  gasless: false,
  data: [{
    srcToken: USDC,
    destToken: SOL,
    amount: AMOUNT,
    toChain: 7565164,
    protocol: pair.recommendedSource,
    recipient: account,
    slippage: 1,
  }],
});

Sign & send

Decode the transaction, sign it with your keypair, and hand it to broadcastTradeTx; DZap submits it to the network and returns its transaction ID as txnHash. Do this right away: a Solana transaction is tied to a recent block and expires about a minute after it’s built, so an expired one has to be built again.

const tx = VersionedTransaction.deserialize(Buffer.from(built.data, 'base64'));
tx.sign([keypair]);

const result = await dzap.broadcastTradeTx({
  txId: built.txId,
  chainId: 7565164,
  txData: Buffer.from(tx.serialize()).toString('base64'),
});
if (result.status !== TxnStatus.success) throw new Error(result.message);

Status

broadcastTradeTx returns once the transaction is submitted, so check getTradeTxnStatus with that txnHash every 15 seconds until the status leaves PENDING; COMPLETED means the swap went through. DZap answers 404 until it has picked up the transaction, and 429 once the keyless limit of 5 requests a minute is used up, so the catch skips only those two and rethrows anything else. The loop gives up after 5 minutes, and the check after it throws unless the status is COMPLETED.

let status: TradeStatusResponse | undefined;
for (let i = 0; i < 20; i++) {  // gives up after 5 minutes
  await new Promise((r) => setTimeout(r, 15_000));
  try {
    status = await dzap.getTradeTxnStatus({ txHash: result.txnHash, chainId: 7565164 });
  } catch (e: any) {
    if (![404, 429].includes(e.response?.status)) throw e;
  }
  if (status && status.status !== 'PENDING') break;
}
if (status?.status !== 'COMPLETED') throw new Error(`Not completed: ${status?.status ?? 'no status'}`);

console.log(status.status); // 'COMPLETED'

End-to-end

EVM
Solana

import { DZapClient, Services, ApprovalModes, TxnStatus, type TradeStatusResponse } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({ account, chain: arbitrum, transport: http() });
const dzap = DZapClient.getInstance();

const USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const WETH = '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1';
const AMOUNT = '100000000'; // 100 USDC

// 1. Quote
const quotes = await dzap.getTradeQuotes({
  fromChain: 42161,
  account: account.address,
  data: [{ srcToken: USDC, destToken: WETH, amount: AMOUNT, toChain: 42161, slippage: 1 }],
});
const [pair] = Object.values(quotes);

// 2. Approve (if needed)
const { data } = await dzap.getAllowance({
  chainId: 42161,
  sender: account.address,
  tokens: [{ address: USDC, amount: AMOUNT }],
  service: Services.trade,
  mode: ApprovalModes.Default,
});
if (data[USDC].allowance < BigInt(AMOUNT)) {
  await dzap.approve({
    chainId: 42161,
    signer: walletClient,
    tokens: [{ address: USDC, amount: AMOUNT }],
    service: Services.trade,
    mode: ApprovalModes.Default,
  });
}

// 3. Build + send
const request = {
  fromChain: 42161,
  sender: account.address,
  refundee: account.address,
  gasless: false,
  data: [{ srcToken: USDC, destToken: WETH, amount: AMOUNT, toChain: 42161, protocol: pair.recommendedSource, recipient: account.address, slippage: 1 }],
};
const result = await dzap.trade({ request, signer: walletClient });
if (result.status !== TxnStatus.success) throw new Error(result.errorMsg);

// 4. Status
let status: TradeStatusResponse | undefined;
for (let i = 0; i < 20; i++) {  // gives up after 5 minutes
  await new Promise((r) => setTimeout(r, 15_000));
  try {
    status = await dzap.getTradeTxnStatus({ txHash: result.txnHash!, chainId: 42161 });
  } catch (e: any) {
    if (![404, 429].includes(e.response?.status)) throw e;
  }
  if (status && status.status !== 'PENDING') break;
}
if (status?.status !== 'COMPLETED') throw new Error(`Not completed: ${status?.status ?? 'no status'}`);
console.log('settled:', status.status);

import { DZapClient, TxnStatus, type TradeStatusResponse } from '@dzapio/sdk';
import { Keypair, VersionedTransaction } from '@solana/web3.js';

const dzap = DZapClient.getInstance();
const keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(process.env.SOLANA_SECRET_KEY!)));

const account = keypair.publicKey.toBase58() as `0x${string}`; // SDK types expect hex; base58 works
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const SOL = '11111111111111111111111111111111'; // native SOL
const AMOUNT = '100000000'; // 100 USDC

// 1. Quote
const quotes = await dzap.getTradeQuotes({
  fromChain: 7565164,
  account,
  data: [{ srcToken: USDC, destToken: SOL, amount: AMOUNT, toChain: 7565164, slippage: 1 }],
});
const [pair] = Object.values(quotes);

// 2. Build (no approval on Solana)
const built = await dzap.buildTradeTxn({
  fromChain: 7565164,
  sender: account,
  refundee: account,
  gasless: false,
  data: [{ srcToken: USDC, destToken: SOL, amount: AMOUNT, toChain: 7565164, protocol: pair.recommendedSource, recipient: account, slippage: 1 }],
});

// 3. Sign + broadcast via DZap
const tx = VersionedTransaction.deserialize(Buffer.from(built.data, 'base64'));
tx.sign([keypair]);
const result = await dzap.broadcastTradeTx({
  txId: built.txId,
  chainId: 7565164,
  txData: Buffer.from(tx.serialize()).toString('base64'),
});
if (result.status !== TxnStatus.success) throw new Error(result.message);

// 4. Status
let status: TradeStatusResponse | undefined;
for (let i = 0; i < 20; i++) {  // gives up after 5 minutes
  await new Promise((r) => setTimeout(r, 15_000));
  try {
    status = await dzap.getTradeTxnStatus({ txHash: result.txnHash, chainId: 7565164 });
  } catch (e: any) {
    if (![404, 429].includes(e.response?.status)) throw e;
  }
  if (status && status.status !== 'PENDING') break;
}
if (status?.status !== 'COMPLETED') throw new Error(`Not completed: ${status?.status ?? 'no status'}`);
console.log('settled:', status.status);

API usage

The same flow over REST. Non-EVM chains build a chain-specific transaction you sign locally, then submit via Broadcast.

EVM
Solana

curl -X POST https://api.dzap.io/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 42161,
    "data": [{
      "amount": "100000000",
      "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "destToken": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
      "toChain": 42161,
      "slippage": 1
    }]
  }'

curl -X POST https://api.dzap.io/v1/buildTx \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "0xYourWallet",
    "refundee": "0xYourWallet",
    "fromChain": 42161,
    "gasless": false,
    "data": [{
      "amount": "100000000",
      "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "destToken": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
      "toChain": 42161,
      "protocol": "<recommendedSource from quote>",
      "recipient": "0xYourWallet",
      "slippage": 1
    }]
  }'

curl "https://api.dzap.io/v1/status?txHash=0xabc...&chainId=42161"

Approve the DZap router for the USDC first, then sign and send the transaction from the build response with your own wallet. Full reference: Quote, Build Tx, Status.

curl -X POST https://api.dzap.io/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 7565164,
    "data": [{
      "amount": "100000000",
      "srcToken": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "destToken": "11111111111111111111111111111111",
      "toChain": 7565164,
      "slippage": 1
    }]
  }'

curl -X POST https://api.dzap.io/v1/buildTx \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "YourSolanaWallet",
    "refundee": "YourSolanaWallet",
    "fromChain": 7565164,
    "gasless": false,
    "data": [{
      "amount": "100000000",
      "srcToken": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "destToken": "11111111111111111111111111111111",
      "toChain": 7565164,
      "protocol": "<recommendedSource from quote>",
      "recipient": "YourSolanaWallet",
      "slippage": 1
    }]
  }'

# sign the base64 transaction from the build response, then submit it
curl -X POST https://api.dzap.io/v1/broadcast \
  -H "Content-Type: application/json" \
  -d '{
    "txId": "<txId from build>",
    "chainId": 7565164,
    "txData": "<signed transaction>"
  }'

curl "https://api.dzap.io/v1/status?txHash=<signature>&chainId=7565164"

The build returns a base64 Solana transaction; sign it with your wallet before broadcasting. Full reference: Quote, Build Tx, Broadcast, Status.

What can go wrong

No route: pair.quoteRates is empty; pair.unavailableRoutes says why each provider declined.
The build fails: trade() returns an error and buildTradeTxn throws. The error’s action says what to fix: ADD_FUNDS, INCREASE_ALLOWANCE, or TRY_ANOTHER_ROUTE (quote again).
expired from broadcastTradeTx: build and sign again right away.
Not completed: no status: DZap never returned a status, usually because the transaction failed on-chain. Check the hash in a block explorer.
HTTP 429: without an API key, the trade API allows 5 requests a minute in total, shared by every endpoint, and retryAfter says how many seconds to wait. The status loop skips 429s and polls again.

See Error codes for the full catalog.

​Setup

​Steps

​End-to-end

​API usage

​What can go wrong

Setup

Steps

End-to-end

API usage

What can go wrong