POST /apiv2/order1h

Create a 1-hour energy rental order through multiple energy providers with automatic failover.

Endpoint URL

POST https://netts.io/apiv2/order1h

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-API-KEY	Yes	Your API key from Netts dashboard
X-Real-IP	Yes	IP address from your whitelist

Request Body

{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Energy amount to rent (minimum: 61000, maximum: 3000000)
receiveAddress	string	Yes	TRON address that will receive the energy (TRC-20 format)

Provider Selection

The API automatically selects the optimal energy provider based on:

• Cost efficiency - Always finds the lowest available price
• Availability - Ensures sufficient energy reserves
• Reliability - Uses providers with high success rates
• Speed - Prioritizes fastest delivery times

Example Requests

cURL

curl -X POST https://netts.io/apiv2/order1h \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

import requests

url = "https://netts.io/apiv2/order1h"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Response

Success Response (200 OK)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.23 TRX deducted",
        "data": {
            "orderId": "1H123456",
            "paidTRX": 2.23,
            "hash": "a1b2c3d4e5f6789...",
            "delegateAddress": "TDelegatePoolAddress...",
            "energy": 131050
        }
    }
}

Response Fields

Field	Type	Description
detail.code	integer	Always 10000 for successful orders
detail.msg	string	Success message with deducted amount
detail.data.orderId	string	Unified order ID (format: 1H{request_id})
detail.data.paidTRX	number	Total cost in TRX (includes activation fee if address was not activated)
detail.data.hash	string | null	Transaction hash. Field is always present but may be empty - some providers don't return hash immediately. Use /apiv2/order_check after 1 minute to get the hash
detail.data.delegateAddress	string	Pool address that delegated energy
detail.data.energy	integer	Energy amount + buffer (typically +50)

Error Responses

Authentication Error (401)

{
    "detail": "Invalid API key or IP not in whitelist"
}

Insufficient Balance (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 2.23 TRX, Available: 1.50 TRX"
}

Service Unavailable (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. All energy providers are currently unavailable."
}

Provider Errors (503)

{
    "code": 5001,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5002,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5004,
    "msg": "Energy provider requires higher minimum amount"
}

Internal Server Error (500)

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Error Code Reference

Code	Description	HTTP Status
10000	Success	200
10000	Success (cached response)	208
-	Duplicate request still processing	409
1004	Insufficient balance	403
5000	Internal server error	500
5001	Energy provider unavailable	503
5002	Energy provider unavailable	503
5003	Energy service unavailable	503
5004	Energy provider minimum not met	503

Rate Limits

The following rate limits apply to this endpoint (per IP address):

Period	Limit	Description
1 second	50 requests	Maximum 50 requests per second

Rate Limit Headers

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Rate Limit Exceeded (429)

{
    "message": "API rate limit exceeded"
}

Idempotency

The API supports idempotency to prevent duplicate order processing. When you send multiple identical requests, the system ensures the order is processed only once.

How Idempotency Works

Request uniqueness is determined by a combination of:

• Request timestamp (1-second window)
• Energy amount
• Receiver address
• API key

Each request is given a 1-second uniqueness window. To protect the system from abuse and ensure proper processing, requests with identical parameters cannot be sent more frequently than once per second.

Current behavior: The system automatically protects clients from erroneous retries on already ordered energy. If you accidentally send the same request twice, you won't be charged twice.

Supplying Your Own Key

You can take idempotency into your own hands by sending the X-Idempotency-Key header. When it is present, that value alone decides whether a request is a repeat, and the automatic combination above is not used. When it is absent, nothing changes — the server derives the key for you.

Header	X-Idempotency-Key
Format	Exactly 64 lowercase hexadecimal characters — a SHA-256 digest
Lifetime	24 hours from the first request carrying that key
Scope	Your account. The same value sent by a different account never returns your result

A key of any other shape — a UUID with dashes, base64, uppercase hex — is rejected with 400 before the order is placed and before anything is charged:

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

The format differs from other endpoints. /apiv2/withdraw, /apiv2/bandwidth and the orchestrator accept a 16–64 character base64 key. This endpoint accepts only a 64-character hex digest, so key-building code copied from those endpoints returns 400 here.

How to form the key

Derive it from your API key. That makes the value unique to your account, reproducible on a retry, and impossible for anyone else to arrive at:

import hashlib
import hmac

def make_idempotency_key(api_key: str, address: str, amount: int, nonce: str) -> str:
    message = f"{address}:{amount}:{nonce}"
    return hmac.new(api_key.encode(), message.encode(), hashlib.sha256).hexdigest()

The nonce belongs to the order, not to the request. Pick it once, when the order is created on your side, and pass that same value on every send of that order — the first attempt and every retry alike. Generating a fresh value inside the sending function (str(uuid.uuid4()) on each call) gives every attempt a different key, so a retry after a timeout is accepted as a second order and charged again. The simplest correct choice is the order id you already have: it exists before the first attempt and survives a restart of your process.

# once, when the order appears in your system
order = create_order(address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", amount=131000)

# on the first attempt and on every retry — the same three inputs, the same key
key = make_idempotency_key(API_KEY, order.address, order.amount, order.id)

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Idempotency-Key": key,
}

A key lives 24 hours. After that the same nonce is free again and starts a new order.

Do not use a value anyone else could arrive at — 64 zeros, the digest of a fixed word. Keys share one space across accounts. Such a collision never exposes another account's order, but your request is refused with 409 until their key expires, which is not the answer you want in the middle of a retry.

Placing Two Identical Orders

Sometimes you genuinely want the same order twice — the same amount of energy to the same address, one after the other. The automatic key cannot tell that from a retry: the two requests are byte-for-byte identical, and the only thing separating them is the moment they arrive.

Without a key of your own, the outcome depends on the gap between them:

Gap between the two requests	What happens
Inside the same 1-second window	The second request is taken for a repeat. It is not executed: you get 208 and the first order's response, orderId included. Nothing is charged for it
More than a second apart	Two different keys — both orders are placed and both are charged

So if you rely on the automatic key, leave more than one second between two identical orders, and read the status code: 208 means the order you just sent was not placed.

A pause is a workaround, not a fix. It separates every request, including the ones you never meant to repeat — a retry after a timeout, a double click, a message redelivered by your queue. Those also arrive later than the window, so they are placed as separate orders and charged separately. The response timeout of this endpoint is 10 seconds, which is already far outside the window: the automatic key does not protect a retry that follows a timeout.

Your own key removes the guesswork, because the decision moves to the only side that knows the answer:

What you are doing	What you send	Result
A second, genuinely new order	A new nonce	A new key — the order is placed
A retry of an order whose outcome you do not know	The nonce of the first attempt	The same key — 208, the original response, no second charge

The second row is the reason the header exists, and it is where implementations usually slip: see the note under How to form the key.

HTTP Status Codes for Duplicate Requests

Status Code	Name	Description
200	OK	Order processed successfully (first request)
208	Already Reported	Order was already processed, returning cached response
409	Conflict	Request is currently being processed, do not retry

Duplicate Request - Already Processed (208)

When a duplicate request is received for an already completed order:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.54 TRX deducted",
        "data": {
            "hash": "9e4c20e21e01e4c39b21b670d1ea1fc1e4b0de94d8fbd4c190d5378ba911dfae",
            "energy": 65050,
            "orderId": "1H70bcc7962a",
            "paidTRX": 2.535,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2025-12-03T10:34:49.104896"
    }
}

The response body is identical to the original successful response, with an additional idempotency object indicating this is a cached response.

Duplicate Request - Still Processing (409)

When a duplicate request arrives while the original is still being processed:

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "idempotency_key": "b9e67b2412d33c92...",
    "retry_after_seconds": 3
}

Recommendation: Wait for the specified retry_after_seconds before checking the order status.

Best Practices

• Do not send parallel requests with the same parameters - wait for each response
• Use a new nonce for every new order, and the first attempt's nonce for every retry of it
• Never rebuild the nonce at send time — a retry must reproduce the key of the first attempt, not a new one
• Handle 409 responses by waiting, not by immediately retrying
• Check idempotency.cached field to identify cached responses — a 208 means the order you just sent was not placed

Notes

• Energy is delivered instantly upon successful order (typically within 0.5-10 seconds)
• API response timeout: Maximum 10 seconds, typically responds in up to 2 seconds
• Address activation: If receiver address is not activated, Netts activates it at cost price
• Activation delay: For non-activated addresses, API response may take up to 6 seconds due to activation process
• Orders are processed 24/7 with automatic provider failover
• Minimum energy amount: 61,000 units
• Maximum energy amount: 3,000,000 units per order
• Energy buffer: +50 units added automatically for provider compensation (free of charge)
• Transaction hash: Field is always present but may be empty if provider doesn't return it immediately. To retrieve the hash, call /apiv2/order_check no earlier than 1 minute after placing the order
• Provider selection: Automatic based on cost and availability
• Order ID format: 1H{request_id} for unified tracking
• Pricing: Dynamic based on time of day and energy amount
• Duration: Fixed 1 hour (3600 seconds)
• Rate limiting: 50 requests per second per IP address