> ## Documentation Index
> Fetch the complete documentation index at: https://staging.docs.aile.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregators and routers

> Filling from a contract: the contract is the taker, the bought token is paid to it, and /levels drives route finding.

This page is for DEX aggregators, routers and any integration where a **contract** calls the order
protocol. The order protocol sees `msg.sender`, so everything about the taker applies to that contract.

## Rules

* **`taker` is the contract that calls the order protocol**, not the end user. The order is pinned to it,
  and the bought token is paid to it: forward it to the user yourself inside the same transaction.
* **Approve `fill.allowanceTarget` from that contract** for `sellAmount` of the sold token before the
  call. The allowance target is the order protocol.
* **Ask for the quote once, when you build the transaction.** Use `GET /levels` for route finding; it is
  free of a key, cacheable for a few seconds, and never reserves inventory.
* **Send `fill.to`, `fill.data` and `fill.value` exactly as returned.** `fill.method` is `fillOrder`
  today and may gain values; do not decode and rebuild the calldata.
* **Send `X-Request-Id`** with your own id on `GET /quote`; it is stored with the quote and helps both
  sides trace a fill.
* **Quote lifetime.** 30 seconds by default. Keys flagged for relayer pipelines can receive 60-second
  quotes: ask when you request your key. Exact-in (`sellAmount`) is the common case; exact-out
  (`buyAmount`) is also available.

## Route finding with levels

`GET /levels` returns one entry per quoted direction:

```json theme={null}
{
  "sellToken": "USDC",
  "buyToken": "IDRX",
  "firmQuoted": true,
  "makers": 1,
  "maxFirmSize": { "sellAmount": "380980", "buyAmount": "685321" },
  "ladder": [{ "sellAmount": "380980", "buyAmount": "685321" }],
  "reference": { "rate": "0.00005537", "source": "chainlink", "at": 1794118791 },
  "reason": null
}
```

* `maxFirmSize` is the largest size you can get a firm quote for now, in both tokens. A request above it
  answers `400 over-size` with the maximum in the detail.
* `ladder` has one rung at `maxFirmSize` while the price does not depend on the size; the price after the
  spread is `buyAmount / sellAmount` of that rung.
* `firmQuoted: false` with a `reason` means a quote of this direction would be refused right now; skip
  the route. Treat a `reason` you do not know the same way.
* `pair=BASE/QUOTE` narrows the answer to one pair, in either order.

## Simulating

The fill is a plain call to the order protocol with the calldata the quote returns, so `eth_call` it from
the taker contract before you broadcast. The call reverts `OrderExpired` after `expiresAt`,
`BitInvalidatedOrder` if the order was already filled, and the usual ERC-20 errors if the allowance or
balance is short.

## Attribution

Every quote is attributed to the API key that requested it. There is nothing to put on chain for
attribution, and no fee leg in the order today (`fees.bps` is `0`).

> [!NOTE]
>
> Listing Aile as a liquidity source in your router? Write to [hello@aile.tech](mailto:hello@aile.tech)
> with the shape your router expects; the four routes above are what we provide today.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.