{ "openapi": "3.1.0", "info": { "title": "GasTank Rental API", "version": "1.0.0", "description": "Balance-funded Energy and Bandwidth rentals. Set your service origin in the importing tool. All paths preserve their trailing slash. Business examples are illustrative, not live quotes. Delivery is asynchronous." }, "security": [ { "BearerAuth": [] } ], "paths": { "/openapi/v1/rentals/balance/": { "get": { "summary": "Read account balance", "description": "Required API key scope: read or rent.", "tags": [ "Rentals" ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "network": "mainnet", "asset": "TRX", "balance_sun": "5000000", "frozen_sun": "1680000", "available_sun": "3320000" } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "getBalance", "parameters": [ { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ] } }, "/openapi/v1/rentals/quotes/": { "post": { "summary": "Create a rental quote", "description": "Required API key scope: rent.", "tags": [ "Rentals" ], "responses": { "201": { "description": "Success.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "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" } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "Invalid JSON, unsupported body field or invalid parameters. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "combined": { "summary": "Energy and Bandwidth", "value": { "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "energy_amount": 65000, "bandwidth_amount": 350, "duration_seconds": 600 } }, "energyOnly": { "summary": "Energy only", "value": { "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "energy_amount": 65000, "duration_seconds": 600 } }, "bandwidthOnly": { "summary": "Bandwidth only", "value": { "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "energy_amount": 0, "bandwidth_amount": 350, "duration_seconds": 600 } } } } } }, "operationId": "createQuote", "parameters": [ { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ] } }, "/openapi/v1/rentals/quotes/{quote_id}/": { "get": { "summary": "Read your quote", "description": "Required API key scope: read or rent.", "tags": [ "Rentals" ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "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" } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Record not found or not owned by this account. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ], "operationId": "getQuote" } }, "/openapi/v1/rentals/orders/": { "post": { "summary": "Submit or recover an order", "description": "Required API key scope: rent.", "tags": [ "Rentals" ], "responses": { "202": { "description": "Accepted, not proof of resource delivery.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "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 } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "Invalid JSON, unsupported body field or invalid parameters. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Insufficient balance or order conflict. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" }, "example": { "quote_id": "11111111-1111-4111-8111-111111111111", "max_total_sun": "1680000" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Persist before submitting. Same key and unchanged payload recover the original order across keys in the same account/network." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ], "operationId": "createOrder" }, "get": { "summary": "List or find your orders", "description": "Required API key scope: read or rent.", "tags": [ "Rentals" ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" }, "example": { "results": [ { "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 } ], "next_cursor": null } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "400": { "description": "Invalid JSON, unsupported body field or invalid parameters. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "idempotency_key", "in": "query", "schema": { "type": "string" }, "description": "Filter by the original persisted key. Response remains a page; no match returns an empty results array." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 4096 }, "description": "Pass the previous next_cursor unchanged." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ], "operationId": "listOrders" } }, "/openapi/v1/rentals/orders/{order_id}/": { "get": { "summary": "Read delivery and fee settlement", "description": "Required API key scope: read or rent.", "tags": [ "Rentals" ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "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 } } } }, "401": { "description": "Missing or invalid active Bearer credential. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "405": { "description": "Unsupported method. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded; wait for Retry-After. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "const": "60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Rental, pricing, capacity, chain RPC or limiter unavailable. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Unexpected failure. An order may already be committed; recover using the original idempotency key. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Record not found or not owned by this account. Infrastructure or unmatched URL errors may have other bodies.", "headers": { "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional response language, for example en or zh-hans." } ], "operationId": "getOrder" } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "SunAmount": { "type": "string", "pattern": "^[0-9]+$", "description": "Non-negative integer SUN encoded as a decimal string. 1 TRX = 1000000 SUN. Use integer arithmetic." }, "Balance": { "type": "object", "required": [ "network", "asset", "balance_sun", "frozen_sun", "available_sun" ], "properties": { "network": { "type": "string", "enum": [ "mainnet", "nile" ] }, "asset": { "type": "string", "const": "TRX" }, "balance_sun": { "$ref": "#/components/schemas/SunAmount" }, "frozen_sun": { "$ref": "#/components/schemas/SunAmount" }, "available_sun": { "$ref": "#/components/schemas/SunAmount" } }, "examples": [ { "network": "mainnet", "asset": "TRX", "balance_sun": "5000000", "frozen_sun": "1680000", "available_sun": "3320000" } ] }, "QuoteRequest": { "type": "object", "required": [ "receiver_address", "energy_amount", "duration_seconds" ], "properties": { "receiver_address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "Base58Check TRON resource receiver. A valid checksum is required." }, "energy_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "bandwidth_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807, "default": 0 }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Seconds. Deployment minimum and available pricing apply." } }, "additionalProperties": false, "anyOf": [ { "properties": { "energy_amount": { "minimum": 1 } } }, { "required": [ "bandwidth_amount" ], "properties": { "bandwidth_amount": { "minimum": 1 } } } ], "description": "At least one resource must be positive. Positive Energy must obey deployment limits. Bandwidth-only is supported by this Bearer API.", "examples": [ { "receiver_address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "energy_amount": 65000, "bandwidth_amount": 350, "duration_seconds": 600 } ] }, "Quote": { "type": "object", "required": [ "id", "receiver_address", "energy_amount", "bandwidth_amount", "duration_seconds", "rental_fee_sun", "bandwidth_fee_sun", "activation_fee_sun", "total_sun", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "receiver_address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "Base58Check TRON resource receiver. A valid checksum is required." }, "energy_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "bandwidth_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "duration_seconds": { "type": "integer", "minimum": 1 }, "rental_fee_sun": { "$ref": "#/components/schemas/SunAmount" }, "bandwidth_fee_sun": { "$ref": "#/components/schemas/SunAmount" }, "activation_fee_sun": { "$ref": "#/components/schemas/SunAmount" }, "total_sun": { "$ref": "#/components/schemas/SunAmount" }, "expires_at": { "type": "string", "format": "date-time" } }, "examples": [ { "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" } ] }, "OrderRequest": { "type": "object", "required": [ "quote_id", "max_total_sun" ], "properties": { "quote_id": { "type": "string", "format": "uuid" }, "max_total_sun": { "oneOf": [ { "type": "string", "pattern": "^[0-9]*[1-9][0-9]*$" }, { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 } ], "description": "Authorized spending ceiling in SUN, at most 9223372036854775807. Decimal string recommended to avoid precision loss." } }, "additionalProperties": false, "examples": [ { "quote_id": "11111111-1111-4111-8111-111111111111", "max_total_sun": "1680000" } ] }, "FeeSettlement": { "type": "object", "required": [ "amount_sun", "status", "status_label" ], "properties": { "amount_sun": { "$ref": "#/components/schemas/SunAmount" }, "status": { "type": "string", "enum": [ "held", "charged", "released", "not_applicable" ] }, "status_label": { "type": "string", "description": "Localized display text; do not use for control flow." } } }, "Delivery": { "type": "object", "required": [ "resource", "amount", "status", "delegate_txid", "recall_txid" ], "properties": { "resource": { "type": "string", "enum": [ "ENERGY", "BANDWIDTH" ] }, "amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "status": { "type": "string", "enum": [ "preparing", "pending", "delegated", "undelegating", "undelegated", "failed" ] }, "delegate_txid": { "type": [ "string", "null" ] }, "recall_txid": { "type": [ "string", "null" ] } }, "examples": [ { "resource": "BANDWIDTH", "amount": 350, "status": "delegated", "delegate_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "recall_txid": null } ] }, "Order": { "type": "object", "required": [ "id", "status", "status_label", "receiver_address", "energy_amount", "bandwidth_amount", "duration_seconds", "total_sun", "rental", "bandwidth", "activation", "deliveries", "created_at", "starts_at", "expires_at", "delegate_txid", "notice" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "created", "ready", "delegating", "partial", "active", "expiring", "expired", "undelegating", "closed", "failed", "cancelled" ] }, "status_label": { "type": "string" }, "receiver_address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "Base58Check TRON resource receiver. A valid checksum is required." }, "energy_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "bandwidth_amount": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "duration_seconds": { "type": "integer", "minimum": 1 }, "total_sun": { "$ref": "#/components/schemas/SunAmount" }, "rental": { "$ref": "#/components/schemas/FeeSettlement" }, "bandwidth": { "$ref": "#/components/schemas/FeeSettlement" }, "activation": { "$ref": "#/components/schemas/FeeSettlement" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "created_at": { "type": "string", "format": "date-time" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "delegate_txid": { "type": [ "string", "null" ] }, "notice": { "type": [ "string", "null" ] } }, "examples": [ { "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 } ] }, "OrderPage": { "type": "object", "required": [ "results", "next_cursor" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor, or null after the final page." } }, "examples": [ { "results": [ { "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 } ], "next_cursor": null } ] }, "ApiError": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string", "description": "Localized display text." }, "request_id": { "type": "string" } }, "examples": [ { "code": "order_conflict", "message": "The request conflicts with an existing order.", "request_id": "33333333-3333-4333-8333-333333333333" } ] } } } }