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

# Apps and wallets

> Integrating Aile when the end user's wallet sends the fill: who the taker is, where the key lives, and how to show the price.

This page is for products where an end user's wallet (an EOA or a smart account) sends the fill: wallets,
neobank apps, remittance apps, treasury tools. If your own contract sends the fill, read
[Aggregators and routers](https://staging.docs.aile.tech/integrate/aggregators-and-routers.md).

## Shape of the integration

```mermaid theme={null}
flowchart LR
    U[User's wallet] -- 1 asks a price --> B[Your backend]
    B -- 2 GET /quote, API key, taker = user --> A[Aile gateway]
    A -- 3 signed order + calldata --> B
    B -- 4 fill.to / data / value --> U
    U -- 5 approve + fillOrder --> C[Order protocol on Base]
```

* **The API key stays on your backend.** It identifies your company, has its own request budget, and
  every quote is attributed to it. Never ship it in a client.
* **`taker` is the user's address.** The order is pinned to it: only that address can fill, and the bought
  token is paid to it. Ask for the quote after the user has connected a wallet.
* **Your client sends two transactions at most:** an ERC-20 `approve` of `fill.allowanceTarget` for the
  sold token (once, if you approve a large amount), then the fill with `fill.to`, `fill.data` and
  `fill.value` exactly as returned.

## Showing a price before the quote

Call `GET /levels` (no key needed, cacheable for a few seconds) while the user types. For the direction
they chose it gives `maxFirmSize` (the largest size now), the price after the spread
(`buyAmount / sellAmount`) and the `reference` mid. Show the rate and the reference next to each other;
that is what the Aile web app does.

Ask for the quote only when the user is ready to send: a quote holds the maker's inventory for 30 seconds,
and each key has a request budget.

## Timing

A quote lives about 30 seconds. Wallet confirmation dialogs eat into that, so:

* Request the quote right before you hand the transaction to the wallet, not when the screen opens.
* Do the `approve` first, as its own step, before you request the quote.
* If fewer than about 10 seconds remain when the user confirms, let the quote expire and request a new
  one rather than risk `OrderExpired`.

## Exact-in or exact-out

Pass `sellAmount` to fix what the user pays, or `buyAmount` to fix what they receive, never both. The
other side comes back exact, and the fill delivers it or reverts.

## Handling refusals

`GET /quote` answers a problem with a `reason`. The ones a wallet product meets most:

| Reason | Status | What to show |
| - | - | - |
| `amount-too-small`, `over-size` | 400 | The detail names the minimum or maximum. Suggest that size. |
| `no-maker`, `maker-unavailable`, `no-price`, `maker-underfunded`, `maker-allowance` | 503 | "Not available right now." Try again later; check `/levels`. |
| `kill-switch` | 503 | Trading is paused. |
| `address-refused` | 403 | This wallet cannot be quoted. |
| `screening-unavailable` | 503 | The wallet check could not run; try again. |

Treat a `reason` you do not know as "no quote". The full list is in the
[API overview](https://staging.docs.aile.tech/api-reference/overview.md#problems).

## Confirmation

The receipt is the confirmation: the `Transfer` log of the bought token to the user's address equals
`buyAmount`. `GET /orders/{orderHash}` shows the gateway's view a few seconds later, once the fill is
indexed from chain logs; it is useful for a history screen, not for the confirmation itself.


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