POST /apiv2/order5m

Create a 5-minute energy rental order through Netts internal energy pools.

Endpoint URL

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

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": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parameters

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

Energy Limits

The 5-minute endpoint accepts energy amounts between 61,000 and 650,000 units per order. Requests outside this range will be rejected with HTTP 400.

Provider Information

5-minute energy orders are fulfilled exclusively through Netts internal energy pools. Unlike the 1-hour endpoint, external providers are not used.

Availability & Retry Strategy

Since delegations come only from internal pools, temporary unavailability is possible during high-demand periods. If you receive a 503 error, retry the request after a short delay or fall back to the 1-hour endpoint which has access to multiple external providers.

Example Requests

cURL

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

Python

import requests

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

payload = {
    "amount": 65000,
    "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')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
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, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Success with Address Activation (200 OK)

When the receiver address has not been activated on the TRON network, Netts activates it automatically. The activation cost is added to the total:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a"
        }
    }
}

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: 5M{id})
detail.data.paidTRX	number	Total cost in TRX (includes activation fee if applicable)
detail.data.hash	string	Delegation transaction hash
detail.data.delegateAddress	string	Pool address that delegated energy
detail.data.energy	integer	Energy amount + buffer (typically +50)
detail.data.activationHash	string	Only present if address activation was performed

Error Responses

Invalid Energy Amount (400)

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

Authentication Error (401)

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

Insufficient Balance (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

Service Unavailable (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

Handling 503 Errors

A 503 response means internal pools are temporarily at capacity. Recommended strategy:

1. Wait 2-3 seconds and retry the 5-minute order
2. If still unavailable, fall back to the 1-hour endpoint which uses multiple providers

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
1003	Energy amount out of range	400
1004	Insufficient balance	403
1005	User payer address not configured	400
5000	Internal server error	500
5003	Energy service unavailable	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 (2-second window)
• Energy amount
• Receiver address
• API key

Each request is given a 2-second uniqueness window. Requests with identical parameters within this window are treated as duplicates.

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.

The rules are the same as on /apiv2/order1h:

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."
}

Derive the key from your API key so it is unique to your account and reproducible on a retry — the worked example is on the 1-hour page. Include the rental period in the message you hash: renting the same address for 5 minutes and for 1 hour are different orders, and reusing one key for both returns the first order's response for the second request.

Placing Two Identical Orders

The same trap as on the hourly endpoint, with a wider window. Two identical orders — the same amount to the same address — are indistinguishable from a retry, and only the moment of arrival separates them.

Without a key of your own:

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

So leave more than two seconds 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 also separates the requests you never meant to repeat, such as a retry after a timeout or a message redelivered by your queue, and each of those becomes a separate order with a separate charge. Sending your own key is what actually settles it: a new nonce for a new order, the first attempt's nonce for a retry. The reasoning in full is on the 1-hour page.

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)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

Duplicate Request - Still Processing (409)

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

Best Practices

• Do not send parallel requests with the same parameters - wait for each response
• Handle 409 responses by waiting, not by immediately retrying
• Check idempotency.cached field to identify cached responses

Comparison: 5-Minute vs 1-Hour Orders

Feature	5-Minute Order	1-Hour Order
Endpoint	/apiv2/order5m	/apiv2/order1h
Duration	5 minutes	1 hour
Energy range	61,000 - 650,000	61,000 - 3,000,000
Providers	Netts internal pools only	Internal pools + external providers
Price	Lower (5-minute rate)	Standard hourly rate
Availability	May be limited during peak	High (multiple provider fallback)
Best for	Frequent small transactions	Large or guaranteed delivery

Postpaid Accounts

Accounts on postpaid billing use the same endpoint, URL, headers and request body as everyone else. The difference is how the order is paid:

• Nothing is deducted from your deposit. Each successful order is added to your account balance due in the settlement currency agreed in your contract. You pay it by invoice, according to your agreement.
• Your account has a credit limit. While the amount due is within the limit, orders are accepted even with a zero deposit.
• Only delivered services are billed. An order that is rejected or not executed costs nothing.
• If the receiving address has to be activated, the activation is part of the same order and is billed as a separate charge.

Postpaid billing is enabled by Netts for an account on request. Every response tells you how the order is paid: paymentMode is postpaid or prepaid.

Additional request fields

Parameter	Type	Required	Description
test	boolean	No	true — calculate the price only. Nothing is ordered, delivered or billed
freezePrice	boolean	No	true — fix the price under your contract for 60 seconds. Nothing is ordered or billed
quoteId	string	No	Place the order at the price of a quote issued by freezePrice
priceCurrency	string	No	TRX (default) or the currency of your contract, as in settlement.asset. For postpaid accounts the amounts in your contract currency are always included

quoteId cannot be combined with test or freezePrice. Any other field in the request body is rejected.

Price check (test: true)

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "test": true
}

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 65000,
            "unitPriceSun": "19",
            "discount": null,
            "energyTRX": "1.235000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "2.335000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.409088", "activation": "0.364370", "total": "0.773458"}},
            "fxAt": "2026-10-19T07:16:12.548894+00:00"
        }
    }
}

Field	Description
unitPriceSun	Price per energy unit in SUN, including your personal discount if you have one
discount	Your personal discount (type, value) or null
energyTRX / activationTRX / wouldCostTRX	Energy, activation (if the address needs it) and total, in TRX
activationCheck	inactive — the address will be activated and billed; active — no activation; unknown — could not be checked right now
alt.<currency>	The same amounts in the currency of your contract
fxAt	Time of the exchange rate used for the amounts in your contract currency

Fixed-price quote (freezePrice: true)

Use a quote to fix the price under your contract before you order.

1. Send the order with "freezePrice": true. The response has code 10011 (Quote issued), the same fields as a price check, plus quoteId and expiresAt.
2. Within 60 seconds send the order with "quoteId": "<quoteId>" and the same amount and receiveAddress.
3. The order is billed at the quoted price — the price under your contract at the moment of the quote — even if the price changes in between.

A quote can be used once and only for the same product: a 5-minute quote cannot pay for a 1-hour order. An expired or already used quote is rejected and nothing is ordered.

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "quoteId": "q_4f540f16a2c94b7f8e3d1a6b5c0e9d72"
}

Successful order

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.24 TRX service cost, postpaid",
        "data": {
            "orderId": "5M5f557d2fba",
            "paidTRX": 1.235,
            "hash": "c1fafd8ef7fb6b7fb8a729120756b26e611f401275cb4f7a04fe2bafd75b13da",
            "delegateAddress": "TR3qZsdmkFcvP729Md3PwXzktFQkMoUzjg",
            "energy": 65000,
            "paymentMode": "postpaid",
            "energyTRX": "1.235000",
            "activationTRX": "0.000000",
            "totalTRX": "1.235000"
        }
    }
}

Field	Description
paidTRX	Cost of the service in TRX. For postpaid accounts it is not deducted from the deposit
paymentMode	postpaid
energyTRX / activationTRX / totalTRX	Exact amounts, 6 decimal places
quoteId, alt	Present when the order was placed with a quote: the quote ID and the quoted amounts

All other fields are the same as for prepaid orders.

Credit limit reached (402)

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

The order is not executed and nothing is billed. New orders are accepted again once your payment is registered or your limit is increased.

Postpaid error codes

Code	HTTP	Description
10010	200	Price check result (test)
10011	200	Quote issued (freezePrice)
1004	402	Postpaid credit limit reached
4100	400	Invalid request
4101	400	Unsupported priceCurrency
4102	400	quoteId combined with test or freezePrice
4103	409	Quote already used
4104	409	Quote expired
4105	409	Idempotency key already used for a different request
4106	404	Quote not found
4107	409	Order parameters differ from the quote
4108	400	Invalid quoteId format
4109	422	Not available for sub-accounts
5032	503	Price temporarily unavailable
5033	503	Exchange rate temporarily unavailable
5034	503	Billing temporarily unavailable — the order was not accepted
5036	503	Credit check temporarily unavailable — retry later

For all 4xx and 503 responses above nothing is ordered and nothing is billed.

Notes

• Energy is delivered instantly upon successful order (typically within 0.5-2 seconds)
• API response timeout: Maximum 10 seconds (includes internal retry attempts)
• Address activation: If receiver address is not activated, Netts activates it at cost price. Activation cost is charged only once per address
• Duration: Fixed 5 minutes (300 seconds)
• Minimum energy amount: 61,000 units
• Maximum energy amount: 650,000 units per order
• Energy buffer: +50 units added automatically (free of charge)
• Order ID format: 5M{id} for unified tracking
• Pricing: Dynamic based on time of day via Pricing API
• Rate limiting: 50 requests per second per IP address
• Internal pools only: If pools are at capacity, retry after a short delay or use the 1-hour endpoint as fallback