SDK Reference

A TypeScript SDK for interacting with PulseSwap.io, providing seamless integration with multiple DEX platforms on the PulseChain network.

Features

• Multi-DEX Support: Integration with PulseX V1/V2/Stable, 9inch V2/V3, 9mm V2/V3, Phux.io, 0xTide, Piteas, and PulseSwap Aggregator

• Quote Generation: Get optimal swap quotes across different platforms with FAST or OPTIMAL modes

• Transaction Building: Generate ready-to-execute transaction data

• TypeScript Support: Full type definitions for better developer experience

• Fee Management: Built-in fee calculation and optimization

• Aggregator Support: Access to Piteas and PulseSwap aggregators for best route finding

---

Installation

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

---

Quick Start

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

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

// Get a quote
const quote = await sdk.getQuote({
  chainId: 369, // PulseChain mainnet
  fromToken: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27', // WPLS
  toToken: '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07',   // USDC
  userAddress: '0x...',                                   // User's wallet address
  amountIn: '1000000000000000000',                        // 1 PLS (in wei)
  slippage: 0.5,                                          // 0.5% slippage
  mode: QuoteMode.OPTIMAL,                                // Quote mode
  extra: {
    tokenInTax: 100,       // 1% tax on input token (basis points)
    tokenOutTax: 200,      // 2% tax on output token (basis points)
    tokenInPrice: 0.0001,  // Optional: USD price for better optimization
    tokenOutPrice: 1.0,    // Optional: USD price for better optimization
    gasPrice: '1000000000',// Optional: Gas price in wei
    gasTokenPrice: 0.0001, // Optional: Gas token USD price
  },
}, Platform.PULSEX_V2);

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

---

Supported Platforms

import { Platform } from 'pulseswap-sdk';

Platform	Type	Description
Platform.PULSEX_V1	Uniswap V2	PulseX V1 DEX
Platform.PULSEX_V2	Uniswap V2	PulseX V2 DEX
Platform.PULSEX_STABLE	Stable	PulseX Stable DEX
Platform.NINEINCH_V2	Uniswap V2	9inch V2 DEX
Platform.NINEINCH_V3	Uniswap V3	9inch V3 DEX
Platform.NINEMM_V2	Uniswap V2	9mm V2 DEX
Platform.NINEMM_V3	Uniswap V3	9mm V3 DEX
Platform.PHUX_V2	Balancer V2	Phux.io DEX
Platform.TIDE_V3	Balancer V3	0xTide DEX
Platform.PITEAS	Piteas	Piteas Aggregator
Platform.PULSESWAP	PulseSwap	PulseSwap Aggregator

---

API Reference

PulseSwapSDK

Constructor

constructor(config: PulseSwapSDKConfig)

Parameters:

• config.quoteUrl – URL for the standard quote API (default: https://quotes.pulseswap.io/api/v2)

• config.piteasUrl – URL for the Piteas quote API (default: https://api.piteas.io)

---

getQuote

async getQuote(
  request: QuoteRequest,
  platform: Platform
): Promise<QuoteResult | null>

Gets a swap quote for the specified platform.

Parameters:

• request – Quote request object

• platform – Target DEX platform (Platform enum)

Returns: Promise<QuoteResult | null> – Resolves to quote result, or null if the quote failed.

---

Types

PulseSwapSDKConfig

type PulseSwapSDKConfig = {
  quoteUrl?: string;  // Default: 'https://quotes.pulseswap.io/api/v2'
  piteasUrl?: string; // Default: 'https://api.piteas.io'
};

---

QuoteRequest

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

---

QuoteResult

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

---

Transaction

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

---

Route

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

---

QuoteExtra

type QuoteExtra = {
  tokenInTax?: number;
  tokenOutTax?: number;
  tokenInPrice?: number;
  tokenOutPrice?: number;
  gasPrice?: string;
  gasTokenPrice?: number;
};

Fields:

• tokenInTax – Tax rate for the input token (basis points, e.g. 100 = 1%)

• tokenOutTax – Tax rate for the output token (basis points, e.g. 200 = 2%)

• tokenInPrice – USD price of the input token (for better optimization)

• tokenOutPrice – USD price of the output token (for better optimization)

• gasPrice – Gas price in wei (as string)

• gasTokenPrice – USD price of the gas token (for gas cost calculations)

---

QuoteMode

enum QuoteMode {
  FAST = 'fast',
  OPTIMAL = 'optimal'
}

---

Examples

Basic Swap

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

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

// Swap 1 PLS for USDC
const quote = await sdk.getQuote({
  chainId: 369,
  fromToken: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27', // WPLS
  toToken: '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07',   // USDC
  userAddress: '0x742d35Cc6634C0532925a3b8D0C0E1C4C5C5C5C5',
  amountIn: '1000000000000000000', // 1 PLS
  slippage: 1.0,                   // 1% slippage
  mode: QuoteMode.OPTIMAL,
  extra: {
    tokenInTax: 100,
    tokenOutTax: 200,
    tokenInPrice: 0.0001,
    tokenOutPrice: 1.0,
    gasPrice: '1000000000',
    gasTokenPrice: 0.0001,
  },
}, Platform.PULSEX_V2);

if (quote && quote.tx) {
  // Execute the transaction using your preferred wallet library
  console.log('Transaction data:', quote.tx);
}

---

Using Piteas Aggregator

const quote = await sdk.getQuote({
  chainId: 369,
  fromToken: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27',
  toToken: '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07',
  userAddress: '0x742d35Cc6634C0532925a3b8D0C0E1C4C5C5C5C5',
  amountIn: '1000000000000000000',
  slippage: 0.5,
  mode: QuoteMode.OPTIMAL,
  extra: {
    tokenInTax: 100,
    tokenOutTax: 200,
    tokenInPrice: 0.0001,
    tokenOutPrice: 1.0,
    gasPrice: '1000000000',
    gasTokenPrice: 0.0001,
  },
}, Platform.PITEAS);

---

Using PulseSwap Aggregator

const quote = await sdk.getQuote({
  chainId: 369,
  fromToken: '0xA1077a294dDE1B09bB078844df40758a5D0f9a27',
  toToken: '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07',
  userAddress: '0x742d35Cc6634C0532925a3b8D0C0E1C4C5C5C5C5',
  amountIn: '1000000000000000000',
  slippage: 0.5,
  mode: QuoteMode.OPTIMAL,
  extra: {
    tokenInTax: 100,
    tokenOutTax: 200,
    tokenInPrice: 0.0001,
    tokenOutPrice: 1.0,
    gasPrice: '1000000000',
    gasTokenPrice: 0.0001,
  },
}, Platform.PULSESWAP);

---

Error Handling

The SDK returns null when a quote cannot be generated (network errors, invalid params, etc.). Always check for null:

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

if (!quote) {
  console.error('Failed to get quote');
  return;
}

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