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

# How it works

> Get a price, send one transaction, receive the exact amount. What a firm quote is, what Aile's servers do, and what the chain enforces.

## The flow

**1. Read the deployment**

`GET /config` returns the chain, the order protocol address (`contracts.lop`) and the tokens with their
decimals. Read it at startup; it is cacheable for 60 seconds.

**2. Ask for a quote**

`GET /quote` prices `sellToken` to `buyToken` for exactly one of `sellAmount` (exact-in) or
`buyAmount` (exact-out). Pass as `taker` the address that will send the transaction. The answer is an
order signed by a market maker plus the calldata that fills it.

**3. Approve**

From the taker address, approve `fill.allowanceTarget` (the order protocol) for the token you sell.
Once is enough if you approve a large amount.

**4. Fill**

Send `fill.to`, `fill.data` and `fill.value` from the taker address before `expiresAt`. Send them
exactly as returned.

**5. Read the receipt**

The transaction delivers exactly `buyAmount` of the bought token to the taker, or reverts. The `Transfer`
logs in the receipt are your confirmation; `GET /orders/{hash}` shows the same fill once indexed.

```mermaid theme={null}
sequenceDiagram
    participant T as Taker (your backend or wallet)
    participant G as Aile gateway
    participant M as Market maker
    participant C as Order protocol on Base
    T->>G: GET /quote (pair, amount, taker)
    G->>M: price and size the request
    M-->>G: order signed by the maker
    G-->>T: quote: order, signature, fill calldata, expiresAt
    T->>C: fillOrder(order, signature, ...) from the taker address
    C->>C: check signature, taker, expiry, nonce
    C->>C: move both tokens at the signed amounts
    C-->>T: receipt (exact buyAmount) or revert
```

## What a quote is

A quote is an ordinary order on the order protocol that a market maker signs for you:

| Property | Meaning |
| - | - |
| Signed by the maker | The maker's signature authorises the exact amounts. The maker holds the inventory it quotes from. |
| Pinned to one taker | `allowedSender` is your `taker`. Nobody else can use the order. |
| Valid about 30 seconds | `expiresAt` is a unix second. After it the order is dead; ask again. |
| Fills once, in full | Each order has its own nonce. A second fill of the same order reverts. No partial fills. |
| Exact | The fill delivers `buyAmount` or reverts. There is no slippage parameter and no last look. |

`maxFirmSize` in every quote is the largest amount the maker can pay right now at this rate, in both
tokens. It is a fact about the present, not a promise about the future. To see it before asking, read
[`GET /levels`](https://staging.docs.aile.tech/api-reference/get-levels).

## Who does what

| Part | Run by | Role |
| - | - | - |
| Gateway (`/api/base/v1`) | Aile | Checks the caller (API key, wallet screening, venue pause), relays the request to the makers, stores the quote, indexes fills from chain logs. Holds no keys that can move funds. |
| Quote server | Each market maker, on its own infrastructure | Prices from a reference feed plus its spread, sizes from the wallet balance and allowance it actually has, signs the order with its own key. |
| Order protocol | Public contract on Base | The only contract a swap calls. Verifies the signature, the taker, the expiry and the nonce, then moves both tokens. See [Contracts](https://staging.docs.aile.tech/reference/contracts.md). |
| Taker | You | Approves the order protocol once, sends the fill, receives the bought token. |

The fill is sent by your wallet straight to the order protocol. No Aile server is in that path, and no
Aile server can block, delay or alter a fill once the quote is signed.

## What the chain enforces, and what it does not

On chain, the order protocol checks that the signature recovers to the maker, that `msg.sender` is the
pinned taker, that the order has not expired and that its nonce is unspent, then transfers both tokens at
the signed amounts. If any step fails, the whole transaction reverts and nothing moves.

The chain does **not** check the price. The rate is whatever the maker signed; that is what "firm" means.
The maker prices off chain from a Chainlink FX feed (CAD, EUR, SGD, IDR, GBP, TRY against USD) plus its
spread, and `referenceRate` in the quote tells you the mid it used, so you can judge the rate before you
send.

## Pause

The owner of the order protocol can pause it. A paused protocol refuses every new fill and `GET /quote`
answers `503 kill-switch`. Pausing never moves funds and cannot change an order; it only stops new fills
while an incident is handled.

## Reading the result

A fill emits `OrderFilled(orderHash, remainingAmount)` with `remainingAmount` 0. The gateway's indexer
reads it within a few seconds and marks the quote filled; your receipt's `Transfer` logs tell you the same
sooner. If the fill reverts with `OrderExpired`, the 30 seconds passed: request a new quote.
`BitInvalidatedOrder` means this quote was already filled.


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