pulseswap-sdk

v0.6.0

Published

a month ago

SDK for Pulseswap.io

0High
0Medium
0Low

PulseSwap SDK

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 development 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
    tokenOutTax: 200, // 2% tax on output token
    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

| 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)

Methods

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

Returns: Promise resolving to quote result or null if 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;
};

Optional extra parameters for quote requests:

tokenInTax: Tax rate for the input token (in basis points, e.g., 100 = 1%)
tokenOutTax: Tax rate for the output token (in basis points, e.g., 200 = 2%)
tokenInPrice: USD price of the input token (for better quote optimization)
tokenOutPrice: USD price of the output token (for better quote optimization)
gasPrice: Gas price in wei (as string) for gas estimation
gasTokenPrice: USD price of the gas token (for gas cost calculations)

QuoteMode

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

Constants

The SDK provides several useful constants:

import { 
  WPLS_ADDRESS,
  STABLE_TOKENS,
  POPULAR_TOKENS,
  SUPPORTED_DEXES 
} from 'pulseswap-sdk';

// Wrapped PLS address
console.log(WPLS_ADDRESS); // 0xA1077a294dDE1B09bB078844df40758a5D0f9a27

// Popular tokens on PulseChain
console.log(POPULAR_TOKENS); // Array of popular token addresses

// Supported DEX information
console.log(SUPPORTED_DEXES); // Array of DEX configurations

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, // 1% tax on input token
    tokenOutTax: 200, // 2% tax on output token
    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 && quote.tx) {
  // Execute the transaction using your preferred wallet library
  console.log('Transaction data:', quote.tx);
}

Using Piteas Aggregator

// Get the best quote 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, // 1% tax on input token
    tokenOutTax: 200, // 2% tax on output token
    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.PITEAS);

Using PulseSwap Aggregator

// Get the best quote 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, // 1% tax on input token
    tokenOutTax: 200, // 2% tax on output token
    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.PULSESWAP);

Error Handling

The SDK handles errors gracefully and returns null when quotes fail. Always check for null results:

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

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

// Proceed with the quote
console.log('Quote successful:', quote.amountOut);

Development

Building

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Clean build artifacts
pnpm run clean

# Format code
pnpm run format

Project Structure

src/
├── index.ts              # Main SDK entry point (PulseSwapSDK class)
├── piteas/              # Piteas aggregator implementation
│   ├── abi.ts          # Piteas router ABI definitions
│   └── index.ts        # PiteasQuoter class
├── standard/            # Standard DEX quote implementation
│   ├── abi.ts          # PulseSwap router ABI definitions
│   └── index.ts        # StandardQuoter class
└── utils/               # Utilities, types, and constants
    ├── constants.ts    # Token addresses, router/factory addresses, DEX configs
    ├── enums.ts        # Platform and QuoteMode enums
    ├── helpers.ts      # Utility functions (BigNumber, fee calculation, encoding)
    ├── types.ts        # TypeScript type definitions
    └── index.ts        # Utils module exports

Dependencies

axios: HTTP client for API requests
bignumber.js: Big number arithmetic and calculations
ethers: Ethereum utilities for encoding/decoding
uuid: UUID generation for quote IDs
viem: Ethereum library for transaction encoding and address handling

License

ISC

Support

Issues: GitHub Issues
Email: [email protected]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

v0.2.0

Breaking Change: Updated constructor to use config object pattern
Added new type definitions: PulseSwapSDKConfig, Route, QuoteExtra
Enhanced error handling and logging
Improved documentation with comprehensive JSDoc comments
Better support for token tax calculations

v0.1.0

Initial release
Support for multiple DEX platforms
Piteas aggregator integration
TypeScript support