Skip to main content
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.

​
Shape of the integration

  • 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: Treat a reason you do not know as “no quote”. The full list is in the API overview.

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