@switch-win/sdk 1.2.9 → 1.3.1

package/dist/types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * Switch DEX Aggregator -- API Response Types
+ *
+ * TypeScript interfaces for all objects returned by the /swap/quote endpoint.
+ * Import these to get full type safety when integrating with the Switch API.
+ *
+ * @example
+ * ```ts
+ * import type { BestPathResponse } from "@switch-win/sdk/types";
+ *
+ * const res = await fetch("https://quote.switch.win/swap/quote?...");
+ * const quote: BestPathResponse = await res.json();
+ * ```
+ */
+/** Full response from `GET /swap/quote` */
+export interface BestPathResponse {
+    /** Input token address */
+    fromToken: string;
+    /** Output token address */
+    toToken: string;
+    /** Recipient address for output tokens. Same as `sender` unless a custom `receiver` was specified. */
+    receiver?: string;
+    /** Total input amount in wei */
+    totalAmountIn: string;
+    /**
+     * Quoted route output in wei before the Switch protocol fee and slippage.
+     * Adapter-native quotes may already include token-tax effects (for example,
+     * the Flap Portal quote).
+     */
+    totalAmountOut: string;
+    /**
+     * Expected output the user will actually receive, in wei.
+     * Accounts for sell tax, protocol fee, and buy tax -- but NOT slippage.
+     *
+     * Use this for UI display of the estimated received amount. For tax tokens,
+     * this is significantly more accurate than applying taxes as linear
+     * multipliers to `totalAmountOut`.
+     */
+    expectedOutputAmount: string;
+    /**
+     * Minimum acceptable output after taxes, fee, and slippage.
+     *
+     * Tax accounting is adapter-specific. Use this API value directly rather
+     * than recomputing it from the reported tax rates. This is encoded in the
+     * `tx` calldata as `_minTotalAmountOut`.
+     */
+    minAmountOut: string;
+    /** Human-readable path descriptions */
+    paths: SwapPath[];
+    /** Human-readable structured route breakdown for display and analytics. */
+    routeAllocation?: RouteAllocationPlan;
+    /** Ready-to-send transaction with fee on **input** (default). Only present when `sender` query param is provided. */
+    tx?: SwapTransaction;
+    /**
+     * Ready-to-send transaction with fee on **output**.
+     * Only present when `sender` query param is provided.
+     *
+     * Use this variant when fee-on-output is preferred (e.g. to collect fees in
+     * the output token). See the README for recommended strategies.
+     */
+    txFeeOnOutput?: SwapTransaction;
+    /** Transaction matching the requested fee mode. Never broadcast this for a gasless order. */
+    selectedTx?: SwapTransaction;
+    protocolFeeBps?: number;
+    feeOnOutput?: boolean;
+    quoteGasPrice?: string;
+    quoteBlockNumber?: number;
+    gaslessExecution?: import("./gasless-types.js").GaslessPreviewResult;
+    /** Conservative server recommendation; normal quotes report not_checked. */
+    gaslessEligibility?: import("./gasless-types.js").GaslessEligibility;
+    /**
+     * Transfer tax info for the input token.
+     * Present when the API detects whether the token has a fee-on-transfer mechanism.
+     */
+    fromTokenTax?: TokenTaxResponse;
+    /**
+     * Transfer tax info for the output token.
+     * Present when the API detects whether the token has a fee-on-transfer mechanism.
+     * If `toTokenTax.isTaxToken` is true, `minAmountOut` already accounts for the buy tax.
+     */
+    toTokenTax?: TokenTaxResponse;
+    /**
+     * Effective slippage in basis points = user slippage + sell tax + buy tax + auto-liq buffer.
+     *
+     * For example, if a user requests 50 bps (0.5%) slippage but the input token has
+     * a 120 bps (1.2%) sell tax, effectiveSlippageBps = 170.
+     *
+     * Display this in your UI so users understand the total tolerance applied.
+     */
+    effectiveSlippageBps: number;
+    /**
+     * Human-readable effective slippage percentage.
+     *
+     * Examples: `"0.5"` (no tax), `"1.7"` (0.5% user + 1.2% sell tax), `"4.5"` (0.5% + 2% sell + 2% buy).
+     */
+    effectiveSlippagePercent: string;
+}
+/** Transfer tax information for a token (fee-on-transfer) */
+export interface TokenTaxResponse {
+    /** Whether this token has a transfer tax */
+    isTaxToken: boolean;
+    /**
+     * Buy tax in basis points.
+     * Applied when the token is acquired (i.e. when it is the output token).
+     * For example, 500 = 5% buy tax.
+     */
+    buyTaxBps: number;
+    /**
+     * Sell tax in basis points.
+     * Applied when the token is sold (i.e. when it is the input token).
+     * For example, 500 = 5% sell tax.
+     */
+    sellTaxBps: number;
+}
+/** Transaction object ready to be sent on-chain via `signer.sendTransaction()` */
+export interface SwapTransaction {
+    /** SwitchRouter contract address */
+    to: string;
+    /** ABI-encoded `goSwitch()` calldata */
+    data: string;
+    /** Native currency to send (wei). `"0"` for ERC-20 input tokens. */
+    value: string;
+}
+/**
+ * Human-readable summary of a single route split.
+ * Useful for UI display (e.g. "60% via PulseX, 40% via 9inch").
+ */
+export interface SwapPath {
+    /** Human-readable DEX adapter name (e.g. `"PulseXV2"`, `"UniswapV3"`, `"9inchV2"`) */
+    adapter: string;
+    /** Input amount for this path (wei) */
+    amountIn: string;
+    /** Expected output for this path (wei) */
+    amountOut: string;
+    /** Ordered list of token addresses traversed (e.g. `[tokenIn, intermediate, tokenOut]`) */
+    path: string[];
+    /** Human-readable adapter names used at each hop */
+    adapters: string[];
+    /** Percentage of total input routed through this path */
+    percentage?: number;
+    /** Detailed breakdown of each hop-leg in this path */
+    legs?: SwapPathLeg[];
+}
+/** A single leg within a swap path */
+export interface SwapPathLeg {
+    /** Leg input token */
+    tokenIn: string;
+    /** Leg output token */
+    tokenOut: string;
+    /** Human-readable DEX adapter name */
+    adapter?: string;
+    /** Input amount (wei) */
+    amountIn: string;
+    /** Output amount (wei) */
+    amountOut: string;
+    /** Percentage of the hop routed through this adapter */
+    percentage?: number;
+}
+/** Top-level route allocation plan */
+export interface RouteAllocationPlan {
+    /** Total input in wei */
+    amountIn: string;
+    /** Total expected output in wei */
+    totalAmountOut: string;
+    /** Array of split routes */
+    routes: SingleRouteAllocation[];
+}
+/** A single route within the split */
+export interface SingleRouteAllocation {
+    /** Input amount for this route portion (wei) */
+    amountIn: string;
+    /** Sequential hops in this route */
+    hops: HopAllocationPlan[];
+}
+/** A single hop within a route */
+export interface HopAllocationPlan {
+    /** Hop input token */
+    tokenIn: string;
+    /** Hop output token */
+    tokenOut: string;
+    /** Total output from all legs in this hop (wei) */
+    totalAmountOut: string;
+    /** Adapter legs executing this hop (can be split across DEXes) */
+    legs: HopAdapterAllocationPlan[];
+}
+/** A single adapter leg within a hop */
+export interface HopAdapterAllocationPlan {
+    /** Human-readable DEX adapter name */
+    adapter: string;
+    /** Input amount routed through this adapter (wei) */
+    amountIn: string;
+    /** Expected output from this adapter (wei) */
+    amountOut: string;
+    /** V3 fee tier or concentrated-liquidity tick-spacing hint. Zero for adapters that do not use it. */
+    fee?: number;
+}
+/** Error response returned when the API encounters a problem */
+export interface ErrorResponse {
+    error: string;
+}
+/** The quote endpoint returns either a successful response or an error */
+export type QuoteResponse = BestPathResponse | ErrorResponse;
+/** Type guard to check if a response is an error */
+export declare function isErrorResponse(response: QuoteResponse): response is ErrorResponse;
+/** A single adapter (DEX) returned by `GET /swap/adapters` */
+export interface AdapterInfo {
+    /** On-chain adapter index (used in the `adapters` query param for `/swap/quote`) */
+    index: number;
+    /** Human-readable DEX name (e.g. `"PulseXV2"`, `"UniswapV3"`, `"9inchV2"`) */
+    name: string;
+    /** On-chain adapter contract address */
+    address: string;
+}
+/** Response from `GET /swap/adapters` */
+export interface AdaptersResponse {
+    adapters: AdapterInfo[];
+}
+/** Response from `GET /swap/checkTax` */
+export interface CheckTaxResponse {
+    /** Lowercased token address that was checked */
+    token: string;
+    /** Whether this token has a non-zero transfer tax */
+    isTaxToken: boolean;
+    /** Buy tax in basis points (applied when the token is the output) */
+    buyTaxBps: number;
+    /** Sell tax in basis points (applied when the token is the input) */
+    sellTaxBps: number;
+}
+/** Type guard for CheckTaxResponse errors */
+export type CheckTaxResult = CheckTaxResponse | ErrorResponse;
+/**
+ * Parameters for a limit order — the fields the maker signs via EIP-712.
+ *
+ * All amounts are raw integer strings in wei (same convention as swap quotes).
+ * The `nonce` MUST be unique per maker — once used (filled or cancelled) it
+ * cannot be reused.
+ */
+export interface LimitOrderParams {
+    /** Maker (signer) address */
+    maker: string;
+    /** Input token address (token the maker is selling) */
+    tokenIn: string;
+    /** Output token address (token the maker wants to receive) */
+    tokenOut: string;
+    /** Amount of tokenIn the maker is offering (wei) */
+    amountIn: string;
+    /** Minimum amount of tokenOut the maker will accept (wei) */
+    minAmountOut: string;
+    /**
+     * Unix timestamp after which the order expires. Set to `0` for no expiry.
+     * The contract will revert with `OrderExpired()` if `block.timestamp > deadline` (when > 0).
+     */
+    deadline: number;
+    /**
+     * Unique nonce per maker. Once a nonce is used (filled or cancelled on-chain),
+     * it cannot be reused. Use `Date.now()` or a random integer for uniqueness.
+     */
+    nonce: number;
+    /**
+     * If `true`, the contract fee is deducted from the output (tokenOut) instead
+     * of the input (tokenIn). Same concept as swap fee modes.
+     */
+    feeOnOutput: boolean;
+    /**
+     * Address that receives the output tokens. Defaults to the maker if set
+     * to the zero address (`0x0000…`).
+     */
+    recipient: string;
+    /**
+     * If `true` and tokenOut is WPLS, the contract unwraps to native PLS
+     * before sending to the recipient.
+     */
+    unwrapOutput: boolean;
+    /**
+     * Partner address to receive 50% of protocol fees.
+     * Use the zero address (`0x0000…`) for no partner.
+     */
+    partnerAddress: string;
+}
+/**
+ * A signed limit order — the order parameters plus the EIP-712 signature.
+ * This is what gets submitted to the Switch backend via `POST /limit-orders`.
+ */
+export interface SignedLimitOrder extends LimitOrderParams {
+    /** EIP-712 signature of the order struct, produced by the maker's wallet */
+    signature: string;
+    /**
+     * SwitchLimitOrder deployment used in the EIP-712 domain.
+     * Include this when submitting Robinhood orders or orders signed against an
+     * older supported deployment so the backend verifies the correct domain.
+     */
+    limitOrderContract?: string;
+}
+/** Body for `POST /limit-orders` */
+export type CreateLimitOrderRequest = SignedLimitOrder;
+/** @deprecated Current hosted API cancellation is on-chain only. */
+export interface CancelLimitOrderRequest {
+    /** Maker address */
+    maker: string;
+    /** Nonce of the order to cancel */
+    nonce: number;
+}
+/** Order status in the backend database */
+export type LimitOrderStatus = "ACTIVE" | "FILLED" | "CANCELLED" | "EXPIRED";
+/**
+ * A limit order record as returned by the Switch backend API.
+ *
+ * Includes all order parameters plus metadata fields added by the backend.
+ */
+export interface LimitOrderRecord {
+    /** Unique database ID (cuid) */
+    id: string;
+    /** Maker address (lowercased) */
+    maker: string;
+    /** Recipient address (lowercased) */
+    recipient: string;
+    /** Input token address (lowercased) */
+    tokenIn: string;
+    /** Output token address (lowercased) */
+    tokenOut: string;
+    /** Input amount in wei */
+    amountIn: string;
+    /** Minimum output amount in wei */
+    minAmountOut: string;
+    /** Expiry timestamp (0 = no expiry) */
+    deadline: number;
+    /** Unique nonce for this maker */
+    nonce: number;
+    /** Fee mode flag */
+    feeOnOutput: boolean;
+    /** Unwrap wrapped-native output to PLS/ETH on the selected network */
+    unwrapOutput: boolean;
+    /** Partner address for fee sharing */
+    partnerAddress: string;
+    /** LO contract address this order targets for cancellation/fill */
+    limitOrderContract?: string;
+    /** EIP-712 signature */
+    signature: string;
+    /** Pair key in format `tokenIn:tokenOut` (lowercased) */
+    pairKey: string;
+    /** Sell tax on input token in basis points, when known */
+    tokenInSellTaxBps?: number;
+    /** Buy tax on input token in basis points, when known */
+    tokenInBuyTaxBps?: number;
+    /** Sell tax on output token in basis points, when known */
+    tokenOutSellTaxBps?: number;
+    /** Buy tax on output token in basis points, when known */
+    tokenOutBuyTaxBps?: number;
+    /** Current order status */
+    status: LimitOrderStatus;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** ISO 8601 last update timestamp */
+    updatedAt: string;
+    /** Filler address for filled orders */
+    filler?: string | null;
+    /** Filler profit in tokenIn units for filled orders */
+    fillerProfit?: string | null;
+    /** Block number where the order was filled (if status is FILLED) */
+    filledBlock?: number | null;
+    /** Transaction hash of the fill (if status is FILLED) */
+    filledTxHash?: string | null;
+}
+/** Response from `POST /limit-orders` (success) */
+export interface CreateLimitOrderResponse {
+    success: true;
+    order: LimitOrderRecord;
+}
+/** @deprecated Current hosted API cancellation is on-chain only. */
+export interface CancelLimitOrderResponse {
+    success: true;
+}
+/** Response from `GET /limit-orders` */
+export interface ListLimitOrdersResponse {
+    /** Total matching orders */
+    total: number;
+    /** Page size used */
+    limit: number;
+    /** Page offset used */
+    offset: number;
+    /** Array of order records */
+    orders: LimitOrderRecord[];
+}
+/** Response from `GET /limit-orders/pairs` */
+export interface LimitOrderPair {
+    /** Pair key in format `tokenIn:tokenOut` */
+    pairKey: string;
+    /** Input token address */
+    tokenIn: string;
+    /** Output token address */
+    tokenOut: string;
+    /** Number of active orders for this pair */
+    activeOrders: number;
+}
+/** Response from `GET /limit-orders/stats` */
+export interface LimitOrderStats {
+    active: number;
+    filled: number;
+    cancelled: number;
+    expired: number;
+    total: number;
+}
+/** Response from `GET /limit-orders/config`. */
+export interface LimitOrderConfigResponse {
+    limitOrderContract: string;
+    limitOrderRouter?: string | null;
+    gaslessContract?: string | null;
+    gaslessSettlementVersion?: number;
+    gaslessTaxTokensSupported?: boolean;
+    gaslessApprovalSpender?: string | null;
+    gaslessProtocolFeeBps?: number;
+    gaslessMaxOperatorPayoutBps?: number;
+    gaslessEip712Domain?: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: string;
+    } | null;
+    orderSubmissionLimitOrderContracts?: string[];
+    otcRoutingLimitOrderContracts?: string[];
+    deprecatedLimitOrderContracts?: string[];
+    allLimitOrderContracts: string[];
+    plsFlowContract: string | null;
+    allPlsFlowContracts: string[];
+    limitOrderContractVersions: Record<string, string>;
+    plsFlowContractVersions: Record<string, string>;
+    eip712Domain: {
+        name: "SwitchLimitOrder";
+        version: "2";
+        chainId: number;
+        verifyingContract: string;
+    };
+}
+/** Union type for limit order mutation responses */
+export type LimitOrderMutationResponse = CreateLimitOrderResponse | CancelLimitOrderResponse | ErrorResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Switch DEX Aggregator -- API Response Types
+ *
+ * TypeScript interfaces for all objects returned by the /swap/quote endpoint.
+ * Import these to get full type safety when integrating with the Switch API.
+ *
+ * @example
+ * ```ts
+ * import type { BestPathResponse } from "@switch-win/sdk/types";
+ *
+ * const res = await fetch("https://quote.switch.win/swap/quote?...");
+ * const quote: BestPathResponse = await res.json();
+ * ```
+ */
+/** Type guard to check if a response is an error */
+export function isErrorResponse(response) {
+    return "error" in response;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmNH,oDAAoD;AACpD,MAAM,UAAU,eAAe,CAC7B,QAAuB;IAEvB,OAAO,OAAO,IAAI,QAAQ,CAAC;AAC7B,CAAC"}

package/examples/gasless-nextjs-proxy.ts

@@ -0,0 +1,87 @@
+/** app/api/switch/[...path]/route.ts. Use your normal origin/session checks and rate limits. */
+const READ_PATHS = new Set([
+  "swap/quote",
+  "swap/checkTax",
+  "limit-orders",
+  "limit-orders/config",
+]);
+const STATUS_PATH = /^limit-orders\/0x[\da-f]{40}\/\d{1,16}$/i;
+
+export async function proxySwitch(
+  request: Request,
+  path: string[],
+  apiKey: string,
+): Promise<Response> {
+  if (!apiKey)
+    return Response.json(
+      { error: "Switch proxy is not configured" },
+      { status: 500 },
+    );
+  const route = path.join("/");
+  const read =
+    request.method === "GET" &&
+    (READ_PATHS.has(route) || STATUS_PATH.test(route));
+  const submit = request.method === "POST" && route === "limit-orders";
+  if (!read && !submit)
+    return Response.json({ error: "Unsupported route" }, { status: 404 });
+  const incoming = new URL(request.url);
+  if (
+    !["pulsechain", "robinhood"].includes(
+      incoming.searchParams.get("network") ?? "",
+    )
+  )
+    return Response.json(
+      { error: "Select a supported network" },
+      { status: 400 },
+    );
+  const upstream = new URL(`https://quote.switch.win/${route}`);
+  incoming.searchParams.forEach((value, key) =>
+    upstream.searchParams.set(key, value),
+  );
+  let body: string | undefined;
+  if (submit) {
+    // Enforce a body limit at your hosting/server layer as well.
+    body = await request.text();
+    if (body.length > 16384)
+      return Response.json({ error: "Order body too large" }, { status: 413 });
+  }
+  try {
+    const response = await fetch(upstream, {
+      method: request.method,
+      body,
+      cache: "no-store",
+      headers: {
+        "x-api-key": apiKey,
+        ...(submit ? { "Content-Type": "application/json" } : {}),
+      },
+      signal: AbortSignal.any([
+        request.signal,
+        AbortSignal.timeout(submit ? 20000 : 60000),
+      ]),
+    });
+    return new Response(await response.text(), {
+      status: response.status,
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store, max-age=0",
+      },
+    });
+  } catch {
+    // A 502 on POST is uncertain: it does not mean the upstream rejected the order.
+    return Response.json(
+      {
+        error: submit
+          ? "Submission status uncertain; check the saved order"
+          : "Switch API unavailable",
+      },
+      { status: 502 },
+    );
+  }
+}
+
+// App Router wrappers (adapt params to your installed Next.js version):
+// export async function GET(request, context) {
+//   return proxySwitch(request, (await context.params).path, process.env.SWITCH_API_KEY!);
+// }
+// export const POST = GET;
+// Keep SWITCH_API_KEY server-side. A status timeout must retain the maker's pending lock.

package/examples/gasless-operator.ts

@@ -0,0 +1,76 @@
+import { Contract, type Provider } from "ethers";
+import {
+  GASLESS_SWITCH_ABI,
+  assertGaslessOperator,
+  assessGaslessOperatorProfit,
+  encodeGaslessFill,
+  gaslessGasBudget,
+  type GaslessDeployment,
+  type GaslessOrder,
+  type GaslessRoute,
+} from "../src/gasless-index.js";
+
+/** Validate an execution proposal from your routing engine. Does not broadcast. */
+export async function checkGaslessExecution(input: {
+  provider: Provider;
+  deployment: GaslessDeployment;
+  operator: string;
+  order: GaslessOrder;
+  signature: string;
+  routes: GaslessRoute[];
+  receivedInput?: string;
+  quoteGasPriceWei: bigint;
+  /** Obtained by tracing the exact fill: actual after-tax payout converted to native. */
+  valueActualPayoutNative(call: {
+    to: string;
+    data: string;
+    value: string;
+    from: string;
+    gasPrice: bigint;
+  }): Promise<bigint>;
+}) {
+  await assertGaslessOperator(input.provider, input.deployment, input.operator);
+  const block = await input.provider.getBlock("latest");
+  if (!block) throw Error("Current chain block unavailable");
+  const call = encodeGaslessFill({ ...input, chainTimestamp: block.timestamp });
+  const settlement = new Contract(
+    input.deployment.contract,
+    GASLESS_SWITCH_ABI,
+    input.provider,
+  );
+  // Necessary signature/balance/nonce checks, not a profitability assertion.
+  if (!(await settlement.canFillOrder(input.order, input.signature)))
+    return {
+      eligible: false as const,
+      reason: "Order is not currently fillable",
+    };
+  const rawPrice = (await input.provider.getFeeData()).gasPrice;
+  if (!rawPrice) throw Error("Current gas price unavailable");
+  const initial = gaslessGasBudget(1n, rawPrice, input.quoteGasPriceWei);
+  const transaction = {
+    ...call,
+    from: input.operator,
+    gasPrice: initial.gasPrice,
+  };
+  const estimate = await input.provider.estimateGas(transaction);
+  const budget = gaslessGasBudget(estimate, rawPrice, input.quoteGasPriceWei);
+  const measuredPayout = await input.valueActualPayoutNative(transaction);
+  const profit = assessGaslessOperatorProfit(
+    measuredPayout,
+    budget.gasLimit,
+    budget.gasPrice,
+  );
+  // Operators can reserve further headroom, but never increase the contract cap.
+  if (!profit.eligible || measuredPayout <= budget.gasBudgetNative)
+    return {
+      eligible: false as const,
+      reason: "Payout does not cover padded gas",
+    };
+  await input.provider.call({ ...transaction, gasLimit: budget.gasLimit });
+  // Recheck deadline/nonce/role/gas immediately before using this proposal; serialize wallet nonces.
+  return {
+    eligible: true as const,
+    transaction: { ...transaction, gasLimit: budget.gasLimit },
+    profit,
+  };
+}