Rental API reference

Look up each operation below, then expand its shared response schema. All paths are relative to OPENAPI_BASE_URL, which includes /openapi/v1/rentals/. Preserve the trailing slash.

Download OpenAPI 3.1 JSON · Integration guide

The JSON describes full API paths and has no production server address. Set the service origin when importing it into Postman or another OpenAPI tool. Examples show structure only; amounts, availability and expiry must come from a fresh quote.

Conventions

Keys are created in the console. The complete key is shown once; keep it on your server. Revocation blocks new requests without cancelling accepted orders. Only use HTTPS outside loopback development.

Operations

GET balance/

No request body or query parameters. Returns 200 · Balance for the authenticated account.

{
  "network": "mainnet",
  "asset": "TRX",
  "balance_sun": "5000000",
  "frozen_sun": "1680000",
  "available_sun": "3320000"
}

POST quotes/

Requires rent. Returns 201 · Quote.

{
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600
}

Both resources cannot be zero. Bandwidth-only is supported by this API; website checkout still requires Energy. Both components share the duration and have independent prices. Unavailable requested resources reject the quote; the service does not silently remove a component. A quote neither freezes funds nor reserves inventory.

Additional errors: 400 invalid_request; 403 permission_denied; 503 rentals_unavailable / rental_unavailable.

GET quotes//

Returns 200 · Quote. Only the current account can read it; missing or unowned quotes return 404 not_found. Unused quotes may be removed after more than seven days past expiry. Quotes attached to orders are retained.

POST orders/

Requires rent. Returns 202 · Order, including for an unchanged idempotent replay. 202 is acceptance, not confirmed delivery.

{
  "quote_id": "11111111-1111-4111-8111-111111111111",
  "max_total_sun": "1680000"
}

The ceiling does not override pricing. A quote creates at most one order. Idempotency is shared across keys and browser orders in the same account/network: the same key, quote and ceiling return the original order; changing either field returns 409 order_conflict. There is no external_order_id field.

Additional errors: 400 invalid_request; 403 permission_denied; 409 insufficient_balance / order_conflict; 503 rentals_unavailable / rental_unavailable. Quote expiry and disabling new rentals do not block recovery of accepted requests.

GET orders/

Returns 200 · OrderPage. Results are newest first and include this account’s API and browser balance orders. No match returns results: [], not 404. Invalid pagination returns 400 invalid_request. Cursors are bound to account and resource.

GET orders/?idempotency_key=YOUR_PERSISTED_REQUEST_ID

GET orders//

Returns 200 · Order. Read deliveries and fee settlement to determine the outcome. Missing or unowned orders return 404 not_found.

Response schemas

Balance

Quote

Energy and Bandwidth fees are independently rounded up to 0.01 TRX. The quote confirms all fees; do not calculate your own payable amount from this example.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600,
  "rental_fee_sun": "1400000",
  "bandwidth_fee_sun": "280000",
  "activation_fee_sun": "0",
  "total_sun": "1680000",
  "expires_at": "2026-10-25T08:02:00Z"
}

Order

Example of an accepted order before delivery (202):

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "ready",
  "status_label": "Awaiting delivery",
  "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
  "energy_amount": 65000,
  "bandwidth_amount": 350,
  "duration_seconds": 600,
  "total_sun": "1680000",
  "rental": {
    "amount_sun": "1400000",
    "status": "held",
    "status_label": "Frozen"
  },
  "bandwidth": {
    "amount_sun": "280000",
    "status": "held",
    "status_label": "Frozen"
  },
  "activation": {
    "amount_sun": "0",
    "status": "not_applicable",
    "status_label": "Not applicable"
  },
  "deliveries": [],
  "created_at": "2026-10-25T08:00:00Z",
  "starts_at": null,
  "expires_at": null,
  "delegate_txid": null,
  "notice": null
}

FeeSettlement

If another party activates the address after a positive activation hold, activation becomes released, not not_applicable. For Bandwidth-only orders rental is zero/not_applicable; without Bandwidth, bandwidth is zero/not_applicable.

Delivery

Delegated means the delegation is confirmed; undelegated means recall is confirmed. Do not substitute order states such as active for these per-resource values. One Energy transaction never proves Bandwidth was delivered.

OrderPage

{
  "results": [],
  "next_cursor": null
}

ApiError

{
  "code": "order_conflict",
  "message": "The request conflicts with an existing order.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

Order lifecycle and recovery

After a timeout, 500 or lost response, query orders/?idempotency_key=... first, or retry the identical POST with the same key. Do not generate a new key while the original outcome is unknown. Never treat a single failed component as proof that another uncertain transaction failed. Successful components are charged and recalled at expiry; normal expiry does not refund rent.

Errors and rate limits

These are application errors on matched endpoints. Invalid URL paths, Host rejection, reverse proxies and Cloudflare can return HTML or a different body. Inspect HTTP status and Content-Type before decoding JSON. Successful application responses and handled errors carry X-Request-ID.

Deployments may adjust these limits. Retries consume quota; use a polling interval and backoff rather than tight loops. Limiter failure returns 503. Deposit addresses, key management and financial history remain in the console; there are no withdrawal or refund operations in this API.