@switch-win/sdk 1.0.0

package/src/types.ts

@@ -0,0 +1,423 @@
+/**
+ * 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();
+ * ```
+ */
+
+// -- Top-level response --
+
+/** 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;
+  /**
+   * Raw DEX output in wei -- reflects price impact only.
+   * This is the amount the pools would return before any taxes, fees, or slippage are applied.
+   */
+  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.
+   *
+   * Calculated as:
+   * `totalAmountOut -- (1 -- sellTax) -- (1 -- fee) -- (1 -- buyTax) -- (1 -- slippage)`
+   *
+   * This is the value encoded in the `tx` calldata as `_minTotalAmountOut`.
+   */
+  minAmountOut: string;
+  /** Human-readable path descriptions */
+  paths: SwapPath[];
+  /** Structured route breakdown (matches on-chain structs) */
+  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;
+  /**
+   * 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 (on-chain) --
+
+/** 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 PLS to send (wei). `"0"` for ERC-20 input tokens. */
+  value: string;
+}
+
+// -- Human-readable paths --
+
+/**
+ * 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;
+}
+
+// -- Route allocation (matches on-chain structs) --
+
+/** 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 {
+  /** DEX adapter contract address */
+  adapter: string;
+  /** Input amount routed through this adapter (wei) */
+  amountIn: string;
+  /** Expected output from this adapter (wei) */
+  amountOut: string;
+}
+
+// -- Error response --
+
+/** 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 function isErrorResponse(
+  response: QuoteResponse,
+): response is ErrorResponse {
+  return "error" in response;
+}
+
+// -- Adapters endpoint --
+
+/** 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[];
+}
+
+// -- Check Tax endpoint --
+
+/** 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;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Limit Orders (V2 — EIP-712 signed, approve-only)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// -- Order parameters --
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+// -- API request/response types --
+
+/** Body for `POST /limit-orders` */
+export type CreateLimitOrderRequest = SignedLimitOrder;
+
+/** Body for `DELETE /limit-orders` */
+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 output to native PLS flag */
+  unwrapOutput: boolean;
+  /** EIP-712 signature */
+  signature: string;
+  /** Pair key in format `tokenIn:tokenOut` (lowercased) */
+  pairKey: string;
+  /** Current order status */
+  status: LimitOrderStatus;
+  /** ISO 8601 creation timestamp */
+  createdAt: string;
+  /** ISO 8601 last update timestamp */
+  updatedAt: string;
+  /** 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;
+}
+
+/** Response from `DELETE /limit-orders` (success) */
+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;
+}
+
+/** Union type for limit order mutation responses */
+export type LimitOrderMutationResponse =
+  | CreateLimitOrderResponse
+  | CancelLimitOrderResponse
+  | ErrorResponse;