SDK reference

Updated August 20266 min readView as Markdown

pulseswap-sdk is the TypeScript client for PulseChain swaps: one call returns the best route it can build on a platform, with ready-to-execute transaction data and full type definitions. It is the same library this site's own swap uses.

Install

Shell

pnpm add pulseswap-sdk
# or
npm install pulseswap-sdk
# or
yarn add pulseswap-sdk

Quick start

TypeScript

import { PulseSwapSDK, Platform, QuoteMode } from 'pulseswap-sdk';

const sdk = new PulseSwapSDK({
  quoteUrl: 'https://quotes.pulseswap.io/api/v2', // quote API
  piteasUrl: 'https://api.piteas.io',             // Piteas API
});

const quote = await sdk.getQuote(
  {
    chainId: 369,                                             // PulseChain
    fromToken: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27',  // WPLS
    toToken: '0x95B303987A60C71504D99Aa1b13B4DA07b0790ab',    // PLSX
    userAddress: '0x…',                                       // the trader's wallet
    amountIn: '1000000000000000000',                          // 1 WPLS, in wei
    slippage: 0.5,                                            // 0.5%
    mode: QuoteMode.OPTIMAL,                                  // → POST /quotes/advanced
  },
  Platform.PULSEX_V2,
);

if (quote) {
  console.log('Amount out:', quote.amountOut);
  console.log('Transaction:', quote.tx);
}

Pass both URLs. quoteUrl and piteasUrl are optional in the type, but the SDK has no built-in defaults: construct it without quoteUrl and every standard quote resolves to null before a request is ever made.

Piteas quotes are origin-whitelisted. They answer from the pulseswap.io origin, so a server or a local script asking Platform.PITEAS may get a 403 and a null back — every other platform is unaffected.

Supported platforms

Platform is an enum of the 11 DEXes & aggregators the SDK can quote — the table below is generated from the package's own export, so it is whatever version you have installed.

Platform	Wire value	Type	Routes through
Platform.PULSEX_V1	`pulsex_v1`	uni-v2	PulseX V1
Platform.PULSEX_V2	`pulsex_v2`	uni-v2	PulseX V2
Platform.PULSEX_STABLE	`pulsex_stable`	stable	PulseX Stable
Platform.NINEINCH_V2	`9inch_v2`	uni-v2	9inch v2
Platform.NINEINCH_V3	`9inch_v3`	uni-v3	9inch v3
Platform.NINEMM_V2	`9mm_v2`	uni-v2	9mm v2
Platform.NINEMM_V3	`9mm_v3`	uni-v3	9mm v3
Platform.PHUX_V2	`phux_v2`	bal-v2	Phux.io
Platform.TIDE_V3	`tide_v3`	bal-v3	0xTide
Platform.PITEAS	`piteas`	piteas	Piteas
Platform.PULSESWAP	`pulseswap`	pulseswap	PulseSwap

TypeScript

// The PulseSwap aggregator: searches across DEXes rather than inside one.
// It REQUIRES QuoteMode.OPTIMAL — any other mode returns null without a request.
const best = await sdk.getQuote(
  { ...request, mode: QuoteMode.OPTIMAL },
  Platform.PULSESWAP,
);

// Piteas is a routing partner with its own API; the SDK sends this one to piteasUrl.
const piteas = await sdk.getQuote(
  { ...request, mode: QuoteMode.OPTIMAL },
  Platform.PITEAS,
);

Quote modes

mode is not a hint — it picks the endpoint behind the call:

QuoteMode.FAST → POST /quotes, the standard algorithm.
QuoteMode.OPTIMAL → POST /quotes/advanced, a deeper route search: better for large swaps and illiquid pairs, slightly slower.

Token taxes belong in extra: tokenInTax and tokenOutTax are basis points (100 = 1%) used for the SDK's own fee maths, and are stripped from the request body before it is sent. The USD prices and gas fields are forwarded, and are what let the service rank routes by net value rather than raw output.

Types

Straight from the shipped declarations — getQuote(request, platform) resolves to QuoteResult or null.

TypeScript

type PulseSwapSDKConfig = {
  quoteUrl?: string;
  piteasUrl?: string;
};

type QuoteRequest = {
  chainId: number;
  fromToken: `0x${string}`;
  toToken: `0x${string}`;
  userAddress?: `0x${string}`;
  amountIn: string;
  amountInUsd?: number;
  slippage: number;
  mode: QuoteMode;
  extra?: QuoteExtra;
};

type QuoteExtra = {
  tokenInTax?: number;      // basis points, e.g. 100 = 1%
  tokenOutTax?: number;     // basis points, e.g. 200 = 2%
  tokenInPrice?: number;    // USD, improves optimisation
  tokenOutPrice?: number;   // USD, improves optimisation
  gasPrice?: string;        // wei, as a string
  gasTokenPrice?: number;   // USD
};

type QuoteResult = {
  success: boolean;
  quoteId: string;
  amountIn: string;
  amountOut: string;
  gasEstimate: number;
  splits: [number, Route[]][];
  tx?: Transaction;
};

type Route = {
  pairAddress: `0x${string}`;
  tokenIn: `0x${string}`;
  tokenOut: `0x${string}`;
  fee: number;
  feeDenominator: number;
  platform: Platform;
};

type Transaction = {
  from: `0x${string}`;
  to: `0x${string}`;
  data: string;
  value: string;
};

enum QuoteMode {
  FAST = 'fast',        // → POST /quotes
  OPTIMAL = 'optimal',  // → POST /quotes/advanced
}

Error handling

The SDK does not throw for a failed quote: it resolves to null. That covers a network error, an invalid pair, a zero amountIn, an unset quoteUrl and Platform.PULSESWAP asked in the wrong mode — so a null check is not optional.

TypeScript

const quote = await sdk.getQuote(request, platform);

if (!quote) {
  // no route, a network error, an unset quoteUrl, or amountIn === '0'
  console.error('Failed to get quote');
  return;
}

console.log('Quote successful:', quote.amountOut);

Every type, enum value and behaviour on this page was read from pulseswap-sdk as installed in this site's own build, not from a changelog.

Prefer plain HTTP? API reference pulseswap-sdk on npm