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: 5000000)
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.

Coming soon: An optional idempotency_key parameter will be added to the request. When provided, the system will use this key to determine request uniqueness instead of auto-generated parameters. This gives clients full control over idempotency, since only the client knows whether a request is truly unique or a retry.

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 unique idempotency keys for different orders
• Handle 409 responses by waiting, not by immediately retrying
• Check idempotency.cached field to identify cached responses

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: 5,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