Sign in

v2

latestOpenAPI 3.1.0Proprietary2026-07-3191563.2 KB
Orders

Create an order

Pre-flight the recipient, quote the price, and create an order in awaiting_payment. The response payment block tells you exactly how much to send, to which address, and with which memo (the order id). An ineligible recipient returns 422 recipient_ineligible and creates no order (you are never charged for an undeliverable recipient). If eligibility cannot be verified right now (a transient upstream blip), the call returns a retryable 503 and creates no order — retry shortly with the same Idempotency-Key.

post/v1/orders

Headers

Idempotency-Keystring required

A unique key for this create attempt. Retrying with the same key and an identical body returns the original order; a different body is a 409.

Request body

type'stars' | 'premium' required
quantityinteger

Number of Stars. Required when type=stars. Must be in [50, 1000000].

months3 | 6 | 12

Premium subscription length in months. Required when type=premium. Must be 3, 6, or 12.

payment_currency'ton' | 'usdt_ton'

ton = GRAM (TON), usdt_ton = USDT on the TON chain.

callback_urlstring uri

Optional HTTPS URL for the signed order-status webhook. Must be a publicly reachable https:// URL — loopback addresses, private-network hosts, and non-HTTPS schemes are rejected with 400 bad_request.

Example request

{
  "recipient": {
    "username": "durov"
  }
}

Response

Idempotent replay — the same key + body returns the original order.

order_idstring uuid required
status'received' | 'awaiting_payment' | 'paid' | 'reserved' | 'swapping' | 'funding' | 'purchasing' | 'fulfilling' | 'completed' | 'delivered' | 'failed' | 'reversed' | 'expired' | 'held' | 'cancelled' required

Lifecycle status. awaiting_payment is the only cancellable state.

type'stars' | 'premium' required

The product this order is for — echoed back from your request.

quantityinteger nullable required

The number of Stars ordered (when type=stars); null for Premium.

monthsinteger nullable required

The Premium subscription length in months ordered (when type=premium); null for Stars.

expires_atstring date-time required

After this, an unpaid order expires and is cleaned up.

Example response

{
  "quantity": 500,
  "payment": {
    "chain": "ton",
    "amount": "5.757",
    "fee": {
      "subtotal": "13.18",
      "processing_fee": "0.92",
      "total": "14.1",
      "description": "1% swap + 0.5 GRAM gas"
    }
  }
}