On-Ramp / Off-Ramp
On-ramp buys crypto with fiat, delivered on-chain straight to a wallet address. Off-ramp sells crypto for fiat, paid out to a recipient bank account. Both move crypto on-chain per order — unlike Scan-to-Pay and Cashout, neither touches your crypto fund.
The sequence
quote → create → pay in or send → poll or webhook
Quote — on-ramp ·
off-ramp. Previews the crypto amount, the fiat
amount, and the fee. Send either cryptoAmount or fiatAmount, never both — the quote returns the
other side.
Create — on-ramp ·
off-ramp. The response comes back immediately
with status PROCESSING and the instructions for the next step — a fiat payment for on-ramp, a
crypto deposit for off-ramp.
Pay in or send. An on-ramp order returns payment: the bank details and, where the provider
supports it, a QR code to pay the fiat with. An off-ramp order returns deposit: the address and
network to send the crypto to, plus a memo when the network needs one. Send the exact amount the
order specifies, before its expiresAt passes — neither leg is reserved past that window.
Track — on-ramp ·
off-ramp, or a
webhook. On-ramp and off-ramp orders do not take a webhookSecretKey:
register your endpoint once in the AliX management portal, and every order fires it automatically.
Status
| Status | Meaning |
|---|---|
PROCESSING | The order exists and is waiting on the fiat payment or crypto deposit, or the resulting delivery/payout is in flight. Not terminal. |
SUCCESS | On-ramp: the crypto has landed in the wallet address. Off-ramp: the recipient has been paid. Terminal. |
FAILED | The order did not complete. Terminal. |
Only SUCCESS and FAILED are terminal, and only terminal states fire a webhook.
Amounts and fees
Every quote and order carries a fees breakdown: processingFee, AliX's service fee, and
systemFee, which includes the network fee. The two directions apply it in opposite directions —
an on-ramp fiatAmount is what you pay, fees included; an off-ramp fiatAmount is what gets paid
out, fees already deducted. Either way, the response always returns both the crypto and fiat side,
so you never compute one from the other.
Creating an order re-prices at the current rate, so the cryptoAmount, fiatAmount, and fees on the
order can come back slightly different from what the quote showed. Re-quote right before you show a
user a final number, and once an order exists, read its amounts rather than the quote's.
Currencies, networks, and limits
cryptoCurrency defaults to USDT if omitted. network is required on every call — it fixes the
network fee and, for on-ramp, where the crypto is delivered. Discover what a fiat currency supports
before you quote: on-ramp ·
off-ramp. Each crypto currency
carries its own minAmount / maxAmount in crypto, and each of its networks carries a network fee
and whether that network needs a memo. Outside those bounds the quote or order fails with
BUY_AMOUNT_BELOW_MIN / BUY_AMOUNT_ABOVE_MAX on-ramp, or SELL_AMOUNT_BELOW_MIN /
SELL_AMOUNT_ABOVE_MAX off-ramp.
Collecting the off-ramp recipient
An off-ramp order pays out to recipient, and its shape depends on the fiat currency's provider —
call destination-fields for the fiat
currency first, and build the recipient form from what it returns rather than assuming
bankCode / accountNumber / accountName. accountName is optional for VND, and required for
every other fiat currency.
orderId is your idempotency key
Same rule as Scan-to-Pay and Cashout: you choose orderId, reusing one is rejected with
DUPLICATE_TRANSACTION_ID (HTTP 409), and a request that times out should be retried with the same
id rather than a new one. See Scan-to-Pay & Cashout for the
full pattern.