TRONowDefine one business order before making a request
Create a unique client_order_id in your own database for the business operation. Store the requested Energy, duration and receiver alongside it before contacting the API. Use a uniqueness constraint so concurrent workers cannot create two local records for the same operation. This article describes a reference integration, not production results from a named customer.
Quote the request you will actually submit
Call GET /prices/quote for the exact resource amount and duration. The response contains price_sun, currency and priced_at; store price_sun as an integer SUN string and use it as the current reference price. POST /orders recalculates and locks the order price when accepted, so no quote identifier is submitted.
Sign the actual serialized request
Keep signing credentials on your server. Build the request body once and sign those exact bytes according to the downloadable contract and client. Do not sign one JSON representation and send a different one. Redact credentials and authentication headers from application logs.
Persist the idempotency key too
POST /orders requires an 8–128 character visible-ASCII Idempotency-Key in addition to client_order_id. Persist the key and exact request bytes before submission. For a retry of an uncertain creation, keep both unchanged and generate a fresh timestamp, nonce and signature. Merchant order creation does not return QUOTE_EXPIRED. The public Skill describes webhook verification; address activation has no webhook and must be queried.
Handle an uncertain order response
Submit POST /orders with the original client_order_id. If the connection times out, first query GET /orders?client_order_id={client_order_id}. A received order should be tracked, not replaced with a fresh identifier. If a retry is appropriate, retain the identifier and request semantics. Treat an idempotency conflict as a business error requiring inspection.
Separate accepted, pending and completed
Save the platform order ID and returned status. Update local fulfillment state only from the documented terminal result and delivery evidence. Transport success alone is not proof of delegation. Preserve failed or review states so staff can resolve an exception instead of silently looping or charging twice.
Verify and deduplicate callbacks
Follow the webhook verification rules in the contract. Reject invalid signatures; deduplicate the callback event ID before applying a state change. Acknowledge only after the event has been durably stored or processed. Tolerate duplicate delivery and reconcile using the order query API if local and remote states disagree.
Bound retries and preserve an audit trail
Use timeouts, capped exponential backoff and a finite retry budget. Record client_order_id, platform order ID, status transitions and non-secret error codes. Use a queue or scheduled reconciliation in your application for unresolved orders instead of aggressive polling in the browser.
Test the failure paths before production
Verify insufficient balance, quote mismatch, duplicate business identifiers, timeout after acceptance, duplicate callbacks and invalid signatures in a controlled setup. Confirm that each case creates at most one intended business order and an explainable local record. The linked client and schema provide the actual wire contract; this article does not promise an SDK for every language.