Idempotency and references
partnerReference makes order creation retry-safe. X-OnLink-Delivery makes webhook handling retry-safe.
Two identifiers make this API safe to retry. Neither is a header you invent — one is a body field you supply, the other is a header we send.
Creating orders: partnerReference
partnerReference is required on every order create. It is your own handle,
unique across your orders.
Creating twice with the same partnerReference returns the original order.
It does not create a second one, and it is not an error. That is what makes a
timeout safe: if you do not know whether your request landed, send it again with
the same reference.
POST /v1/orders/sell { partnerReference: "your-ref-000123", ... } → 202 order A
POST /v1/orders/sell { partnerReference: "your-ref-000123", ... } → 202 order AReusing a reference across sides is refused: a reference that already names a
sell order cannot be used to create a buy order, and the reverse. That is a
409.
Store the reference and the order id before you move funds
There is no list-orders endpoint. GET /v1/orders/{id} is the only read, so an
order id you never recorded cannot be found afterwards by searching.
Write partnerReference and orderId down durably before sending USDT or
instructing a payer. If you lose an id, re-POST with the same
partnerReference — the response carries the existing order, which is the
recovery path.
Use an identifier from your own system: your internal order id, or a UUID you store beside it. Do not use a timestamp or a counter that could repeat.
Handling webhooks: X-OnLink-Delivery
Every webhook carries X-OnLink-Delivery, and the same delivery keeps the same
id across every retry. Record the ids you have processed. If one arrives twice,
acknowledge with a 2xx and do nothing else.
Duplicates are normal. A duplicate means your acknowledgement did not reach us — not that the event happened twice.
Payment attribution is separate
paymentReference and the transaction hash attribute money to an order; the
two identifiers above make requests safe to repeat. They solve different
problems — see References and attribution.