References and attribution
Which reference identifies which order, per leg — and why the buy leg needs none of them any more.
Only one leg has an attribution problem to solve. The buy leg debits your own balance directly and has nothing external to attribute; the sell leg still needs to match your on-chain deposit to the order it funds.
| Reference | Whose | Where it comes from | Used for |
|---|---|---|---|
partnerReference | Yours | You choose it. | Idempotent order creation, on both legs. |
| transaction hash | Yours | You generate it sending USDT on-chain. | Attributing your USDT deposit, sell only. |
partnerReference makes creation idempotent — reusing it on create returns the
existing order rather than a second one. It never attributes money; there is no
partner-supplied payment left to attribute on either leg.
Buying — nothing to attribute
POST /v1/orders/buy debits your own KES VA balance directly, the instant
the order is created. There is no payer, no rail, and no incoming payment for a
reference to identify — so there is no attribution problem on this leg at all.
kesDebit.status on the order tells you where that debit stands; see
Buy USDT with KES.
Selling — you send USDT
Your Tron deposit address is long-lived and the same for every one of your orders, so it cannot tell two of your orders apart.
The transaction hash is what attributes a deposit. Attach it with
PATCH /v1/orders/{id} after you send. Until you do, nothing links your send to
the order you meant.
A hash is normalised before comparison — case and a leading 0x are ignored,
because those are the same on-chain transaction. One hash attributes exactly one
order.
Reading the hash back
GET /v1/orders/{id} carries the hash you attached, once you have one:
{
"status": "usdt_received",
"txHash": "5d6a3c7b1e4f2a908c6d5b4a3928170f6e5d4c3b2a1908f7e6d5c4b3a2918070"
}txHash is null until you attach one.
Rules of thumb
partnerReferenceis for creation, not attribution. Reusing it on create returns the original order, which is what makes retries safe — it does nothing for attributing money.- One transaction hash funds one order. A hash already attributed to another
order is refused (
409); attaching a different hash to an order that already has one is refused the same way, never an overwrite. - The buy leg has no equivalent rule. There is nothing external to attribute, by design — the debit is yours, from your own balance, the moment you create the order.