# SDK reference

`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

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

## Quick start

```ts
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      |

```ts
// 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`.

```ts
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.

```ts
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.

---

Canonical HTML page: <https://pulseswap.io/docs/sdk>