API Reference

PulseSwap is a multi-chain DEX aggregator that finds the best swap prices across multiple liquidity sources. It scans 12+ aggregators and 50+ DEXs in real time, including PulseX, Piteas, 9inch, and others. Developers can integrate PulseSwap to give users cost-efficient swaps directly inside their applications.

Overview

The Quote API provides two endpoints for getting swap quotes on PulseChain DEX platforms:

• POST /quotes – Standard quote algorithm (fast, optimized for common swaps)

• POST /quotes/advanced – Advanced routing (deeper route search, best for complex swaps)

Both endpoints use the same request and response structure.

Base URL

https://quotes.pulseswap.io/api/v2

All endpoints are relative to this base URL.

---

POST /quotes

Get a quote using the standard routing algorithm.

Endpoint

POST /quotes

Request Headers

Content-Type: application/json

Request Body

{
  chainId: number;
  platform: string;
  fromToken: string;
  toToken: string;
  amountIn: string;
  slippage: number;
  userAddress?: string;
  amountUSD?: number;
  extra?: {
    tokenInPrice?: number;
    tokenOutPrice?: number;
    gasPrice?: string;
    gasTokenPrice?: number;
  };
}

Request Schema

Field	Type	Required	Description
chainId	number	Yes	Must be 369 (PulseChain)
platform	string	Yes	DEX platform identifier (see Supported Platforms)
fromToken	string	Yes	Source token address (42-char EVM address). Use 0x000...000 for PLS
toToken	string	Yes	Destination token address (42-char EVM address). Use 0x000...000 for PLS
amountIn	string	Yes	Amount in wei/smallest unit
slippage	number	Yes	Max allowed slippage (0.0 to 100.0)
userAddress	string	No	EVM address used to generate transaction data
amountUSD	number	No	USD amount for analytics
extra	object	No	Additional pricing & gas parameters
extra.tokenInPrice	number	No	Price of input token in USD
extra.tokenOutPrice	number	No	Price of output token in USD
extra.gasPrice	string	No	Gas price in wei (string)
extra.gasTokenPrice	number	No	Gas token price in USD

---

Supported Platforms

Platform	DEX Type	Description
pulsex_v1	UniV2	PulseX V1
pulsex_v2	UniV2	PulseX V2
pulsex_stable	Stable	PulseX Stable Pools
9inch_v2	UniV2	9inch V2
9inch_v3	UniV3	9inch V3
9mm_v2	UniV2	9mm V2
9mm_v3	UniV3	9mm V3
phux_v2	BalV2	Phux V2
tide_v3	BalV3	Tide V3
mixed	Mixed	Cross-DEX routing

---

Response Schema

{
  success: boolean;
  data: {
    success: boolean;
    quoteId: string;
    amountIn: string;
    amountOut: string;
    amountOutUSD: string;
    gasEstimate: number;
    tx?: {
      from: string;
      to: string;
      data: string;
      value: string;
    };
  };
  message: string;
  timestamp: string;
}

---

Example Request

curl -X POST https://quotes.pulseswap.io/api/v2/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 369,
    "platform": "pulsex_v2",
    "fromToken": "0x0000000000000000000000000000000000000000",
    "toToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
    "userAddress": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29",
    "amountIn": "1000000000000000000",
    "amountUSD": 1000.0,
    "slippage": 0.5
  }'

Example Response

{
  "success": true,
  "data": {
    "success": true,
    "quoteId": "123e4567-e89b-12d3-a456-426614174000",
    "amountIn": "1000000000000000000",
    "amountOut": "950000000000000000",
    "amountOutUSD": "950000000000000000",
    "gasEstimate": 21000,
    "tx": {
      "from": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29",
      "to": "0x0987654321098765432109876543210987654321",
      "data": "0x1234567890abcdef",
      "value": "0x0"
    }
  },
  "message": "OK",
  "timestamp": "2024-01-15T10:30:00Z"
}

---

POST /quotes/advanced

The advanced endpoint performs more exhaustive routing.

Endpoint

POST /quotes/advanced

Same request schema as /quotes.

Differences

• Deeper route exploration

• Better multi-hop optimization

• Better for large swaps or illiquid pairs

• Slightly slower

---

Example Request

curl -X POST https://quotes.pulseswap.io/api/v2/quotes/advanced \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 369,
    "platform": "mixed",
    "fromToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
    "toToken": "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab",
    "userAddress": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29",
    "amountIn": "1000000000000000000",
    "amountUSD": 1000.0,
    "slippage": 0.5,
    "extra": {
      "tokenInPrice": 1.0,
      "tokenOutPrice": 1.0,
      "gasPrice": "12345667890",
      "gasTokenPrice": 1.0
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "success": true,
    "quoteId": "456e7890-e89b-12d3-a456-426614174000",
    "amountIn": "1000000000000000000",
    "amountOut": "980000000000000000",
    "amountOutUSD": "980000000000000000",
    "gasEstimate": 18000,
    "tx": {
      "from": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29",
      "to": "0x0987654321098765432109876543210987654321",
      "data": "0x1234567890abcdef",
      "value": "0x0"
    }
  },
  "message": "OK",
  "timestamp": "2024-01-15T10:30:00Z"
}

---

Validation Rules

Chain ID

• Must be 369 (PulseChain)

Token Addresses

• Must be valid 42-character EVM addresses

• Use 0x000...000 for native PLS

Amount Format

• Must be a positive integer string (wei)

Slippage

• Must be between 0.0 and 100.0

Platform

• Must match one of the supported platforms (case-sensitive)

User Address

• Optional but must be a valid EVM address if provided

---

Common Use Cases

Simple PLS → Token

{
  "chainId": 369,
  "platform": "pulsex_v2",
  "fromToken": "0x0000000000000000000000000000000000000000",
  "toToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
  "amountIn": "1000000000000000000",
  "slippage": 0.5
}

ERC20 → ERC20

{
  "chainId": 369,
  "platform": "9inch_v3",
  "fromToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
  "toToken": "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab",
  "amountIn": "1000000000000000000",
  "slippage": 0.3
}

Swap With Transaction Data

{
  "chainId": 369,
  "platform": "pulsex_v2",
  "fromToken": "0x0000000000000000000000000000000000000000",
  "toToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
  "userAddress": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29",
  "amountIn": "1000000000000000000",
  "slippage": 0.5
}

Swap With Extra Pricing Data

{
  "chainId": 369,
  "platform": "mixed",
  "fromToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
  "toToken": "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab",
  "amountIn": "1000000000000000000",
  "slippage": 0.5,
  "extra": {
    "tokenInPrice": 1.0,
    "tokenOutPrice": 0.95,
    "gasPrice": "20000000000",
    "gasTokenPrice": 0.0001
  }
}

---

Error Handling

Invalid Chain ID

{
  "success": false,
  "data": null,
  "message": "Validation failed: Unsupported chain_id: 1. Only PulseChain (369) is supported",
  "timestamp": "2024-01-15T10:30:00Z"
}

Invalid Platform

{
  "success": false,
  "data": null,
  "message": "Validation failed: Invalid platform: 'invalid_platform'. Supported platforms: pulsex_v1, pulsex_v2, pulsex_stable, 9inch_v2, 9inch_v3, 9mm_v2, 9mm_v3, phux_v2, tide_v3, mixed",
  "timestamp": "2024-01-15T10:30:00Z"
}

Invalid Token Address

{
  "success": false,
  "data": null,
  "message": "Validation failed: fromToken: Validation error: length is 15, expected 42",
  "timestamp": "2024-01-15T10:30:00Z"
}

Invalid Slippage

{
  "success": false,
  "data": null,
  "message": "Validation failed: slippage: Validation error: range is outside [0.0, 100.0]",
  "timestamp": "2024-01-15T10:30:00Z"
}

Server Error

{
  "success": false,
  "data": null,
  "message": "Internal server error",
  "timestamp": "2024-01-15T10:30:00Z"
}

---

Best Practices

Caching

• Quotes cached for 5 seconds

• Use identical params to utilize cache

Slippage

• 0.1–0.5% for stablecoins

• 1–3% for volatile assets

Platform Choice

• pulsex_v2, 9inch_v2 for standard swaps

• pulsex_stable for stablecoins

• mixed for best overall price

• 9inch_v3 / 9mm_v3 for UniV3 concentrated liquidity

Transaction Execution

• Quotes expire quickly

• Execute ASAP

• Always validate gas costs

Error Handling

• Check success

• Handle validation failures

• Log quoteId for debugging

---

Rate Limiting

• 60 requests/min/IP

• Whitelisted domains bypass limits:

  • pulsecoinlist.com

  • pulseswap.io

• User-Agent bot detection enabled

---

CORS Support

• Automatic OPTIONS handling

• CORS headers included on all responses

---

Developer Notes

1. Use 0x000...000 for native PLS (auto-wrapped to WPLS).

2. Always send amountIn as a string.

3. Quotes are cached for 5 seconds.

4. tx only appears when userAddress is provided.

5. Gas estimates are approximate.

6. Platform determines DEX routing logic automatically.

7. Contact/support via X @PulseCoinList