API integration guide

Use the console to recharge and create an API key, then call /openapi/v1/rentals/. Use the deployment network shown in the console; API orders share the same balance and settlement logic as browser rentals.

1. Choose the network

Nile test TRX and mainnet TRX are separate assets. Your account, deposit address and API Key must belong to the same network as the service. The service URL selects the deployment; no network request header is required. Never send mainnet funds to a test environment.

2. Open an account and deposit

The console provides a dedicated TRX deposit address and QR code. Deposit using the displayed network. Funds enter your account after chain confirmation; an unconfirmed transfer is not spendable.

Deposits are credited in full. Consolidating physical funds does not change your customer balance. The receiving wallet's on-chain balance is not your account balance.

3. Create a key and read your balance

Create a read-only or rental key in the console. Choose the default lifetime or Never expires; either type can be revoked. Save the complete key when created; it cannot be displayed again. Keep it on your server, outside frontend code and version control. Revoke a compromised key.

The authentication header is Authorization: Bearer YOUR_API_KEY. The API uses integer SUN amounts encoded as decimal strings: "5000000" means 5 TRX. Available balance is total balance minus frozen funds.

4. Quote and place an order

Request a quote using the Energy receiver, amount and rental duration. Check the rental fee, any activation fee and expiry. Submit the quote with a maximum total price, a persisted idempotency key.

The receiver is the wallet that will use the Energy. Energy requirements vary with the transaction; a transfer-count estimate is not a guarantee.

See the API reference for supported fields, permissions, rate limits and response states.

5. Track delivery and charges

An accepted order is not proof of delivery. Poll the original order until delivery is confirmed or failure is definitive. After a request timeout, query or retry the original request with the same idempotency key and unchanged payload.

Account entries contain deposits, actual charges and manual balance adjustments. Freezes and releases appear in order settlement details, not as income or expense entries. A normal rental expiry does not reverse the rental charge.

Automatic withdrawals and instant refunds are not part of the initial API. Refund terms will be published before that process opens.

curl example (Bash)

Replace all uppercase placeholders. Use your real HTTPS service URL outside local development.

# Load real keys through your secret manager; do not commit them or paste them into shell history.
export OPENAPI_BASE_URL="YOUR_OPENAPI_BASE_URL"
export GASTANK_API_KEY="YOUR_API_KEY"

curl --fail-with-body "${OPENAPI_BASE_URL}balance/" \
  -H "Authorization: Bearer $GASTANK_API_KEY"

curl --fail-with-body "${OPENAPI_BASE_URL}quotes/" \
  -H "Authorization: Bearer $GASTANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"receiver_address":"YOUR_TRON_ADDRESS","energy_amount":65000,"duration_seconds":600}'

# Read the quote, authorize the amount and persist the request ID before this POST.
curl --fail-with-body "${OPENAPI_BASE_URL}orders/" \
  -H "Authorization: Bearer $GASTANK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_PERSISTED_REQUEST_ID" \
  -d '{"quote_id":"QUOTE_UUID","max_total_sun":"AUTHORIZED_TOTAL_IN_SUN"}'

curl --fail-with-body "${OPENAPI_BASE_URL}orders/?idempotency_key=YOUR_PERSISTED_REQUEST_ID" \
  -H "Authorization: Bearer $GASTANK_API_KEY"

Poll orders/ORDER_UUID/ for delivery. After 429, wait for Retry-After. After an ambiguous order response, query the original idempotency key before retrying; there is no automatic retry loop here.

Optional Bandwidth

The shared rental form defaults to Energy only. Enable “Also rent Bandwidth” and enter an explicit quantity when needed; API clients use bandwidth_amount. Bandwidth has its own price and shares the Energy rental duration. Delivery and charges are confirmed separately. Partial delivery charges only successful components; failed balance components are released, and anonymous payment remainders require manual support handling. Unknown transactions remain pending verification.

For API-only Bandwidth rental, send energy_amount: 0 and a positive bandwidth_amount; both cannot be zero. Website checkout still requires Energy. The same Bandwidth pricing applies; the Energy fee is zero and not applicable. Check the BANDWIDTH entry in deliveries for delivery.