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 whitelist

Corpo da requisição

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

Parâmetros da requisição

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. Solicitações fora dessa faixa serão rejeitadas 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. Diferente 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, é possível haver indisponibilidade temporária durante períodos de alta demanda. Se você receber um erro 503, repita a solicitação após um breve intervalo ou utilize o endpoint de 1 hora, que possui acesso a múltiplos provedores externos.

Exemplos

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": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

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

Quando o endereço de recebimento 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": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a"
        }
    }
}

Campos da Resposta

Field	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 de pedido unificado (formato: 5M{id})
detail.data.paidTRX	number	Custo total em TRX (inclui 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 (normalmente +50)
detail.data.activationHash	string	Presente apenas se a ativação de endereço foi realizada

Respostas de erro

Quantidade de Energy Inválida (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 indica que os pools internos estão temporariamente em 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 o endpoint de 1 hora, que utiliza múltiplos provedores

Erro Interno do Servidor (500)

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

Referência de Códigos de Erro

Code	Description	HTTP Status
10000	Sucesso	200
10000	Sucesso (resposta em cache)	208
-	Solicitação duplicada ainda em processamento	409
1003	Quantidade de energy fora da faixa	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):

Period	Limit	Description
1 segundo	50 solicitações	Máximo de 50 solicitações por segundo

Headers de Rate Limit

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 oferece suporte à idempotência para evitar o processamento de pedidos duplicados. Quando você envia várias solicitações idênticas, o sistema garante que o pedido seja processado apenas uma vez.

Como Funciona a Idempotência

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

• Timestamp da solicitação (janela de 2 segundos)
• Quantidade de energy
• Endereço de recebimento
• Chave de API

Cada solicitação recebe uma janela de unicidade de 2 segundos. Solicitações com parâmetros idênticos dentro dessa janela são tratadas como duplicadas.

Fornecendo Sua Própria Chave

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

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

Header	X-Idempotency-Key
Format	Exatamente 64 caracteres hexadecimais minúsculos — um digest SHA-256
Lifetime	24 horas a partir da primeira solicitação contendo essa chave
Scope	Sua conta. O mesmo valor enviado por uma conta diferente nunca retorna o seu resultado

Uma chave com qualquer outro formato — um UUID com traços, base64, hexadecimal maiúsculo — é rejeitada com 400 antes que o pedido seja realizado 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 única 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 que você calcula o hash: alugar para o mesmo endereço por 5 minutos e por 1 hora são pedidos diferentes, e reutilizar a mesma chave para ambos retorna a resposta do primeiro pedido para a segunda solicitação.

Fazendo Dois Pedidos Idênticos

A mesma armadilha do endpoint de uma 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 de chegada os separa.

Sem uma chave própria:

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

Portanto, aguarde 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 realizado.

Fazer uma pausa é apenas um contorno, não uma solução definitiva — ela também separa solicitaçõ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 de mensagens, e cada uma delas se torna um pedido separado com uma cobrança separada. Enviar sua própria chave é o que realmente resolve isso: um novo nonce para um novo pedido, o nonce da primeira tentativa para uma repetição. O raciocínio completo está na página de 1 hora.

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

Status Code	Name	Description
200	OK	Pedido processado com sucesso (primeira solicitação)
208	Already Reported	O pedido já foi processado, retornando a resposta em cache
409	Conflict	A solicitação está sendo processada no momento, não repita

Solicitação Duplicada - Já Processada (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"
    }
}

Solicitaçã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 solicitações paralelas com os mesmos parâmetros — aguarde cada resposta
• Trate respostas 409 aguardando, em vez de tentar novamente de imediato
• Verifique o campo idempotency.cached para identificar respostas em cache

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

Feature	5-Minute Order	1-Hour Order
Endpoint	/apiv2/order5m	/apiv2/order1h
Duração	5 minutos	1 hora
Faixa 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	Transações pequenas e frequentes	Entregas grandes ou garantidas

Contas Pós-pagas

Contas com faturamento pós-pago utilizam o mesmo endpoint, URL, cabeçalhos e corpo de solicitação que os demais usuários. A diferença reside na forma como o pedido é pago:

• Nada é debitado do seu depósito. Cada pedido bem-sucedido é adicionado ao saldo devedor da sua conta na moeda de liquidação acordada em seu contrato. O pagamento é feito por fatura, de acordo com o seu contrato.
• Sua conta possui um limite de crédito. Enquanto o valor devido estiver dentro do limite, os pedidos serão aceitos mesmo com depósito zerado.
• Apenas serviços entregues são faturados. Um pedido rejeitado ou não executado não gera cobrança.
• Se o endereço de recebimento precisar ser ativado, a ativação fará parte do mesmo pedido e será faturada como uma cobrança separada.

O faturamento pós-pago é ativado pela Netts para uma conta mediante solicitação. Todas as respostas informam como o pedido é pago: paymentMode será postpaid ou prepaid.

Campos adicionais de solicitação

Parameter	Type	Required	Description
test	boolean	Não	true — apenas calcula o preço. Nada é pedido, entregue ou faturado
freezePrice	boolean	Não	true — fixa o preço sob o seu contrato por 60 segundos. Nada é pedido ou faturado
quoteId	string	Não	Faz o pedido com base no preço de uma cotação emitida por freezePrice
priceCurrency	string	Não	TRX (padrão) ou a moeda do seu contrato, conforme em settlement.asset. Para contas pós-pagas, os valores na moeda do seu contrato sempre estão incluídos

quoteId não pode ser combinado com test ou freezePrice. Qualquer outro campo no corpo da solicitação será rejeitado.

Consulta de preço (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	Preço por unidade de energy em SUN, incluindo seu desconto pessoal se você tiver um
discount	Seu desconto pessoal (type, value) ou null
energyTRX / activationTRX / wouldCostTRX	Energy, ativação (caso o endereço precise) e total, em TRX
activationCheck	inactive — o endereço será ativado e faturado; active — sem ativação; unknown — não foi possível verificar no momento
alt.<currency>	Os mesmos valores na moeda do seu contrato
fxAt	Momento da taxa de câmbio utilizada para os valores na moeda do seu contrato

Cotação de preço fixo (freezePrice: true)

Utilize uma cotação para fixar o preço sob o seu contrato antes de fazer o pedido.

1. Envie o pedido com "freezePrice": true. A resposta conterá o código 10011 (Quote issued), os mesmos campos de uma consulta de preço, além de quoteId e expiresAt.
2. Em até 60 segundos, envie o pedido com "quoteId": "<quoteId>" e os mesmos amount e receiveAddress.
3. O pedido é faturado pelo preço cotado — o preço sob o seu contrato no momento da cotação —, mesmo que o preço mude nesse intervalo.

Uma cotação pode ser usada uma única vez e apenas para o mesmo produto: uma cotação de 5 minutos não pode pagar por um pedido de 1 hora. Uma cotação expirada ou já utilizada será rejeitada e nada será pedido.

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

Pedido bem-sucedido

{
    "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	Custo do serviço em TRX. Para contas pós-pagas, ele não é deduzido do depósito
paymentMode	postpaid
energyTRX / activationTRX / totalTRX	Valores exatos, com 6 casas decimais
quoteId, alt	Presentes quando o pedido foi feito com uma cotação: o ID da cotação e os valores cotados

Todos os outros campos são os mesmos dos pedidos pré-pagos.

Limite de crédito atingido (402)

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

O pedido não é executado e nada é faturado. Novos pedidos serão aceitos novamente assim que o seu pagamento for registrado ou o seu limite for aumentado.

Códigos de erro para pós-pago

Code	HTTP	Description
10010	200	Resultado da consulta de preço (test)
10011	200	Cotação emitida (freezePrice)
1004	402	Limite de crédito pós-pago atingido
4100	400	Solicitação inválida
4101	400	priceCurrency não suportada
4102	400	quoteId combinado com test ou freezePrice
4103	409	Cotação já utilizada
4104	409	Cotação expirada
4105	409	Chave de idempotência já utilizada para uma solicitação diferente
4106	404	Cotação não encontrada
4107	409	Parâmetros do pedido diferem da cotação
4108	400	Formato de quoteId inválido
4109	422	Não disponível para subcontas
5032	503	Preço temporariamente indisponível
5033	503	Taxa de câmbio temporariamente indisponível
5034	503	Faturamento temporariamente indisponível — o pedido não foi aceito
5036	503	Verificação de crédito temporariamente indisponível — tente novamente mais tarde

Para todas as respostas 4xx e 503 acima, nada é solicitado e nada é faturado.

Observações

• A energy é entregue instantaneamente após a realização do pedido com sucesso (normalmente em 0,5 a 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 de recebimento 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 em 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ços: Dinâmicos com base na hora do dia por meio da Pricing API
• Rate limiting: 50 solicitações por segundo por endereço IP
• Apenas pools internos: Se os pools estiverem com capacidade esgotada, tente novamente após um breve intervalo ou utilize o endpoint de 1 hora como alternativa