POST /apiv2/order1h

Crie um pedido de aluguel de energia de 1 hora por meio de múltiplos provedores de energia com failover automático.

URL do endpoint

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

Cabeçalhos da requisição

Header	Obrigatório	Descrição
Content-Type	Sim	application/json
X-API-KEY	Sim	Sua chave de API do painel da Netts
X-Real-IP	Sim	Endereço IP da sua lista de permissões (whitelist)

Corpo da requisição

json

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
amount	integer	Sim	Quantidade de Energy a alugar (mínimo: 61000, máximo: 3000000)
receiveAddress	string	Sim	Endereço TRON que receberá a energia (formato TRC-20)

Seleção de Provedor

A API seleciona automaticamente o provedor de energia ideal com base em:

Custo-benefício - Sempre encontra o menor preço disponível
Disponibilidade - Garante reservas suficientes de energia
Confiabilidade - Utiliza provedores com altas taxas de sucesso
Velocidade - Prioriza os tempos de entrega mais rápidos

Exemplos de Requisição

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

Resposta

Resposta de Sucesso (200 OK)

json

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

Campos da Resposta

Campo	Tipo	Descrição
detail.code	integer	Sempre `10000` para pedidos bem-sucedidos
detail.msg	string	Mensagem de sucesso com o valor debitado
detail.data.orderId	string	ID de pedido unificado (formato: `1H{request_id}`)
detail.data.paidTRX	number	Custo total em TRX (inclui taxa de ativação se o endereço não estiver ativado)
detail.data.hash	string \| null	Hash da transação. O campo está sempre presente, mas pode estar vazio - alguns provedores não retornam o hash imediatamente. Use /apiv2/order_check após 1 minuto para obter o hash
detail.data.delegateAddress	string	Endereço da pool que delegou a energia
detail.data.energy	integer	Quantidade de Energy + margem adicional (normalmente +50)

Respostas de erro

Erro de Autenticação (401)

json

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

Saldo Insuficiente (403)

json

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

Serviço Indisponível (503)

json

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

Erros de Provedor (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"
}

Erro Interno do Servidor (500)

json

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

Referência de Códigos de Erro

Código	Descrição	Status HTTP
`10000`	Sucesso	200
`10000`	Sucesso (resposta em cache)	208
`-`	Requisição duplicada ainda em processamento	409
`1004`	Saldo insuficiente	403
`5000`	Erro interno do servidor	500
`5001`	Provedor de energia indisponível	503
`5002`	Provedor de energia indisponível	503
`5003`	Serviço de energia indisponível	503
`5004`	Valor mínimo do provedor de energia não atingido	503

Limites de taxa

Os seguintes limites de taxa se aplicam a este endpoint (por endereço IP):

Período	Limite	Descrição
1 segundo	50 requisições	Máximo de 50 requisições por segundo

Headers de Rate Limit

http

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

Rate Limit Excedido (429)

json

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

Idempotência

A API suporta idempotência para evitar o processamento duplicado de pedidos. Quando você envia múltiplas requisições idênticas, o sistema garante que o pedido seja processado apenas uma vez.

Como a Idempotência Funciona

A unicidade da requisição é determinada por uma combinação de:

Timestamp da requisição (janela de 1 segundo)
Quantidade de Energy
Endereço de recebimento
Chave de API

Cada requisição recebe uma janela de unicidade de 1 segundo. Para proteger o sistema contra abusos e garantir o processamento adequado, requisições com parâmetros idênticos não podem ser enviadas com frequência superior a uma vez por segundo.

Comportamento atual: O sistema protege automaticamente os clientes contra novas tentativas incorretas para energia já solicitada. Se você enviar acidentalmente a mesma requisição duas vezes, não será cobrado em dobro.

Fornecendo Sua Própria Chave

Você pode gerenciar a idempotência por conta própria enviando o header X-Idempotency-Key. Quando ele está presente, esse valor sozinho determina se uma requisição é uma repetição, e a combinação automática acima não é usada. Quando ele está ausente, nada muda — o servidor deriva a chave para você.


Header	`X-Idempotency-Key`
Formato	Exatamente 64 caracteres hexadecimais minúsculos — um resumo (digest) SHA-256
Duração	24 horas a partir da primeira requisição contendo essa chave
Escopo	Sua conta. O mesmo valor enviado por uma conta diferente nunca retorna o seu resultado

Uma chave com qualquer outro formato — um UUID com hifens, base64, hexadecimal maiúsculo — é rejeitada com 400 antes que o pedido seja feito e antes que qualquer valor seja cobrado:

json

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

O formato difere de outros endpoints. /apiv2/withdraw, /apiv2/bandwidth e o orquestrador aceitam uma chave base64 de 16 a 64 caracteres. Este endpoint aceita apenas um digest hexadecimal de 64 caracteres; portanto, o código de construção de chave copiado desses endpoints retornará 400 aqui.

Como formar a chave

Derive-a a partir da sua chave de API. Isso torna o valor exclusivo para a sua conta, reproduzível em uma nova tentativa e impossível de ser gerado por qualquer outra pessoa:

python

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

O nonce pertence ao pedido, não à requisição. Escolha-o uma vez, quando o pedido for criado do seu lado, e envie esse mesmo valor em cada envio desse pedido — tanto na primeira tentativa quanto em todas as repetições. Gerar um novo valor dentro da função de envio (str(uuid.uuid4()) a cada chamada) atribui a cada tentativa uma chave diferente, de modo que uma nova tentativa após um timeout seja aceita como um segundo pedido e cobrada novamente. A escolha correta mais simples é o próprio ID de pedido que você já possui: ele existe antes da primeira tentativa e resiste a uma reinicialização do seu processo.

python

# uma vez, quando o pedido aparece no seu sistema
order = create_order(address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", amount=131000)

# na primeira tentativa e em cada repetição — as mesmas três entradas, a mesma chave
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,
}

Uma chave permanece ativa por 24 horas. Depois disso, o mesmo nonce fica livre novamente e inicia um novo pedido.

Não utilize um valor que qualquer outra pessoa possa gerar — 64 zeros, o digest de uma palavra fixa. As chaves compartilham o mesmo espaço entre as contas. Essa colisão nunca expõe o pedido de outra conta, mas a sua requisição será recusada com 409 até que a chave deles expire, o que não é a resposta desejada durante uma nova tentativa.

Enviando Dois Pedidos Idênticos

Às vezes, você deseja genuinamente fazer o mesmo pedido duas vezes — a mesma quantidade de energia para o mesmo endereço, um após o outro. A chave automática não consegue distinguir isso de uma repetição: as duas requisições são idênticas byte a byte, e a única coisa que as separa é o momento em que chegam.

Sem uma chave própria, o resultado depende do intervalo entre elas:

Intervalo entre as duas requisições	O que acontece
Dentro da mesma janela de 1 segundo	A segunda requisição é considerada uma repetição. Ela não é executada: você recebe `208` e a resposta do primeiro pedido, incluindo o `orderId`. Nada é cobrado por ela
Com mais de um segundo de diferença	Duas chaves diferentes — ambos os pedidos são criados e ambos são cobrados

Portanto, se você depende da chave automática, deixe mais de um segundo entre dois pedidos idênticos e verifique o código de status: 208 significa que o pedido recém-enviado não foi criado.

Uma pausa é um paliativo, não uma solução definitiva. Ela separa todas as requisições, incluindo aquelas que você nunca teve a intenção de repetir — uma nova tentativa após um timeout, um clique duplo, uma mensagem entregue novamente pela sua fila. Essas requisições também chegam fora da janela e, portanto, são processadas como pedidos separados e cobradas individualmente. O timeout de resposta deste endpoint é de 10 segundos, o que já está muito além da janela: a chave automática não protege uma nova tentativa que decorre de um timeout.

Utilizar sua própria chave elimina as incertezas, pois a decisão passa para o único lado que conhece a resposta:

O que você está fazendo	O que você envia	Resultado
Um segundo pedido genuinamente novo	Um novo `nonce`	Uma nova chave — o pedido é realizado
Uma nova tentativa de um pedido cujo resultado você desconhece	O `nonce` da primeira tentativa	A mesma chave — `208`, a resposta original, sem cobrança duplicada

A segunda linha é a razão pela qual o header existe e é onde as implementações normalmente falham: consulte a nota em Como formar a chave.

Códigos de Status HTTP para Requisições Duplicadas

Código de Status	Nome	Descrição
200	OK	Pedido processado com sucesso (primeira requisição)
208	Already Reported	O pedido já foi processado; retornando resposta em cache
409	Conflict	A requisição está em processamento no momento; não tente novamente

Requisição Duplicada - Já Processada (208)

Quando uma requisição duplicada é recebida para um pedido já concluído:

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

O corpo da resposta é idêntico à resposta de sucesso original, contendo um objeto idempotency adicional que indica se tratar de uma resposta em cache.

Requisição Duplicada - Ainda em Processamento (409)

Quando uma requisição duplicada chega enquanto a original ainda está sendo processada:

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
}

Recomendação: Aguarde o tempo especificado em retry_after_seconds antes de verificar o status do pedido.

Melhores Práticas

Não envie requisições paralelas com os mesmos parâmetros — aguarde cada resposta
Use um novo nonce para cada novo pedido e utilize o nonce da primeira tentativa para cada repetição do mesmo pedido
Nunca recrie o nonce no momento do envio — uma nova tentativa deve reproduzir a chave da primeira tentativa, e não uma nova
Trate respostas 409 aguardando, em vez de tentar novamente de imediato
Verifique o campo idempotency.cached para identificar respostas em cache — um 208 significa que o pedido recém-enviado não foi criado

Notas

A energia é entregue instantaneamente após a confirmação do pedido (normalmente entre 0,5 e 10 segundos)
Timeout de resposta da API: Máximo de 10 segundos, respondendo tipicamente em até 2 segundos
Ativação de endereço: Se o endereço de recebimento não estiver ativado, a Netts o ativa a preço de custo
Atraso de ativação: Para endereços não ativados, a resposta da API pode levar até 6 segundos devido ao processo de ativação
Os pedidos são processados 24 horas por dia, 7 dias por semana, com failover automático entre provedores
Quantidade mínima de Energy: 61.000 unidades
Quantidade máxima de Energy: 3.000.000 unidades por pedido
Margem de Energy (buffer): +50 unidades adicionadas automaticamente como compensação do provedor (sem custo)
Hash da transação: O campo está sempre presente, mas pode estar vazio se o provedor não o retornar de imediato. Para obter o hash, chame /apiv2/order_check no mínimo 1 minuto após a realização do pedido
Seleção de provedor: Automática, baseada em custo e disponibilidade
Formato do ID do pedido: 1H{request_id} para rastreamento unificado
Preço: Dinâmico, baseado na hora do dia e na quantidade de energia
Duração: Fixa de 1 hora (3600 segundos)
Rate limiting: 50 requisições por segundo por endereço IP

POST /apiv2/order1h ​

URL do endpoint ​

Cabeçalhos da requisição ​

Corpo da requisição ​

Parâmetros ​

Seleção de Provedor ​

Exemplos de Requisição ​

cURL ​

Python ​

Resposta ​

Resposta de Sucesso (200 OK) ​

Campos da Resposta ​

Respostas de erro ​

Erro de Autenticação (401) ​

Saldo Insuficiente (403) ​

Serviço Indisponível (503) ​

Erros de Provedor (503) ​

Erro Interno do Servidor (500) ​

Referência de Códigos de Erro ​

Limites de taxa ​

Headers de Rate Limit ​

Rate Limit Excedido (429) ​

Idempotência ​

Como a Idempotência Funciona ​

Fornecendo Sua Própria Chave ​

Como formar a chave ​

Enviando Dois Pedidos Idênticos ​

Códigos de Status HTTP para Requisições Duplicadas ​

Requisição Duplicada - Já Processada (208) ​

Requisição Duplicada - Ainda em Processamento (409) ​

Melhores Práticas ​

Notas ​

POST /apiv2/order1h

URL do endpoint

Cabeçalhos da requisição

Corpo da requisição

Parâmetros

Seleção de Provedor

Exemplos de Requisição

cURL

Python

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de erro

Erro de Autenticação (401)

Saldo Insuficiente (403)

Serviço Indisponível (503)

Erros de Provedor (503)

Erro Interno do Servidor (500)

Referência de Códigos de Erro

Limites de taxa

Headers de Rate Limit

Rate Limit Excedido (429)

Idempotência

Como a Idempotência Funciona

Fornecendo Sua Própria Chave

Como formar a chave

Enviando Dois Pedidos Idênticos

Códigos de Status HTTP para Requisições Duplicadas

Requisição Duplicada - Já Processada (208)

Requisição Duplicada - Ainda em Processamento (409)

Melhores Práticas

Notas