SDK types reference

type SwapMode = "ExactIn" | "ExactOut";

type PriceImpactSeverity = "none" | "low" | "moderate" | "high" | "extreme";

interface SDKConfig {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
}

interface QuoteRequest {
  inputMint: string;
  outputMint: string;
  amount: string;
  swapMode: SwapMode;
  slippageBps?: number;
}

interface QuoteResponse {
  inputMint: string;
  outputMint: string;
  amountIn: string;
  amountOut: string;
  priceImpactBps: number;
  priceImpactPercent: string;
  priceImpactSeverity: PriceImpactSeverity;
  priceImpactWarning: string;
  feeBps: number;
  routes: RouteInfo[];
  routePath: string[];
  hopCount: number;
  otherAmountThreshold: string;
  /** Firm-quote commitment ID — pass to swap()/instructions() to replay this
   * exact route at this price. Omitted when the quote can't be pinned. */
  quoteId?: string;
  /** How long quoteId stays redeemable, in ms. */
  validForMs?: number;
  /** How long quoteId stays redeemable with firm: true, in ms. */
  firmForMs?: number;
}

interface RouteInfo {
  poolAddress: string;
  poolType: string;
  percent: number;
  inputMint: string;
  outputMint: string;
}

interface SwapRequest {
  userWallet: string;
  inputMint: string;
  outputMint: string;
  amount: string;
  swapMode: SwapMode;
  slippageBps?: number;
  skipSimulation?: boolean;
  /** Firm-quote ID from quote() — replays the exact quoted route. */
  quoteId?: string;
  /** Price-or-fail redemption (requires quoteId, within firmForMs). */
  firm?: boolean;
}

interface SwapResponse {
  transaction: string;
  lastValidBlockHeight: number;
  amountIn: string;
  amountOut: string;
  minAmountOut?: string;
  maxAmountIn?: string;
  feeAmount: string;
  simulation?: SimulationResult;
  computeUnitsEstimate: number;
  route: string[];
  hopCount: number;
  pools: string[];
  isSplitRoute: boolean;
  splitPercents?: number[];
}

interface SimulationResult {
  success: boolean;
  computeUnitsConsumed: number;
  computeUnitsTotal: number;
  logs: string[];
  error: string;
  slippageExceeded: boolean;
  insufficientFunds: boolean;
  accountsNeeded: string[];
}

interface InstructionsRequest {
  userWallet: string;
  inputMint: string;
  outputMint: string;
  amount: string;
  swapMode: SwapMode;
  slippageBps?: number;
  /** Firm-quote ID from quote() — replays the exact quoted route. */
  quoteId?: string;
  /** Price-or-fail redemption (requires quoteId, within firmForMs). */
  firm?: boolean;
}

interface InstructionsResponse {
  instructions: RawInstruction[];
  addressLookupTableAddresses: string[];
  amountIn: string;
  amountOut: string;
  otherAmountThreshold: string;
  feeAmount: string;
  hopCount: number;
  route: string[];
  pools: string[];
}

interface RawInstruction {
  programId: string;
  accounts: RawAccountMeta[];
  data: string;
}

interface RawAccountMeta {
  publicKey: string;
  isSigner: boolean;
  isWritable: boolean;
}

class VulcxError extends Error {
  readonly statusCode: number;
  readonly body?: unknown;
}

class BadRequestError extends VulcxError {} // statusCode: 400

class AuthError extends VulcxError {} // statusCode: 401

class NoRouteError extends VulcxError {} // statusCode: 404

class RateLimitError extends VulcxError {} // statusCode: 429

class QuoteStaleError extends VulcxError {} // statusCode: 409 — pinned route gone or firm price drifted

class QuoteExpiredError extends VulcxError {} // statusCode: 410 — quoteId past its TTL

class ServerError extends VulcxError {} // statusCode: 500