@1swap/sdk

Off-chain routing SDK for the 1SWAP DEX aggregator on BNB Chain.

Queries 9 protocols in parallel, finds the best price via direct, split, or multi-hop routing, and returns executionData ready to pass into OneDex.execute() on-chain.

Supported protocols

| Protocol | Type | |---|---| | PancakeSwap V2 | AMM | | Uniswap V2 | AMM | | PancakeSwap V3 / CLMM | Concentrated liquidity | | Uniswap V3 | Concentrated liquidity | | Uniswap V4 | Hook-based AMM | | FourMEME | Bonding curve (V1 + V2, X Mode, ERC20 pairs) | | 1MEME | Bonding curve | | Flapsh | Bonding curve (Portal v5.8.6) |

Install

npm install @1swap/sdk

Quick start

import { createPublicClient, http } from "viem";
import { bsc } from "viem/chains";
import { RouteOptimizer, NATIVE, USDT } from "@1swap/sdk";

const client = createPublicClient({ chain: bsc, transport: http() });
const optimizer = new RouteOptimizer(client);

const route = await optimizer.buildRoute({
  tokenIn:     NATIVE,           // BNB
  tokenOut:    USDT,
  amountIn:    1_000_000_000_000_000_000n,  // 1 BNB in wei
  recipient:   "0xYourWallet",
  slippageBps: 50n,              // 0.5%
});

if (route) {
  console.log("kind:         ", route.kind);          // "direct" | "split" | "multihop"
  console.log("amountOut:    ", route.amountOut);
  console.log("executionData:", route.executionData); // pass to OneDex.execute()
}

Routing strategies

RouteOptimizer.buildRoute() evaluates three strategies in parallel and returns whichever gives the highest output:

Direct

Single-hop through the best available protocol.

Split (kind: "split")

Divides the input across the top-2 AMMs at discrete ratios (80/20 → 20/80). Each partial amount is re-quoted so non-linear price impact is correctly modelled. Only used when it beats the single-protocol output. Bonding-curve protocols are never split.

Example: 1 BNB split 60/40 across PancakeSwap V3 and Uniswap V3

Multi-hop (kind: "multihop")

Routes through up to 3 hops via common intermediate tokens — WBNB, USDT, USDC, BUSD. All candidate paths are evaluated in parallel.

Example: TokenA → USDT → WBNB → TokenB

API

RouteOptimizer

const optimizer = new RouteOptimizer(client: PublicClient);

const route = await optimizer.buildRoute({
  tokenIn:     Address,   // use NATIVE for BNB
  tokenOut:    Address,
  amountIn:    bigint,
  recipient:   Address,
  slippageBps: bigint,    // default 50n (0.5%)
}): Promise<Route | null>

QuoteAggregator

Get all raw quotes sorted best-first without building a full route:

const aggregator = new QuoteAggregator(client);

const quotes = await aggregator.getQuotes(client, {
  tokenIn:  Address,
  tokenOut: Address,
  amountIn: bigint,
}): Promise<Quote[]>

detectToken

Check which protocol a token is currently on:

const result = await detectToken(client, tokenAddress);
// result.bondingCurve  — Protocol | null
// result.graduated     — boolean
// result.ammProtocols  — Protocol[]

Types

type RouteKind = "direct" | "split" | "multihop";

interface Route {
  tokenIn:       Address;
  tokenOut:      Address;
  amountIn:      bigint;
  amountOut:     bigint;
  kind:          RouteKind;
  paths:         SinglePath[];   // 1 path for direct/multihop, 2 for split
  executionData: Hex;            // abi.encode(bool feeOnInput, Step[] steps)
  totalFee:      bigint;
}

interface SinglePath {
  steps:     RouteStep[];  // one entry per protocol hop
  amountIn:  bigint;
  amountOut: bigint;
  splitBps:  bigint;       // fraction of total input (10 000 = 100%)
}

interface RouteStep {
  protocol:  Protocol;
  tokenIn:   Address;
  tokenOut:  Address;
  amountIn:  bigint;
  amountOut: bigint;
}

Using executionData on-chain

IOneDex(0x4283F36F8B7A03513FE5C228c2823a147efF253C).execute{value: amountIn}(
    tokenIn,
    amountIn,
    tokenOut,
    minAmountOut,   // apply your slippage to route.amountOut
    recipient,
    block.timestamp + 300,
    route.executionData
);

For ERC20 inputs approve OneDex before calling:

IERC20(tokenIn).approve(0x4283F36F8B7A03513FE5C228c2823a147efF253C, amountIn);
IOneDex(0x4283F36F8B7A03513FE5C228c2823a147efF253C).execute(..., route.executionData);

Or import the constant:

import { ONEDEX } from "@1swap/sdk";

Constants

All BNB Chain addresses are exported:

import {
  ONEDEX,
  WBNB, USDT, USDC, BUSD, USD1, ONECOIN,
  PANCAKE_V2_ROUTER, PANCAKE_V3_ROUTER,
  UNISWAP_V2_ROUTER, UNISWAP_V3_ROUTER,
  UNISWAP_V4_UNIVERSAL_ROUTER,
  FOURMEME_HELPER3, FOURMEME_TOKEN_MANAGER_V1, FOURMEME_TOKEN_MANAGER_V2,
  ONEMEME_BONDING_CURVE,
  FLAPSH_PORTAL,
  NATIVE,
} from "@1swap/sdk";

Individual adapters

Each protocol adapter can be used directly if you only need a single-protocol quote or step builder:

import { PancakeV3Adapter } from "@1swap/sdk";

const adapter = new PancakeV3Adapter(client);
const quote   = await adapter.getQuote({ tokenIn, tokenOut, amountIn });
const steps   = await adapter.buildSteps({ ...quote, minAmountOut, recipient }, quote);

Available adapters: PancakeV2Adapter, UniswapV2Adapter, PancakeV3Adapter, UniswapV3Adapter, UniswapV4Adapter, FourMemeAdapter, OneMemeAdapter, FlapshAdapter.