Guides
How value moves through OnLink, in plain terms: the two flows available today, the four stages every order goes through, and how to tell which flow you need.
A flow is one job, done end to end. Your user holds USDT and wants Kenyan shillings, or holds shillings and wants USDT, and you want that to happen inside your own product. You ask OnLink for a rate, tell us what to do, move the money in, and we move the converted money out and tell you when it is finished.
Two flows are available today, and they are mirror images of each other.
The two flows
flowchart TB
%% Defined buy-first on purpose: mermaid lays out disconnected subgraphs in
%% reverse definition order, so this renders Sell on the left and Buy on the right.
subgraph buy [Buy USDT with KES]
direction TB
B1[Shillings your payer holds] -->|paid by M-PESA or bank transfer| B2((OnLink))
B2 -->|sent as USDT| B3[Your registered wallet address]
end
subgraph sell [Sell USDT, receive KES]
direction TB
S1[USDT you hold] -->|sent to your deposit address| S2((OnLink))
S2 -->|paid out in shillings| S3[Your registered bank account]
endSell USDT, receive KES. You send USDT to a deposit address we give you. When it arrives, we pay the equivalent in shillings into a bank account you have registered with us.
Buy USDT with KES. Your payer sends shillings, by M-PESA or bank transfer, to a collection account issued to you. When the payment arrives, we send the equivalent in USDT to a wallet address you have registered and confirmed.
In both flows the money lands with you, not with your end user. We settle to an account or address that belongs to your partner account; passing the value on to your user is your part of the job.
Every order goes through the same four stages
Whichever direction you are moving value in, an order passes through the same four stages in the same sequence.
flowchart LR
Q[1. Quote<br/>lock a rate] --> O[2. Order<br/>get instructions] --> F[3. Fund<br/>money moves in] --> S[4. Settle<br/>money moves out]Quote — lock a rate. You ask for a quote and receive a rate that holds for a short window. Every amount downstream comes from that rate, so you can show your user exactly what they will get before anyone commits money. A quote is spent by the order that uses it. If your user hesitates past the window, you take a new one and show the new amounts.
Order — get the instructions. You create an order against the quote. The reply tells you where the money should go: a deposit address for USDT on a sell, or the account details your payer should pay on a buy. At this point the order exists, but nothing has happened to the money yet.
Fund — money moves in. On a sell, you send the USDT and tell us which on-chain transaction was yours. On a buy, your payer sends the shillings. Once we have matched the incoming money to your order, we tell you so with a webhook. Until then, we cannot tell "not arrived" from "arrived, but we do not know which order it is for" — which is why the matching details on each flow page matter.
Settle — money moves out. We convert at the locked rate and pay out: shillings to your registered bank account, or USDT to your registered wallet address. A final webhook tells you the order settled — or, less often, that it will not.
Which flow do you need?
| Sell USDT, receive KES | Buy USDT with KES | |
|---|---|---|
| Your user wants | Kenyan shillings, and has USDT | USDT, and has Kenyan shillings |
| Who sends the money in | You, from a USDT wallet | Your payer, by M-PESA or bank transfer |
| Where it goes in | Your OnLink deposit address | Your OnLink collection account |
| What comes out | Kenyan shillings | USDT on Tron |
| Where it lands | A bank account registered to you | A wallet address you registered and confirmed |
| What ties the money to the order | The transaction hash you attach after sending | The amount and the account paid on M-PESA, or the reference in a bank narration |
| Set up before your first order | A registered payout bank account | A registered and confirmed wallet address |
What you need in place first
- API credentials. We issue them. See API credentials.
- Somewhere for the money to land. For sell orders, a bank account registered against your partner account. For buy orders, a wallet address you register and then confirm. Neither can be added in the middle of an order.
- A way to hear the result. An HTTPS endpoint for webhooks. You can start by polling an order's status instead, but the webhook is the completion signal your integration should be built around.
True of both flows
- Settlement happens after the call. Creating an order does not complete it. Your product needs a state for an order that is neither done nor failed. This is the one idea that decides how you build; read Asynchronous settlement before you design anything.
- The rate is locked, then spent. Nothing re-prices silently. An expired quote is refused, never quietly replaced with a fresh rate you did not see.
- An order has a funding window. You have 24 hours from creation to fund an order. An order that is never funded expires; an order that has been funded does not.
- Every order ends one of three ways. Settled, rejected or expired. A rejected order means your funds are with us and the order will not proceed; the resolution is a conversation with us, so have a path for it in your product. See Who does what.
- One currency pair, one chain. Kenyan shillings against USDT, and USDT moves on Tron only. Sending on any other network loses the funds. See Rails.
Ready to build
Each flow has its own page with the exact requests, responses, matching rules and the errors worth handling.