Migration Guide - DZap Documentation

Migration Overview

This guide helps you migrate from other DeFi SDKs to DZap SDK or update your existing DZap SDK integration to use the latest features and best practices.

Migration Scenarios

From 1inch SDK

Migrate from 1inch API/SDK to DZap for better routing

From LI.FI SDK

Switch from LI.FI to DZap for enhanced cross-chain features

From 0x API

Upgrade from 0x Protocol to DZap for improved liquidity

DZap SDK v1 to v2

Update to the latest DZap SDK version

Migrating from 1inch SDK

Key Differences

Feature	1inch SDK	DZap SDK
Initialization	API key required	No API key needed
Approval Mode	Standard only	Multiple modes (permits)
Cross-chain	Limited	Native support
Zap Operations	Not supported	Full support

Code Migration

Before (1inch)
After (DZap)

import { OneInchApi } from '@1inch/sdk';

const oneInch = new OneInchApi({
  apiKey: 'your-api-key',
  chainId: 1
});

// Get quote
const quote = await oneInch.getQuote({
  fromTokenAddress: '0xA0b86a33...',
  toTokenAddress: '0xC02aaA39...',
  amount: '1000000'
});

// Approve token
const approvalTx = await oneInch.approve({
  tokenAddress: '0xA0b86a33...',
  amount: '1000000'
});

// Execute swap
const swapTx = await oneInch.swap({
  fromTokenAddress: '0xA0b86a33...',
  toTokenAddress: '0xC02aaA39...',
  amount: '1000000',
  fromAddress: userAddress,
  slippage: 1
});

import { DZapClient, ApprovalModes, Services } from '@dzapio/sdk';
import type { HexString } from '@dzapio/sdk';

const dZap = DZapClient.getInstance();

const quotes = await dZap.getTradeQuotes({
  fromChain: 1,
  data: [{
    amount: '1000000',
    srcToken: '0xA0b86a33...',
    destToken: '0xC02aaA39...',
    toChain: 1,
    slippage: 1
  }],
  account: userAddress
});

const pairKey = Object.keys(quotes)[0];
const source = quotes[pairKey].recommendedSource ?? quotes[pairKey].bestReturnSource;
const bestQuote = quotes[pairKey].quoteRates?.[source];

const tokens = [{ address: '0xA0b86a33...' as HexString, amount: '1000000' }];
const allowanceCheck = await dZap.getAllowance({
  chainId: 1,
  sender: userAddress,
  tokens,
  service: Services.trade,
  mode: ApprovalModes.AutoPermit
});

const data = allowanceCheck.data ?? {};
if (tokens.some((t) => data[t.address]?.approvalNeeded)) {
  await dZap.approve({
    chainId: 1,
    signer,
    sender: userAddress,
    tokens,
    service: Services.trade,
    mode: ApprovalModes.AutoPermit
  });
}

const result = await dZap.trade({
  request: {
    fromChain: 1,
    sender: userAddress,
    refundee: userAddress,
    gasless: false,
    data: [{
      amount: bestQuote.srcAmount,
      srcToken: bestQuote.srcToken.address,
      srcDecimals: bestQuote.srcToken.decimals,
      destToken: bestQuote.destToken.address,
      destDecimals: bestQuote.destToken.decimals,
      toChain: 1,
      protocol: source,
      recipient: userAddress,
      slippage: 1
    }]
  },
  signer
});

Migration Steps

Remove 1inch Dependencies

npm uninstall @1inch/sdk
npm install @dzapio/sdk

Update Imports

// Remove
import { OneInchApi } from "@1inch/sdk";

// Add
import { DZapClient, ApprovalModes } from "@dzapio/sdk";

Update Initialization

// Before
const oneInch = new OneInchApi({ apiKey: "key", chainId: 1 });

// After
const dZap = DZapClient.getInstance();

Update Quote Logic

// Before
const quote = await oneInch.getQuote({
  fromTokenAddress,
  toTokenAddress,
  amount,
});

// After
const quotes = await dZap.getTradeQuotes({
  fromChain: 1,
  data: [{
    amount,
    srcToken: fromTokenAddress,
    destToken: toTokenAddress,
    toChain: 1,
    slippage: 1
  }],
  account: userAddress
});

Migrating from LI.FI SDK

Key Differences

Feature	LI.FI SDK	DZap SDK
Route Structure	Complex multi-step	Simplified routes
Gas Optimization	Basic	Advanced (permits)
Token Management	External	Built-in
Error Handling	Basic	Detailed

Code Migration

Before (LI.FI)
After (DZap)

import { LiFi } from '@lifi/sdk';

const lifi = new LiFi();

// Get routes
const routes = await lifi.getRoutes({
  fromChainId: 1,
  toChainId: 137,
  fromTokenAddress: '0xA0b86a33...',
  toTokenAddress: '0x2791Bca1...',
  fromAmount: '1000000',
  fromAddress: userAddress
});

// Execute route
const execution = await lifi.executeRoute(signer, routes.routes[0]);

import { DZapClient, ApprovalModes, Services } from '@dzapio/sdk';

const dZap = DZapClient.getInstance();

const quotes = await dZap.getTradeQuotes({
  fromChain: 1,
  data: [{
    amount: '1000000',
    srcToken: '0xA0b86a33...',
    destToken: '0x2791Bca1...',
    toChain: 137,
    slippage: 0.5
  }],
  account: userAddress
});

const pairKey = Object.keys(quotes)[0];
const source = quotes[pairKey].recommendedSource ?? quotes[pairKey].bestReturnSource;
const bestQuote = quotes[pairKey].quoteRates?.[source];

const tokens = [{ address: '0xA0b86a33...' as HexString, amount: '1000000' }];
const allowanceCheck = await dZap.getAllowance({
  chainId: 1,
  sender: userAddress,
  tokens,
  service: Services.trade,
  mode: ApprovalModes.AutoPermit
});

const allowanceData = allowanceCheck.data ?? {};
if (tokens.some((t) => allowanceData[t.address]?.approvalNeeded)) {
  await dZap.approve({
    chainId: 1,
    signer,
    sender: userAddress,
    tokens,
    service: Services.trade,
    mode: ApprovalModes.AutoPermit
  });
}

const result = await dZap.trade({
  request: {
    fromChain: 1,
    sender: userAddress,
    refundee: userAddress,
    gasless: false,
    data: [{
      amount: bestQuote.srcAmount,
      srcToken: bestQuote.srcToken.address,
      srcDecimals: bestQuote.srcToken.decimals,
      destToken: bestQuote.destToken.address,
      destDecimals: bestQuote.destToken.decimals,
      toChain: 137,
      protocol: source,
      recipient: userAddress,
      slippage: 0.5
    }]
  },
  signer
});

Migrating from 0x Protocol

Key Differences

Feature	0x Protocol	DZap SDK
API Structure	REST endpoints	TypeScript SDK
Multi-chain	Separate endpoints	Unified interface
Liquidity Sources	0x network	Aggregated sources
Developer Experience	Manual integration	SDK abstraction

Code Migration

Before (0x)
After (DZap)

// Get quote from 0x API
const response = await fetch(
  `https://api.0x.org/swap/v1/quote?sellToken=${fromToken}&buyToken=${toToken}&sellAmount=${amount}`
);
const quote = await response.json();

// Handle approval manually
if (quote.allowanceTarget) {
  const approveTx = {
    to: fromToken,
    data: `0x095ea7b3${quote.allowanceTarget.slice(2).padStart(64, '0')}${amount.toString(16).padStart(64, '0')}`
  };
  await signer.sendTransaction(approveTx);
}

// Execute swap
await signer.sendTransaction({
  to: quote.to,
  data: quote.data,
  value: quote.value
});

import { DZapClient } from '@dzapio/sdk';

const dZap = DZapClient.getInstance();

const quotes = await dZap.getTradeQuotes({
  fromChain: 1,
  data: [{ amount, srcToken: fromToken, destToken: toToken, toChain: 1, slippage: 0.5 }],
  account: userAddress
});
const pairKey = Object.keys(quotes)[0];
const source = quotes[pairKey].recommendedSource ?? quotes[pairKey].bestReturnSource;
const bestQuote = quotes[pairKey].quoteRates?.[source];
const result = await dZap.trade({
  request: {
    fromChain: 1,
    sender: userAddress,
    refundee: userAddress,
    gasless: false,
    data: [{
      amount: bestQuote.srcAmount,
      srcToken: bestQuote.srcToken.address,
      srcDecimals: bestQuote.srcToken.decimals,
      destToken: bestQuote.destToken.address,
      destDecimals: bestQuote.destToken.decimals,
      toChain: 1,
      protocol: source,
      recipient: userAddress,
      slippage: 0.5
    }]
  },
  signer
});

Upgrading DZap SDK v1 to v2

Breaking Changes

DZap SDK v2 introduces several breaking changes. Please test thoroughly before deploying to production.

1. Initialization Changes

import DZap from '@dzapio/sdk';

const dZap = new DZap({
  apiKey: 'your-api-key',
  chainId: 1
});

import { DZapClient } from '@dzapio/sdk';

// Singleton pattern, no configuration needed
const dZap = DZapClient.getInstance();

2. Quote Method Changes

const quote = await dZap.quote({
  from: '0xA0b86a33...',
  to: '0xC02aaA39...',
  amount: '1000000',
  chainId: 1
});

const quotes = await dZap.getTradeQuotes({
  fromChain: 1,
  data: [{
    amount: '1000000',
    srcToken: '0xA0b86a33...',
    destToken: '0xC02aaA39...',
    toChain: 1,
    slippage: 0.5
  }],
  account: userAddress
});

3. Approval System Overhaul

// Manual approval
await dZap.approve({
  token: '0xA0b86a33...',
  amount: '1000000'
});

// Execute swap
await dZap.swap({
  route: quote.route,
  signer
});

const tokens = [{ address: '0xA0b86a33...' as HexString, amount: '1000000' }];
const allowanceCheck = await dZap.getAllowance({
  chainId: 1,
  sender: userAddress,
  tokens,
  service: Services.trade,
  mode: ApprovalModes.AutoPermit
});

const data = allowanceCheck.data ?? {};
if (tokens.some((t) => data[t.address]?.approvalNeeded)) {
  await dZap.approve({ chainId: 1, signer, sender: userAddress, tokens, service: Services.trade, mode: ApprovalModes.AutoPermit });
}
if (tokens.some((t) => data[t.address]?.signatureNeeded)) {
  await dZap.sign({ chainId: 1, sender: userAddress, tokens: tokens.map((t) => ({ address: t.address, amount: t.amount })), signer, service: Services.trade, permitType: PermitTypes.AutoPermit });
}

await dZap.trade({ request: { fromChain: 1, sender: userAddress, refundee: userAddress, gasless: false, data: [...] }, signer });

Migration Checklist

Update Dependencies

npm uninstall @dzapio/sdk@1
npm install @dzapio/sdk@latest

Update Imports

// Old
import DZap from "@dzapio/sdk";

// New
import { DZapClient, ApprovalModes } from "@dzapio/sdk";

Replace Constructor with getInstance()

// Old
const dZap = new DZap(config);

// New
const dZap = DZapClient.getInstance();

Update Quote Method Calls
Implement New Approval System
Update Error Handling
Test All Functionality

Common Migration Issues

Issue 1: Type Errors

// Problem: Old interfaces not compatible
interface OldQuoteRequest {
  from: string;
  to: string;
  amount: string;
}

// Solution: Use TradeQuotesRequest (from @dzapio/sdk)
// request: { fromChain, data: [{ amount, srcToken, destToken, toChain, slippage, srcDecimals?, destDecimals? }], account? }

Issue 2: Approval Flow Breaks

// Problem: v1 approval method not working
// Old way
await dZap.approve({ token, amount });

// Solution: data is keyed by token address; use approvalNeeded
const tokens = [{ address: token as HexString, amount }];
const allowanceCheck = await dZap.getAllowance({
  chainId: 1,
  sender: userAddress,
  tokens,
  service: Services.trade,
  mode: ApprovalModes.AutoPermit,
});
const allowanceData = allowanceCheck.data ?? {};
if (tokens.some((t) => allowanceData[t.address]?.approvalNeeded)) {
  await dZap.approve({
    chainId: 1,
    signer,
    sender: userAddress,
    tokens,
    service: Services.trade,
    mode: ApprovalModes.AutoPermit,
  });
}

Issue 3: Transaction Execution Changes

// Problem: v1 transaction method removed
// Old way
await dZap.swap({ route, signer });

// Solution: Use trade() with TradeBuildTxnRequest (from quote: build data from recommendedSource/bestReturnSource and quoteRates)
await dZap.trade({
  request: {
    fromChain: 1,
    sender: userAddress,
    refundee: userAddress,
    gasless: false,
    data: [{ amount, srcToken, srcDecimals, destToken, destDecimals, toChain, protocol: source, recipient: userAddress, slippage: 0.5 }],
  },
  signer,
});

Testing Your Migration

Create Migration Tests

// migration.test.ts
describe("Migration Tests", () => {
  it("should maintain backward compatibility for common flows", async () => {
    // Test that common v1 workflows still work with v2 equivalent
    const quotes = await dZap.getTradeQuotes({
      fromChain: 1,
      data: [{
        amount: "1000000",
        srcToken: "0xA0b86a33E6441cE4C7c6A3Ec9E3489c4D7a5EFd1",
        destToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        toChain: 1,
        slippage: 0.5
      }],
      account: "0x742d35Cc6A66F4e85c11D8F4D10Cf2D9e37da2b3",
    });

    const pairKeys = Object.keys(quotes);
    expect(pairKeys.length).toBeGreaterThan(0);
    expect(quotes[pairKeys[0]].recommendedSource ?? quotes[pairKeys[0]].bestReturnSource).toBeDefined();
  });

  it("should handle approval migration correctly", async () => {
    const allowanceCheck = await dZap.getAllowance({
      chainId: 1,
      sender: userAddress,
      tokens: [{ address: tokenAddress as HexString, amount: "1000000" }],
      service: Services.trade,
      mode: ApprovalModes.AutoPermit,
    });

    expect(allowanceCheck.status).toBe("success");
    expect(allowanceCheck.data).toBeDefined();
  });
});

Gradual Migration Strategy

Phase 1: Side-by-side Testing
- Run both old and new SDK in parallel
- Compare results and behavior
- Identify discrepancies
Phase 2: Feature Flag Migration
- Use feature flags to gradually enable v2 features
- Monitor performance and errors
- Roll back if issues arise
Phase 3: Complete Migration
- Remove old SDK dependencies
- Clean up legacy code
- Update documentation

Performance Improvements

New Features in v2

Gas Optimization

New permit system reduces gas costs by up to 40%

Better Caching

Improved caching reduces API calls by 60%

Batch Operations

Process multiple operations more efficiently

Error Recovery

Better error handling and automatic retries

Migration Benefits

// Example: Gas savings with v2
const v1GasCost = 150000; // Approval + swap
const v2GasCost = 90000; // Permit + swap

const savings = ((v1GasCost - v2GasCost) / v1GasCost) * 100;
console.log(`Gas savings: ${savings}%`); // ~40% savings

Support and Resources

Getting Help

Migration Support

Join our Discord for migration assistance

Documentation

Complete API reference and guides

Code Examples

Migration examples in our GitHub repo

Video Tutorials

Step-by-step migration tutorials

Community Resources

Discord: Real-time help from our team and community
GitHub Discussions: Technical discussions and Q&A
Blog: Migration tips and best practices
Office Hours: Weekly sessions with our engineers

Next Steps

After completing your migration:

Test Thoroughly: Run full tests in a staging environment
Monitor Performance: Track gas savings and improved user experience
Update Documentation: Ensure your team knows about the new features
Share Feedback: Help us improve by sharing your migration experience

Need personalized migration assistance? Reach out to our team at [email protected] for dedicated migration support.

Getting Started

Trade

Zap

Chains

Tokens

Approval

Reference

Examples

Migration

​Migration Overview

​Migration Scenarios

From 1inch SDK

From LI.FI SDK

From 0x API

DZap SDK v1 to v2

​Migrating from 1inch SDK

​Key Differences

​Code Migration

​Migration Steps

​Migrating from LI.FI SDK

​Key Differences

​Code Migration

​Migrating from 0x Protocol

​Key Differences

​Code Migration

​Upgrading DZap SDK v1 to v2

​Breaking Changes

​1. Initialization Changes

​2. Quote Method Changes

​3. Approval System Overhaul

​Migration Checklist

​Common Migration Issues

​Issue 1: Type Errors

​Issue 2: Approval Flow Breaks

​Issue 3: Transaction Execution Changes

​Testing Your Migration

​Create Migration Tests

​Gradual Migration Strategy

​Performance Improvements

​New Features in v2

Gas Optimization

Better Caching

Batch Operations

Error Recovery

​Migration Benefits

​Support and Resources

​Getting Help

Migration Support

Documentation

Code Examples

Video Tutorials

​Community Resources

​Next Steps

Migration Overview

Migration Scenarios

Migrating from 1inch SDK

Key Differences

Code Migration

Migration Steps

Migrating from LI.FI SDK

Key Differences

Code Migration

Migrating from 0x Protocol

Key Differences

Code Migration

Upgrading DZap SDK v1 to v2

Breaking Changes

1. Initialization Changes

2. Quote Method Changes

3. Approval System Overhaul

Migration Checklist

Common Migration Issues

Issue 1: Type Errors

Issue 2: Approval Flow Breaks

Issue 3: Transaction Execution Changes

Testing Your Migration

Create Migration Tests

Gradual Migration Strategy

Performance Improvements

New Features in v2

Migration Benefits

Support and Resources

Getting Help

Community Resources

Next Steps