> ## 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.

# API overview

> Base URL, authentication, rate limits, quote lifetime, problem reasons and the compatibility promise of the Aile quote API.

Four routes, all `GET`, all JSON. The spec on this site is a daily snapshot of the staging gateway's own
OpenAPI document; the gateway also serves it live with a
[Swagger UI](https://staging.app.aile.tech/api/v1/integration/docs).

| Route | Key | Purpose |
| - | - | - |
| [`GET /v1/config`](https://staging.docs.aile.tech/api-reference/get-config) | optional | Chain, order protocol address, tokens with decimals. Cacheable 60 s. |
| [`GET /v1/levels`](https://staging.docs.aile.tech/api-reference/get-levels) | optional | Largest firm size and its price per direction, before a quote. Indicative. |
| [`GET /v1/quote`](https://staging.docs.aile.tech/api-reference/get-quote) | **required** | A maker-signed order with ready calldata, for one taker, valid about 30 s. |
| [`GET /v1/orders/{hash}`](https://staging.docs.aile.tech/api-reference/get-orders) | optional | The fill of a quote, from indexed chain events. |

## Base URL

```
https://staging.app.aile.tech/api/base/v1
```

Base mainnet, chain ID 8453, real assets. The `/base` segment names the network; routes for other
networks will appear next to it.

## Authentication

Aile issues your API key. Send it as `Authorization: Bearer <key>` and keep it on your backend.

* `GET /quote` requires it; without a key it answers `401 api-key-required`.
* The other routes work without it. With it, their calls count against your own budget and are
  attributed to you instead of sharing the anonymous per-address limit.

[How to get a key](https://staging.docs.aile.tech/legal/get-an-api-key.md).

## Rate limits

* Each key has its own request budget, set when it is issued. Over budget you get `429 key-rate-limit`
  with a `Retry-After` header.
* Keyless calls to `/config`, `/levels` and `/orders` share a limit per calling address; over it you get
  `429 rate-limited` with `Retry-After`.
* `/config` is cacheable for 60 seconds and `/levels` for a few seconds; read them on a timer, not per
  user keystroke.

## Quote lifetime

A quote is an order signed by the market maker. It is valid for about **30 seconds** (`expiresAt`, unix
seconds), only the `taker` can use it, and it can be used once. The maker holds the inventory for the
quote until it expires or fills. Ask for a quote when you are ready to send the transaction; use
`/levels` while you are deciding. Keys flagged for relayer pipelines can receive 60-second quotes on
request.

## Problems

Errors are RFC 7807 problem details (`type`, `title`, `status`, `detail`) plus a machine-readable
`reason`. Branch on `reason`, not on `title`. **Treat a `reason` you do not know as "no quote".**

| Status | Reason | Meaning |
| - | - | - |
| 400 | `invalid-request` | A parameter is missing or malformed (both or neither of `sellAmount`/`buyAmount`; `recipient` is not accepted). |
| 400 | `bad-pair` | Nobody quotes this pair, or a token is not offered on this network. |
| 400 | `amount-too-small` | Below the minimum; the detail names it. |
| 400 | `over-size` | Above `maxFirmSize`; the detail names the maximum. |
| 401 | `api-key-required` | `GET /quote` without a key. |
| 403 | `address-refused` | The `taker` may not be quoted. |
| 429 | `key-rate-limit` | Your key's budget is spent; see `Retry-After`. |
| 429 | `rate-limited` | The anonymous per-address limit; see `Retry-After`. |
| 503 | `no-maker` | No market maker is quoting this direction now. |
| 503 | `maker-unavailable` | The maker did not answer in time. |
| 503 | `no-price` | No reference price could be read. |
| 503 | `maker-underfunded` | The maker's balance cannot cover the size. |
| 503 | `maker-allowance` | The maker's allowance to the order protocol cannot cover the size. |
| 503 | `kill-switch` | Trading is paused. |
| 503 | `screening-unavailable` | The wallet check could not run. |

`GET /levels` reports the same reasons per direction in its `reason` field, so you can see before asking
why a direction would be refused.

## Compatibility promise

What you can rely on across every later release of the API:

* Fields, routes and enumeration values are only ever **added**, never removed or changed in type.
* Send `fill.to`, `fill.data` and `fill.value` exactly as returned. `order`, `signature`, `maker` and the
  other `fill` fields are there for your information.
* Do not hard-code the maker address: it changes. Read the order protocol address from `/config`.
* `maker.kind`, `signature.type`, `fill.method` and the problem `reason` can gain new values. Treat a
  `reason` you do not know as "no quote".

Build against these four rules and your integration keeps working without tracking our releases.

## Amounts

Every amount is a decimal string in the token's base units, never a float. Decimals are in `/config`
(`tokens[].decimals`, `bookTokens[].decimals`): USDC 6, EURC 6, XSGD 6, TRYB 6, IDRX 2, CADC 18, TGBP 18.


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