Migrate - DZap

A migrate exits one position and enters another in a single zap, a withdraw and a deposit in one. srcToken is the position you’re leaving and destToken the one you’re entering; DZap swaps in between, and bridges when the new position is on another chain, EVM or Solana. Pick EVM or Solana in any tab, and the rest of the page switches with it.

Setup

EVM
Solana

This example moves a Uniswap position on Base into the Uniswap v3 WETH/USDC pool, signing with walletClient, a viem wallet client built from the private key in PRIVATE_KEY. No API key is needed.

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

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

const POOL = '0xd0b53D9277642d899DF5C87A3966A349A798F224';   // Uniswap v3 WETH/USDC 0.05% on Base, the new position

getZapChains lists the provider IDs each chain supports, and getZapPools lists the positions you can enter.

This example moves a Jupiter Lend USDC position on Solana into Kamino’s Steakhouse USDC vault. It signs with the keypair in SOLANA_SECRET_KEY using @solana/web3.js, which you install alongside the SDK, and sends through a Solana RPC connection. No API key is needed.

import { DZapClient, type SVMTxnDetails, type ZapStatusResponse } from '@dzapio/sdk';
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

const dzap = DZapClient.getInstance();
const connection = new Connection('https://api.mainnet-beta.solana.com');
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 VAULT = 'HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E';       // Kamino Steakhouse USDC, the new position

getZapChains lists the provider IDs each chain supports, and getZapPools lists the positions you can enter.

Steps

EVM
Solana

Find the position

getZapPositions lists your open positions with one provider on one chain. Uniswap positions are NFTs, so each carries nftDetails: the NFT’s id and its manager contract.

const { positions } = await dzap.getZapPositions({
  account: account.address,
  chainId: 8453,
  provider: 'uniswap',
});

const position = positions[0];      // the position you're leaving
const nft = position.nftDetails!;   // Uniswap positions are NFTs

Quote

getZapQuote returns the route and the new position you’ll hold. srcToken is the old position, positionDetails.nftId names its NFT, and destToken is the new position; with no amount, the whole position moves. To enter a position on another chain, set destChainId to it and recipient to your address there; the route then bridges in between.

const request = {
  srcChainId: 8453,
  destChainId: 8453,
  account: account.address,
  srcToken: position.address,           // the position you're leaving
  positionDetails: { nftId: nft.id },
  destToken: POOL,                      // the position you're entering
  recipient: account.address,
  refundee: account.address,
  slippage: 1,                          // 1 = 1%
};

const quote = await dzap.getZapQuote(request);
console.log(quote.output[0].asset.symbol, quote.output[0].amountUSD); // the new position and its USD value

The new position is in a concentrated-liquidity pool, so DZap picks a narrow price range for it. Add poolDetails: { lowerTick, upperTick } to the request to set your own, as on the deposit page.

Approve

The zap contract, the quote’s approvalData[0].approveTo, needs permission to move the old position’s NFT. approve() handles NFTs too: pass the NFT’s manager as the token and its id as the amount.

await dzap.approve({
  chainId: 8453,
  signer: walletClient,
  tokens: [{ address: nft.manager, amount: nft.id }],   // an NFT is approved by its id
  service: Services.zap,
  mode: ApprovalModes.Default,
  spender: quote.approvalData[0].approveTo,
});

Leaving an ERC-20 position, such as a vault share or a lending token? Leave out positionDetails, set amount, and approve the token with getAllowance and approve() as on the deposit page.

Build & send

buildZapTxn builds the move and checks it against your wallet, so it throws if it would fail. zap() then signs and sends it: one transaction exits the old position, swaps, and opens the new one for recipient.

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

Status

Poll getZapTxnStatus with the transaction hash until the status leaves PENDING; COMPLETED means every step finished. status.steps reports each leg: the exit, the swap and the deposit, plus the bridge on a cross-chain move. DZap answers 404 until it sees the transaction, and 429 once its rate limit is used up, so the catch skips only those two and rethrows anything else. The loop gives up after 5 minutes (raise it if the route bridges), and the check after it throws unless the status is COMPLETED.

let status: ZapStatusResponse | 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.getZapTxnStatus({ chainId: 8453, txnHash: result.txnHash! });
  } 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'

Find the position

Same call with Solana’s chain ID, 7565164, and your base58 address. A Jupiter Lend position is a token, jlUSDC, so it has no nftDetails.

const { positions } = await dzap.getZapPositions({
  account,
  chainId: 7565164,
  provider: 'jupiterlend',
});

const position = positions[0];      // the position you're leaving

Quote

srcToken is the old position and amount is how much of it to move; position.amount moves all of it. destToken is the new position. There’s nothing to approve on Solana: approvalData comes back empty. To enter a position on another chain, set destChainId to it and recipient to your address there; refundee stays your Solana address.

const request = {
  srcChainId: 7565164,
  destChainId: 7565164,
  account,
  srcToken: position.address,           // the position you're leaving
  amount: position.amount,              // all of it
  destToken: VAULT,                     // the position you're entering
  recipient: account,
  refundee: account,
  slippage: 1,                          // 1 = 1%
};

const quote = await dzap.getZapQuote(request);
console.log(quote.output[0].asset.symbol, quote.output[0].amountUSD); // the new position and its USD value

Build

buildZapTxn builds the move and returns it in route.steps[0].data, where data is a list of base64 transactions. This move needs just one.

const route = await dzap.buildZapTxn(request);
const step = route.steps[0].data as SVMTxnDetails;

Sign & send

Sign the transaction with your keypair and send it through your Solana connection; the signature it returns identifies the transaction. Do it right away: the transaction expires about a minute after it’s built.

const tx = VersionedTransaction.deserialize(Buffer.from(step.data[0], 'base64'));
tx.sign([keypair]);
const signature = await connection.sendRawTransaction(tx.serialize());

Status

Poll getZapTxnStatus with that signature, not the build’s txnId, until the status leaves PENDING. Until DZap sees the transaction it answers 500 Failed to process transaction or 404, and 429 once its rate limit is used up, so the catch skips only those and rethrows anything else. The loop gives up after 5 minutes (raise it if the route bridges), and the check after it throws unless the status is COMPLETED.

let status: ZapStatusResponse | 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.getZapTxnStatus({ chainId: 7565164, txnHash: signature });
  } catch (e: any) {
    if (![404, 429, 500].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 ZapStatusResponse } from '@dzapio/sdk';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

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

const POOL = '0xd0b53D9277642d899DF5C87A3966A349A798F224'; // Uniswap v3 WETH/USDC 0.05% on Base

// 1. Find the position
const { positions } = await dzap.getZapPositions({ account: account.address, chainId: 8453, provider: 'uniswap' });
const position = positions[0];
const nft = position.nftDetails!;

// 2. Quote
const request = {
  srcChainId: 8453,
  destChainId: 8453,
  account: account.address,
  srcToken: position.address,
  positionDetails: { nftId: nft.id },
  destToken: POOL,
  recipient: account.address,
  refundee: account.address,
  slippage: 1,
};
const quote = await dzap.getZapQuote(request);
console.log(quote.output[0].asset.symbol, quote.output[0].amountUSD);

// 3. Approve the old position's NFT (by its id)
await dzap.approve({
  chainId: 8453,
  signer: walletClient,
  tokens: [{ address: nft.manager, amount: nft.id }],
  service: Services.zap,
  mode: ApprovalModes.Default,
  spender: quote.approvalData[0].approveTo,
});

// 4. Build & send
const route = await dzap.buildZapTxn(request);
const result = await dzap.zap({ request, steps: route.steps, signer: walletClient });
if (result.status !== TxnStatus.success) throw new Error(result.errorMsg);

// 5. Status
let status: ZapStatusResponse | 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.getZapTxnStatus({ chainId: 8453, txnHash: result.txnHash! });
  } 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, type SVMTxnDetails, type ZapStatusResponse } from '@dzapio/sdk';
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

const dzap = DZapClient.getInstance();
const connection = new Connection('https://api.mainnet-beta.solana.com');
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 VAULT = 'HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E'; // Kamino Steakhouse USDC

// 1. Find the position
const { positions } = await dzap.getZapPositions({ account, chainId: 7565164, provider: 'jupiterlend' });
const position = positions[0];

// 2. Quote
const request = {
  srcChainId: 7565164,
  destChainId: 7565164,
  account,
  srcToken: position.address,
  amount: position.amount,
  destToken: VAULT,
  recipient: account,
  refundee: account,
  slippage: 1,
};
const quote = await dzap.getZapQuote(request);
console.log(quote.output[0].asset.symbol, quote.output[0].amountUSD);

// 3. Build
const route = await dzap.buildZapTxn(request);
const step = route.steps[0].data as SVMTxnDetails;

// 4. Sign & send
const tx = VersionedTransaction.deserialize(Buffer.from(step.data[0], 'base64'));
tx.sign([keypair]);
const signature = await connection.sendRawTransaction(tx.serialize());

// 5. Status, by signature
let status: ZapStatusResponse | 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.getZapTxnStatus({ chainId: 7565164, txnHash: signature });
  } catch (e: any) {
    if (![404, 429, 500].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, on the zap API at https://zap.dzap.io/v1. Each response wraps its result in data.

EVM
Solana

curl "https://zap.dzap.io/v1/user/positions?account=0xYourWallet&chainId=8453&provider=uniswap"

curl -X POST https://zap.dzap.io/v1/quote \
  -H "Content-Type: application/json" \
  -d '{
    "srcChainId": 8453,
    "destChainId": 8453,
    "account": "0xYourWallet",
    "srcToken": "<position address>",
    "positionDetails": { "nftId": "<nftDetails.id>" },
    "destToken": "0xd0b53D9277642d899DF5C87A3966A349A798F224",
    "recipient": "0xYourWallet",
    "refundee": "0xYourWallet",
    "slippage": 1
  }'

curl -X POST https://zap.dzap.io/v1/buildTx \
  -H "Content-Type: application/json" \
  -d '{
    "srcChainId": 8453,
    "destChainId": 8453,
    "account": "0xYourWallet",
    "srcToken": "<position address>",
    "positionDetails": { "nftId": "<nftDetails.id>" },
    "destToken": "0xd0b53D9277642d899DF5C87A3966A349A798F224",
    "recipient": "0xYourWallet",
    "refundee": "0xYourWallet",
    "slippage": 1
  }'

curl "https://zap.dzap.io/v1/status?chainId=8453&txnHash=0xabc..."

Approve the old position’s NFT for the quote’s approvalData[0].approveTo and wait for it to confirm before building, since the build checks it. Then send the build’s steps[0].data (callTo, callData, value) from your wallet. Full reference: Positions, Quote, Build Tx, Status.

curl "https://zap.dzap.io/v1/user/positions?account=YourSolanaWallet&chainId=7565164&provider=jupiterlend"

curl -X POST https://zap.dzap.io/v1/quote \
  -H "Content-Type: application/json" \
  -d '{
    "srcChainId": 7565164,
    "destChainId": 7565164,
    "account": "YourSolanaWallet",
    "srcToken": "9BEcn9aPEmhSPbPQeFGjidRiEKki46fVQDyPpSQXPA2D",
    "amount": "<position amount>",
    "destToken": "HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E",
    "recipient": "YourSolanaWallet",
    "refundee": "YourSolanaWallet",
    "slippage": 1
  }'

curl -X POST https://zap.dzap.io/v1/buildTx \
  -H "Content-Type: application/json" \
  -d '{
    "srcChainId": 7565164,
    "destChainId": 7565164,
    "account": "YourSolanaWallet",
    "srcToken": "9BEcn9aPEmhSPbPQeFGjidRiEKki46fVQDyPpSQXPA2D",
    "amount": "<position amount>",
    "destToken": "HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E",
    "recipient": "YourSolanaWallet",
    "refundee": "YourSolanaWallet",
    "slippage": 1
  }'

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

The build returns the transaction base64-encoded in steps[0].data.data[0]; sign it and send it through your own Solana RPC, then query status by its signature. Full reference: Positions, Quote, Build Tx, Status.

What can go wrong

NFT id not found: the old position is an NFT and the request has no positionDetails.nftId.
Amount not found or Token amount not found: the old position is a token and the request has no amount.
Route is not supported: DZap has no route between the two positions.
buildZapTxn throws Execution reverted: the build checks the move against your wallet, so the old position’s approval must be confirmed first. The error response’s message has the revert reason.
positions is empty: the wallet has no open position with that provider on that chain. getZapChains lists the provider IDs each chain supports.
Several Solana transactions: some Solana routes return two or more transactions with isJitoTx: true, which have to land together as a Jito bundle. The SDK can’t submit bundles yet, so the code here covers single-transaction routes like this one.
Blockhash not found or ComputationalBudgetExceeded on Solana: the transaction expired before you sent it, or needed more compute than the build allowed. Build and sign again right away.
Not completed: no status: DZap never returned a status, usually because the transaction failed on-chain. On Solana, query by the signature; the build’s txnId returns Failed to process transaction.
HTTP 429: the zap API allows 60 requests a minute.

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