---
url: https://doc.netts.io/api/v2/endpoints/order1h.md
---
# 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

```json
{
    "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

```bash
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

```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)

```json
{
    "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](/api/v2/endpoints/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)

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

### Insufficient Balance (403)

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

### Service Unavailable (503)

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

### Provider Errors (503)

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

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

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

### Internal Server Error (500)

```json
{
    "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

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

### Rate Limit Exceeded (429)

```json
{
    "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:

```json
{
    "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:

```json
{
    "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**: 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](/api/v2/endpoints/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