🚅Aggregator API

PiperX Aggregator exposes a set of APIs that allow developers to easily query optimal rates for a token swap. These APIs return additional swap data such as the precise swap route, routing parameters, and the encoded calldata required to interact with the Aggregator smart contract.

Public API

Environment	URL
Story mainnet	https://piperxdb.piperxprotocol.workers.dev

Supported Networks

Chain ID	Network
1514	Story Mainnet

API Documentation

Get swap quote

[GET] https://piperxdb.piperxprotocol.workers.dev/api/swap/swapExactToken

Returns the best swap quote based on the provided parameters.

QUERY PARAMETERS

tokenIn (string, required)

The address of the input token Example: 0xF1815bd50389c46847f0Bda824eC8da914045D14

---

tokenOut (string, required)

The address of the output token Example: 0x855bd6a8c5046d97c4e063e90e40f0f010d5423a

---

amount (string, required)

Amount of the input token in base units (raw integer) Example: 1000000 means 1 token if the input token has 6 decimals.

---

type (string, required)

Routing type

• Possible values: exactInput, exactOutput

• Default: exactInput

• If exactInput, amount means input amount

• If exactOutput, amount means target output amount

---

isAggregator (boolean, optional)

Whether to use aggregator route logic

• Default: false

• If true, will search multiple DEXes to optimize route.

---

Response Schema

num (string, required)

Final output amount calculated by the router, in raw base units.

---

universalRoutes (array, required)

Route list. Each route contains:

• route (array) of hops Each hop includes:

  • routerAddress (string)

  • poolType (number) — 0 = V2, 1 = V3

  • tokenIn (string)

  • tokenOut (string)

  • fee (number) — e.g. 3000

  • weight (number)

• percent (number)

• amountIn (string)

• amountOut (string)

Response

{
  "num": "string",
  "universalRoutes": [
    {
      "route": [
        {
          "routerAddress": "string",
          "poolType": 0,
          "tokenIn": "string",
          "tokenOut": "string",
          "fee": 0,
          "weight": 0
        }
      ],
      "percent": 0,
      "amountIn": "string",
      "amountOut": "string"
    }
  ]
}

Example Request

curl 'https://piperxdb.piperxprotocol.workers.dev/api/swap/swapExactToken?'\
'tokenIn=0xF1815bd50389c46847f0Bda824eC8da914045D14&'\
'tokenOut=0x02353a3BD5c9668159cF9Fd54AC61b03212FCf41&'\
'amount=1000000&type=exactInput&isAggregator=true'

Example Response

{
  "num": "457977361510434403631",
  "universalRoutes": [
    {
      "route": [
        {
          "routerAddress": "0x8295c195CEe31404ea082d253a140310b9a0A37e",
          "poolType": 1,
          "tokenIn": "0xF1815bd50389c46847f0Bda824eC8da914045D14",
          "tokenOut": "0xbab93b7ad7fe8692a878b95a8e689423437cc500",
          "fee": 3000,
          "weight": 0.010360735915986746
        },
        {
          "routerAddress": "0x8295c195CEe31404ea082d253a140310b9a0A37e",
          "poolType": 1,
          "tokenIn": "0xbab93b7ad7fe8692a878b95a8e689423437cc500",
          "tokenOut": "0x1514000000000000000000000000000000000000",
          "fee": 3000,
          "weight": 0.004157898814527259
        },
        {
          "routerAddress": "0x1062916B1Be3c034C1dC6C26f682Daf1861A3909",
          "poolType": 1,
          "tokenIn": "0x1514000000000000000000000000000000000000",
          "tokenOut": "0x02353a3BD5c9668159cF9Fd54AC61b03212FCf41",
          "fee": 3000,
          "weight": 0.18184197356998186
        }
      ],
      "percent": 100,
      "amountIn": "1000000",
      "amountOut": "457977361510434403631"
    }
  ]
}

Protocol

Supported DEXes in Aggregator Mode (isAggregator=true)

When isAggregator=true, the PiperX Aggregator automatically selects the best route across the following DEXes:

DEX Name	Description
PiperX V2	Classic V2-based AMM on PiperX
StoryHunt V3	V3 liquidity on Story chain
PiperX V3	Optimized V3-style pools on PiperX

These DEXes are automatically included in the route discovery — no need to manually specify protocols.