POST /apiv2/order5m

Crie um pedido de aluguel de energy de 5 minutos por meio dos pools de energy internos da Netts.

URL do endpoint

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

Cabeçalhos da requisição

Header	Required	Description
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

Corpo da requisição

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

Parâmetros

Parameter	Type	Required	Description
amount	integer	Sim	Quantidade de Energy a ser alugada (mínimo: 61.000, máximo: 650.000)
receiveAddress	string	Sim	Endereço TRON que receberá a energy (formato TRC-20)

Limites de Energy

O endpoint de 5 minutos aceita quantidades de energy entre 61.000 e 650.000 unidades por pedido. Pedidos fora desse intervalo serão rejeitados com HTTP 400.

Informações do Provedor

Os pedidos de energy de 5 minutos são atendidos exclusivamente por meio dos pools de energy internos da Netts. Ao contrário do endpoint de 1 hora, provedores externos não são utilizados.

Disponibilidade e Estratégia de Repetição

Como as delegações vêm apenas de pools internos, pode haver indisponibilidade temporária durante períodos de alta demanda. Se você receber um erro 503, repita a requisição após um breve intervalo ou utilize como alternativa o endpoint de 1 hora, que tem acesso a múltiplos provedores externos.

Examples de Requisições

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

Resposta

Resposta de Sucesso (200 OK)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Sucesso com Ativação de Endereço (200 OK)

Quando o endereço do destinatário ainda não foi ativado na rede TRON, a Netts o ativa automaticamente. O custo de ativação é adicionado ao total:

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

Campos da Resposta

Campo	Type	Description
detail.code	integer	Sempre 10000 para pedidos bem-sucedidos
detail.msg	string	Mensagem de sucesso com o valor debitado
detail.data.orderId	string	ID unificado do pedido (formato: 5M{id})
detail.data.paidTRX	number	Custo total em TRX (inclui a taxa de ativação, se aplicável)
detail.data.hash	string	Hash da transação de delegação
detail.data.delegateAddress	string	Endereço do pool que delegou a energy
detail.data.energy	integer	Quantidade de Energy + margem adicional (geralmente +50)
detail.data.activationHash	string	Presente apenas se a ativação de endereço foi realizada

Respostas de erro

Quantidade Inválida de Energy (400)

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

Erro de Autenticação (401)

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

Saldo Insuficiente (403)

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

Serviço Indisponível (503)

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

Tratamento de Erros 503

Uma resposta 503 significa que os pools internos estão temporariamente em sua capacidade máxima. Estratégia recomendada:

1. Aguarde de 2 a 3 segundos e repita o pedido de 5 minutos
2. Se continuar indisponível, utilize como alternativa o endpoint de 1 hora, que faz uso de múltiplos provedores

Erro Interno do Servidor (500)

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

Referência de Códigos de Erro

Código	Description	HTTP Status
10000	Sucesso	200
10000	Sucesso (resposta em cache)	208
-	Requisição duplicada ainda em processamento	409
1003	Quantidade de Energy fora do intervalo	400
1004	Saldo insuficiente	403
1005	Endereço pagador do usuário não configurado	400
5000	Erro interno do servidor	500
5003	Serviço de energy indisponível	503

Limites de taxa

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

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

Headers de Limite de Taxa

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

Limite de Taxa Excedido (429)

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

Idempotência

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

Como Funciona a Idempotência

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

• Timestamp da requisição (janela de 2 segundos)
• Quantidade de Energy
• Endereço do destinatário
• Chave de API

Cada requisição recebe uma janela de exclusividade de 2 segundos. Requisições com parâmetros idênticos dentro dessa janela são tratadas como duplicatas.

Fornecendo Sua Própria Chave

Você pode assumir o controle da idempotência enviando o header X-Idempotency-Key. Quando ele está presente, esse valor sozinho decide se uma requisição é uma repetição, e a combinação automática acima não é utilizada. Quando ele está ausente, nada muda — o servidor deriva a chave para você.

As regras são as mesmas de /apiv2/order1h:

Header	X-Idempotency-Key
Formato	Exatamente 64 caracteres hexadecimais em minúsculas — um digest SHA-256
Tempo de vida	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 em qualquer outro formato — um UUID com traços, base64, hexadecimal em maiúsculas — é rejeitada com 400 antes que o pedido seja feito e antes de qualquer cobrança:

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

Derive a chave a partir da sua chave de API para que ela seja exclusiva para a sua conta e reproduzível em uma nova tentativa — o exemplo detalhado está na página de 1 hora. Inclua o período de aluguel na mensagem a ser processada pelo hash: alugar para o mesmo endereço por 5 minutos e por 1 hora são pedidos diferentes, e reutilizar uma única chave para ambos retorna a resposta do primeiro pedido para a segunda requisição.

Fazendo Dois Pedidos Idênticos

A mesma armadilha do endpoint de hora em hora, com uma janela maior. Dois pedidos idênticos — a mesma quantidade para o mesmo endereço — são indistinguíveis de uma repetição, e apenas o momento da chegada os separa.

Sem uma chave própria:

Intervalo entre as duas requisições	O que acontece
Dentro da mesma janela de 2 segundos	A segunda requisição é considerada uma repetição. Ela não é executada: você recebe 208 e a resposta do primeiro pedido. Nada é cobrado por ela
Mais de dois segundos de intervalo	Duas chaves diferentes — ambos os pedidos são criados e ambos são cobrados

Portanto, deixe mais de dois segundos entre dois pedidos idênticos e verifique o código de status: 208 significa que o pedido que você acabou de enviar não foi criado.

Fazer uma pausa é um contorno, não uma solução definitiva — ela também separa as requisições que você nunca teve a intenção de repetir, como uma nova tentativa após um timeout ou uma mensagem reenviada pela sua fila, e cada uma delas se torna um pedido separado com uma cobrança separada. Enviar sua própria chave é o que realmente resolve a questão: um novo nonce para um novo pedido, o nonce da primeira tentativa para uma repetição. A explicação completa está na página de 1 hora.

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

Status Code	Nome	Description
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á sendo processada no momento, não tente novamente

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

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

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

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

Melhores Práticas

• Não envie requisições paralelas com os mesmos parâmetros - aguarde cada resposta
• Trate respostas 409 aguardando, e não tentando novamente de imediato
• Verifique o campo idempotency.cached para identificar respostas em cache

Comparação: Pedidos de 5 Minutos vs 1 Hora

Recurso	Pedido de 5 Minutos	Pedido de 1 Hora
Endpoint	/apiv2/order5m	/apiv2/order1h
Duração	5 minutos	1 hora
Intervalo de Energy	61.000 - 650.000	61.000 - 3.000.000
Provedores	Apenas pools internos da Netts	Pools internos + provedores externos
Preço	Mais baixo (tarifa de 5 minutos)	Tarifa horária padrão
Disponibilidade	Pode ser limitada durante picos	Alta (fallback com múltiplos provedores)
Melhor para	Pequenas transações frequentes	Entregas grandes ou garantidas

Notas

• A Energy é entregue instantaneamente após a realização do pedido com sucesso (geralmente entre 0,5 e 2 segundos)
• Timeout de resposta da API: Máximo de 10 segundos (inclui tentativas internas de repetição)
• Ativação de endereço: Se o endereço do destinatário não estiver ativado, a Netts o ativa pelo preço de custo. O custo de ativação é cobrado apenas uma vez por endereço
• Duração: Fixa de 5 minutos (300 segundos)
• Quantidade mínima de Energy: 61.000 unidades
• Quantidade máxima de Energy: 650.000 unidades por pedido
• Margem de Energy: +50 unidades adicionadas automaticamente (gratuitamente)
• Formato do ID do pedido: 5M{id} para rastreamento unificado
• Preço: Dinâmico com base na hora do dia por meio da API de Preços
• Rate Limiting: 50 requisições por segundo por endereço IP
• Apenas pools internos: Se os pools atingirem a capacidade máxima, tente novamente após um breve intervalo ou use o endpoint de 1 hora como alternativa