> For the complete documentation index, see [llms.txt](https://docs.pulseswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pulseswap.io/integrations/api-reference.md). # 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 ```ts { 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
FieldTypeRequiredDescription
chainIdnumberYesMust be 369 (PulseChain)
platformstringYesDEX platform identifier (see Supported Platforms)
fromTokenstringYesSource token address (42-char EVM address). Use 0x000...000 for PLS
toTokenstringYesDestination token address (42-char EVM address). Use 0x000...000 for PLS
amountInstringYesAmount in wei/smallest unit
slippagenumberYesMax allowed slippage (0.0 to 100.0)
userAddressstringNoEVM address used to generate transaction data
amountUSDnumberNoUSD amount for analytics
extraobjectNoAdditional pricing & gas parameters
extra.tokenInPricenumberNoPrice of input token in USD
extra.tokenOutPricenumberNoPrice of output token in USD
extra.gasPricestringNoGas price in wei (string)
extra.gasTokenPricenumberNoGas 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 ```ts { 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 ```bash 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 ```json { "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 ```bash 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 ```json { "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 ```json { "chainId": 369, "platform": "pulsex_v2", "fromToken": "0x0000000000000000000000000000000000000000", "toToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27", "amountIn": "1000000000000000000", "slippage": 0.5 } ``` #### ERC20 → ERC20 ```json { "chainId": 369, "platform": "9inch_v3", "fromToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27", "toToken": "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab", "amountIn": "1000000000000000000", "slippage": 0.3 } ``` #### Swap With Transaction Data ```json { "chainId": 369, "platform": "pulsex_v2", "fromToken": "0x0000000000000000000000000000000000000000", "toToken": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27", "userAddress": "0x742d35Cc6634C0532925a3b8D221691B5c1b6b29", "amountIn": "1000000000000000000", "slippage": 0.5 } ``` #### Swap With Extra Pricing Data ```json { "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 ```json { "success": false, "data": null, "message": "Validation failed: Unsupported chain_id: 1. Only PulseChain (369) is supported", "timestamp": "2024-01-15T10:30:00Z" } ``` #### Invalid Platform ```json { "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 ```json { "success": false, "data": null, "message": "Validation failed: fromToken: Validation error: length is 15, expected 42", "timestamp": "2024-01-15T10:30:00Z" } ``` #### Invalid Slippage ```json { "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 ```json { "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](https://x.com/PulseCoinList) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pulseswap.io/integrations/api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.