Human docs

Energy, Watchlist, and Wallet over HTTP

One HMAC base URL, three product surfaces. Amounts are SUN integers (1 TRX = 1,000,000 SUN). Building an agent or tool? Use the For AI page.

Base URL

https://api.tronscope.io/api/v1

Introduction

Energy Order API - deposit TRX, price Energy, create orders (available on Free). Watchlist API - manage watched addresses (Pro or Enterprise; same quota as the website). Wallet Analyze API - wallet detail, transaction list, counterparties, and tx detail, prepaid per call (overview $0.001, transactions $0.002, counterparties $0.003, tx detail $0.002). Pro includes $2/month, Enterprise $10/month; top up the rest with Stripe.

Energy range is 1,000-50,000,000. Duration is 1H, 1D, 3D, or 30D. Prefer webhooks over polling for order and watchlist events.

Node.js SDK

The official tronscope package signs every request for you (HMAC, timestamp, idempotency key on orders) and ships TypeScript types. Node.js 18+, ESM and CommonJS, no runtime dependencies. Each endpoint below has a Node.js SDK example tab.

bash

npm install tronscope

TypeScript

import { TronScope, TronScopeError } from 'tronscope';

const client = new TronScope({
  apiKey: process.env.TRONSCOPE_API_KEY,       // ts_live_...
  apiSecret: process.env.TRONSCOPE_API_SECRET, // ts_sec_... (server only)
});

try {
  const quote = await client.energyRates({ energyAmount: 65_000, duration: '1H' });
  console.log(quote.priceSun);
} catch (err) {
  if (err instanceof TronScopeError) console.error(err.status, err.code, err.requestId);
  throw err;
}

npm: tronscope GitHub: tronscope/tronscope-node

Failed calls throw TronScopeError with status, code and requestId. Keep the API secret on your server.

Authentication

Every call needs these headers. Timestamp is Unix seconds, ±5 minutes of server time. Don’t reuse a signature inside that window.

http

X-API-Key: ts_live_...
X-Timestamp: 1788123456
X-Signature: ...
X-Idempotency-Key: order-10041

X-Idempotency-Key is required only on POST /energy/orders. Keep the API secret on your server. Never put it in a browser or mobile client.

HMAC signing

Build this string, HMAC-SHA256 it with the API secret, send the hex as X-Signature. Hash the body you actually send - don’t pretty-print JSON and sign that.

text

timestamp
HTTP_METHOD
request_path
canonical_query
SHA256(raw_request_body)

request_path is the path without query, for example /api/v1/energy/orders. canonical_query is sorted key=value pairs, or empty. GET requests hash an empty body.

curl

curl -X POST https://api.tronscope.io/api/v1/energy/orders \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac" \
  -H "X-Idempotency-Key: order-10041" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverAddress": "T...",
    "energyAmount": 65000,
    "duration": "1H"
  }'

Idempotency

POST /energy/orders needs X-Idempotency-Key. Same key and body returns the first order. Same key, different body → IDEMPOTENCY_CONFLICT.

Energy

Deposit prepaid TRX, then create Energy rental orders.

GET/api/v1/balance

Balance

Prepaid TRX available for Energy orders. SUN is canonical (1 TRX = 1,000,000 SUN).

Scope balance:read

Example

curl

curl "https://api.tronscope.io/api/v1/balance" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "asset": "TRX",
  "availableSun": "25000000",
  "available": "25"
}

GET/api/v1/deposit-address

Deposit address

TRON Mainnet address for prepaid TRX. Only TRX is credited.

Scope balance:read

Example

curl

curl "https://api.tronscope.io/api/v1/deposit-address" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "network": "TRON",
  "asset": "TRX",
  "address": "T..."
}

GET/api/v1/energy/rates

Live rate

Price a quantity of Energy for a duration without creating an order.

Scope quotes:read

Query	Type
energyAmount	number	Energy units. Default 65,000.
duration	string	1H, 1D, 3D, or 30D. Default 1H.

Example

curl

curl "https://api.tronscope.io/api/v1/energy/rates?energyAmount=65000&duration=1H" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "energyAmount": 65000,
  "duration": "1H",
  "sunPerUnit": 100,
  "priceSun": "6500000",
  "balanceSun": "25000000"
}

POST/api/v1/energy/orders

Create order

Purchase Energy from prepaid TRX. Pass receiverAddress, energyAmount, and duration. X-Idempotency-Key is required.

Scope orders:write

Body	Type
receiverAddress required	string	TRON Mainnet address that receives Energy — the wallet that will send USDT.
energyAmount required	number	1,000-50,000,000.
duration required	string	1H, 1D, 3D, or 30D.
externalOrderId	string	Your id. Used for lookup by external id.
quoteId	string	Optional existing quote id.

callbackUrl is not accepted. Deliveries go to webhooks configured on the account.
Reuse of the same idempotency key with a different body returns IDEMPOTENCY_CONFLICT.

Example

curl

curl -X POST "https://api.tronscope.io/api/v1/energy/orders" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac" \
  -H "X-Idempotency-Key: order-10041" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverAddress": "TXYZabc123ExampleReceiverAddress",
    "energyAmount": 65000,
    "duration": "1H",
    "externalOrderId": "merchant-order-10041"
  }'

Response

json

{
  "orderId": "en_…",
  "status": "created",
  "energyAmount": 65000,
  "feeSun": 6500000,
  "balanceSun": 18500000
}

GET/api/v1/energy/orders

List orders

Energy orders for this account, newest first.

Scope orders:read

Query	Type
status	string	Optional public status filter.
limit	number	Default 50.

Example

curl

curl "https://api.tronscope.io/api/v1/energy/orders?limit=20" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "items": [],
  "total": 0
}

GET/api/v1/energy/orders/{orderId}

Get order

Fetch a single order by tronscope.io order id.

Scope orders:read

Example

curl

curl "https://api.tronscope.io/api/v1/energy/orders/en_01HEXAMPLEORDERID" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "orderId": "en_…",
  "status": "completed",
  "energyAmount": 65000
}

Watchlist

Same watchlist as the website. Requires Pro or Enterprise; quota still applies.

GET/api/v1/watchlists

List watchlist

Watched addresses for this account, plus categories and watchable assets. Requires Pro or Enterprise.

Scope watchlist:read

Example

curl

curl "https://api.tronscope.io/api/v1/watchlists" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "items": [],
  "categories": ["Ops"],
  "assets": ["TRX", "USDT"]
}

GET/api/v1/watchlists/categories

Add address

Watch a TRON address. Requires Pro or Enterprise. Watchlist quota still applies.

Scope watchlist:write

Body	Type
address required	string	Mainnet T-address.
nickname	string	Optional label.
category	string	Optional category name.
watchedAssets	string[]	e.g. TRX, USDT. Default all watchable.
minNotifyUsd	number	Minimum USD to notify / webhook.

Example

curl

curl -X POST "https://api.tronscope.io/api/v1/watchlists" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TXYZabc123ExampleWatchAddress00",
    "nickname": "Treasury",
    "category": "Ops",
    "minNotifyUsd": 50
  }'

Response

json

{
  "address": "T...",
  "nickname": "Treasury",
  "notificationsEnabled": true
}

PATCH/api/v1/watchlists/{address}

Update entry

Update nickname, category, assets, or notification thresholds. Requires Pro or Enterprise.

Scope watchlist:write

Body	Type
nickname	string	Optional label.
category	string	Optional category.
notificationsEnabled	boolean	Enable or mute alerts.

Example

curl

curl -X PATCH "https://api.tronscope.io/api/v1/watchlists/TXYZabc123ExampleWalletAddress00" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Hot wallet",
    "notificationsEnabled": true
  }'

Response

json

{
  "address": "T...",
  "nickname": "Hot wallet"
}

DELETE/api/v1/watchlists/{address}

Remove address

Stop watching an address. Requires Pro or Enterprise.

Scope watchlist:write

Example

curl

curl -X DELETE "https://api.tronscope.io/api/v1/watchlists/TXYZabc123ExampleWalletAddress00" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "watching": false
}

Wallet

Overview ($0.001), transactions ($0.002), counterparties ($0.003), and tx detail ($0.002). Prepaid USD API balance; Free can pay per call.

GET/api/v1/wallets/{address}

Wallet detail

Balances, tokens, energy, and bandwidth for a Mainnet address. $0.001 per call from the API balance. No transaction history.

Scope wallets:read

HTTP 402 API_CREDIT_REQUIRED when the prepaid API balance is too low.

Example

curl

curl "https://api.tronscope.io/api/v1/wallets/TXYZabc123ExampleWalletAddress00" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "address": "T...",
  "exists": true,
  "accountType": "normal",
  "portfolioUsd": "$1,240.00",
  "trxBalance": "100.5",
  "trxUsd": "$28.40",
  "tokens": [{ "symbol": "USDT", "amount": "50", "usd": "$50.00" }],
  "energy": 65000,
  "energyLimit": 100000,
  "energyUsed": 0,
  "bandwidth": 1200,
  "bandwidthLimit": 1500,
  "stakedTrx": "0",
  "delegatedTrx": "0"
}

GET/api/v1/wallets/{address}/counterparties

Counterparties

Top senders, receivers, frequent peers, and largest relationships for a Mainnet address. $0.003 per call from the API balance.

Scope wallets:read

HTTP 402 API_CREDIT_REQUIRED when the prepaid API balance is too low.

Example

curl

curl "https://api.tronscope.io/api/v1/wallets/TXYZabc123ExampleWalletAddress00/counterparties" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "address": "T...",
  "topSenders": [],
  "topReceivers": [],
  "mostFrequent": [],
  "largestRelationships": []
}

GET/api/v1/wallets/{address}/transactions

Transactions

Recent transfers for a Mainnet address. Newest first. $0.002 per call from the API balance.

Scope wallets:read

Query	Type
limit	number	Max rows. Default 50, max 100.
minUsd	number	Minimum USD value. Default 0.
token	string	Filter by symbol, e.g. USDT or TRX.
direction	string	in or out.

HTTP 402 API_CREDIT_REQUIRED when the prepaid API balance is too low.

Example

curl

curl "https://api.tronscope.io/api/v1/wallets/TXYZabc123ExampleWalletAddress00/transactions?limit=20&minUsd=0" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "address": "T...",
  "minUsd": 0,
  "token": "",
  "direction": "",
  "items": [
    {
      "txid": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef",
      "timestamp": "2026-09-15T00:00:00.000Z",
      "direction": "in",
      "from": "T...",
      "to": "T...",
      "token": "USDT",
      "amount": "50",
      "usdValue": "$50.00",
      "kind": "trc20"
    }
  ]
}

GET/api/v1/tx/{txid}

Transaction detail

Decoded Mainnet transaction: type, parties, asset, amount, fees, energy, and internals. $0.002 per call from the API balance.

Scope wallets:read

HTTP 402 API_CREDIT_REQUIRED when the prepaid API balance is too low.

Example

curl

curl "https://api.tronscope.io/api/v1/tx/a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "X-API-Key: ts_live_YOUR_KEY" \
  -H "X-Timestamp: 1788123456" \
  -H "X-Signature: computed_hmac"

Response

json

{
  "hash": "a1b2…",
  "status": "confirmed",
  "timestamp": "2026-09-15T00:00:00Z",
  "blockNumber": 75000000,
  "confirmations": 12,
  "transactionType": "TransferContract",
  "from": "T...",
  "to": "T...",
  "asset": {
    "symbol": "TRX",
    "name": "TRON",
    "standard": "native",
    "contract": null,
    "decimals": 6
  },
  "amount": "10",
  "feeTrx": "0.345",
  "energyUsed": 0,
  "internals": []
}

Webhooks

Configure the URL in the dashboard and choose event groups. Orders don’t take callbackUrl.

Headers: X-TronScope-Event, X-TronScope-Timestamp, X-TronScope-Signature.

Signature is HMAC-SHA256 of timestamp + "\\n" + raw_body with the webhook secret.

Orders events

deposit.detected, deposit.confirmed, energy.order.created, energy.order.processing, energy.order.completed, energy.order.failed, balance.low.

Watchlist events

watchlist.transfer - fired when a watched address sends or receives a transfer that meets the entry’s asset and USD thresholds.

json

{
  "id": "evt_…",
  "type": "watchlist.transfer",
  "createdAt": "2026-09-15T00:00:00.000Z",
  "data": {
    "address": "T...",
    "txid": "…",
    "token": "USDT",
    "direction": "in",
    "amount": "100",
    "amountUsd": "100.00",
    "counterparty": "T..."
  }
}

Errors

Code	HTTP	Meaning	Recovery
INSUFFICIENT_BALANCE	402	Not enough prepaid TRX.	Deposit, then retry with a new idempotency key.
API_CREDIT_REQUIRED	402	Not enough Wallet API USD credits.	Add API balance on Overview or Plan, then retry.
IDEMPOTENCY_CONFLICT	409	Same key, different body.	New X-Idempotency-Key.
UNAUTHORIZED	401	Bad key, timestamp, or signature.	Check the key and the HMAC string.
RATE_LIMITED	429	Too many requests.	Wait for the 60s window.
INVALID_RECEIVER	400	Not a TRON address.	Mainnet T-address.
UNSUPPORTED_DURATION	400	Duration isn’t 1H, 1D, 3D, or 30D.	Use one of those four.

Rate limits

Per IP, user, and key, in a 60-second window: 30 POST, 120 GET. Responses send X-RateLimit-Limit and X-RateLimit-Remaining.

A few practical notes

Three surfaces share one signed HTTP API: Energy orders, watchlist changes, and Wallet Analyze. Energy is on Free. Wallet Analyze bills after a valid address or transaction ID. Watchlist HTTP needs Pro or Enterprise.

Sign the timestamp, method, path, canonical query, and SHA256 of the body you actually send. Do not pretty-print JSON and sign that. POST /energy/orders also needs X-Idempotency-Key.

Quotes do not charge TRX. Orders do. Wallet Analyze returns HTTP 402 when USD credits run out. Limits: 30 writes and 120 reads per IP, user, and key per 60 seconds.

Introduction

Node.js SDK

Authentication

HMAC signing

Idempotency

Energy

Balance

Deposit address

Live rate

Create order

List orders

Get order

Watchlist

List watchlist

Categories

Add address

Update entry

Remove address

Wallet

Wallet detail

Counterparties

Transactions

Transaction detail

Webhooks

Orders events

Watchlist events

Errors

Rate limits

A few practical notes