# 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

<table><thead><tr><th>Environment</th><th width="415.07421875">URL</th></tr></thead><tbody><tr><td>Story mainnet</td><td><code>https://piperxdb.piperxprotocol.workers.dev</code></td></tr></tbody></table>

### Supported Networks

| Chain ID | Network       |
| -------- | ------------- |
| 1514     | Story Mainnet |

## API Documentation

### Get swap quote

<mark style="color:blue;background-color:purple;">**`[GET]`**</mark>  `https://piperxdb.piperxprotocol.workers.dev/api/swap/swapExactToken`

Returns the best swap quote based on the provided parameters.

<details>

<summary><strong>QUERY PARAMETERS</strong></summary>

&#x20;**`tokenIn`** **(string, required)**

**The address of the input token**\
Example: `0xF1815bd50389c46847f0Bda824eC8da914045D14`

***

**`tokenOut` (string, required)**

**The address of the output token**\
Example: `0x855bd6a8c5046d97c4e063e90e40f0f010d5423a`

***

&#x20;**`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.

***

&#x20;**`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.

</details>

***

<details>

<summary>Response <strong>Schema</strong></summary>

**`num` (string, required)**

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

***

&#x20;**`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)

</details>

<details>

<summary> <strong>Response</strong></summary>

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

</details>

### Example Request

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

### **Example Response**

```json
{
  "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.