API REFERENCE

Rolthe API reference
RESTful and straightforward

Automate bulk rentals and receive real-time order status callbacks, on a service that runs around the clock.

Protocol
RESTful + JSON
Authentication
HMAC-SHA256
Rate limit
100 req/min

Overview

Automate bulk rentals and receive real-time order status callbacks, on a service that runs around the clock.

The Rolthe API is split into two groups by business domain, sharing one authentication scheme and one set of error codes. Read authentication and error codes here first, then move on to the endpoint pages.

Authentication

The API authenticates with an HMAC-SHA256 signature. Every request carries these headers:

HeaderDescription
X-API-KeyThe API key created in your console
X-TimestampUnix timestamp in seconds
X-SignatureHMAC-SHA256 signature (see below)
Content-Typeapplication/json

Signature algorithm

The signature is an HMAC-SHA256 of the message using your API secret. The message is the API key, the timestamp, and — for POST — the request body as compact JSON with keys sorted.

Signing rule
message = API_KEY + TIMESTAMP + [sorted_compact_json_body]
signature = HMAC-SHA256(message, API_SECRET).hex()

# GET requests have no body, so the message is only the first two parts
# For POST, sort the body by key and strip whitespace before signing

Timestamp check

The server validates the timestamp: your request time may not differ from server time by more than 60 seconds. Keep your clock in sync.

Endpoints

Base URL
https://api.rolthe.com/v1

Endpoint groups

ServicePrefixDescription
Energy service/energy/*Energy purchase, price lookup, order management
TRON monitoring/tron-monitor/*Address monitoring, transaction callbacks

Error codes

The error codes the API commonly returns:

HTTPError codesDescription
400INVALID_PARAMSInvalid request parameters
401UNAUTHORIZEDNot authenticated, or the API key is invalid
403FORBIDDENInsufficient permission, or the signature is invalid
404NOT_FOUNDResource not found
429RATE_LIMITEDRate limit exceeded (100 requests per minute by default)
500INTERNAL_ERRORInternal server error

Error response shape

4xx / 5xx
{
  "success": false,
  "code": "INVALID_PARAMS",
  "message": "target_address is required",
  "data": null
}

Code samples

Node.js

EnergyAPIClient
const crypto = require('crypto');
const axios = require('axios');

class EnergyAPIClient {
  constructor(apiKey, apiSecret, baseUrl = 'https://api.rolthe.com/v1') {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.baseUrl = baseUrl;
  }

  // Keys must be sorted before signing — the server sorts too, and a different order breaks the signature
  sortObject(obj) {
    return Object.keys(obj).sort().reduce((sorted, key) => {
      sorted[key] = typeof obj[key] === 'object' && obj[key] !== null
        ? this.sortObject(obj[key])
        : obj[key];
      return sorted;
    }, {});
  }

  sign(timestamp, body = null) {
    let message = `${this.apiKey}${timestamp}`;
    if (body) message += JSON.stringify(this.sortObject(body));
    return crypto.createHmac('sha256', this.apiSecret).update(message).digest('hex');
  }

  async request(method, endpoint, data = null) {
    const timestamp = Math.floor(Date.now() / 1000);
    const headers = {
      'X-API-Key': this.apiKey,
      'X-Timestamp': timestamp.toString(),
      'X-Signature': this.sign(timestamp, data),
      'Content-Type': 'application/json'
    };
    const url = `${this.baseUrl}${endpoint}`;
    const response = method === 'GET'
      ? await axios.get(url, { headers })
      : await axios.post(url, data, { headers });
    return response.data;
  }
}

const client = new EnergyAPIClient('your_api_key', 'your_api_secret');
client.request('GET', '/energy/account').then(console.log);

cURL

cURL example
#!/bin/bash
API_KEY="TY_xxxxxxxx"
API_SECRET="sk_xxxxxxxx"
TIMESTAMP=$(date +%s)

# Signing a GET request (no body)
MESSAGE="${API_KEY}${TIMESTAMP}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

curl -X GET "https://api.rolthe.com/v1/energy/account" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Signature: ${SIGNATURE}"

Endpoint reference

The Energy API exposes nine endpoints, from quote to reconciliation. Three of them are documented in full below; the rest follow as a list.

GET/energy/account

Get account

Balance, available balance and related figures for the current account.

Response example

200 OK
{
  "success": true,
  "code": 10000,
  "message": "ok",
  "data": {
    "user_id": 1,
    "username": "user@example.com",
    "balance": 100.5,
    "available_balance": 95.5,
    "frozen_amount": 5.0,
    "pending_orders_count": 2,
    "recharge_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW"
  }
}

Response fields

FieldTypeDescription
balancenumberTotal account balance (TRX)
available_balancenumberAvailable balance (TRX)
frozen_amountnumberFrozen amount (held by in-flight orders)
recharge_addressstringDeposit address
GET/energy/price

Get price

The current energy rental price.

Request parameters

ParameterTypeRequiredDescription
rent_timenumberNoRental duration in hours. Accepted values: 0.08 (5 min), 0.17 (10 min), 1 (1 hour)

Response example

200 OK
{
  "success": true,
  "code": 10000,
  "message": "ok",
  "data": {
    "price_65k_1hour": 1.86,
    "price_per_10k": 0.286154,
    "energy_per_transfer": 65000,
    "min_energy": 32000,
    "max_energy": 5000000,
    "rent_time": 1
  }
}
POST/energy/buy

Buy energy

Buy a given amount of energy for a given address.

Request parameters

ParameterTypeRequiredDescription
target_addressstringYesThe TRON address that receives the energy
energy_amountnumberNoAmount of energy, 65000 by default
rent_timenumberNoRental duration in hours, 1 by default

Request example

POST /energy/buy
curl -X POST "https://api.rolthe.com/v1/energy/buy" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Timestamp: 1704067200" \
  -H "X-Signature: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "target_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW",
    "energy_amount": 65000,
    "rent_time": 1
  }'

Response example

200 OK
{
  "success": true,
  "code": 10000,
  "message": "ok",
  "data": {
    "order_id": "EN240102ABC123",
    "tx_hash": "abc123...",
    "cost": 3.0
  }
}

Other endpoints

  • POST /energy/auto-buy — Auto buy
  • POST /energy/buy-count — Buy by transaction count
  • POST /energy/smart-buy — Smart buy
  • POST /energy/check-address — Check address
  • POST /energy/activate — Activate address
  • GET /energy/order/{order_id} — Get order