API do marketplace de energia Tron

Bem-vindo à documentação oficial da nossa API do marketplace de energia Tron. Aqui você encontra detalhes sobre os endpoints públicos que permitem:

  • Obter os parâmetros atuais da plataforma (preço da energia, oferta disponível, tamanho mínimo do pedido e endereço de depósito).
  • Verificar o status de um pedido de compra de energia específico pelo hash de depósito.
  • Comprar energia programaticamente a partir de um saldo pré-pago, sem enviar um depósito por cada pedido.

Os dois endpoints GET abaixo são públicos e não exigem autenticação. A compra de energia exige uma chave de API: gere-a no seu painel e envie-a no cabeçalho X-Api-Key. Configurações do comprador

Envie a chave apenas no cabeçalho. As cadeias de consulta acabam nos registos do servidor.

Visão geral dos endpoints

GET https://api.tron.discount/energy/info

Retorna as configurações ao vivo da plataforma, como se o sistema está ativo, quanta energia está disponível, o preço da energia, o endereço de depósito, etc.

GET https://api.tron.discount/energy/order/{depositHash}

Retorna o status de um pedido de compra específico, incluindo os hashes de transação e os detalhes de delegação.

POST https://api.tron.discount/energy/order Chave de API

Compra energia com o seu saldo pré-pago. Não é necessária qualquer transação de depósito.

GET https://api.tron.discount/energy/order/api/{id} Chave de API

Devolve o estado de um pedido feito pela API, a partir do seu identificador numérico.

Endpoints detalhados

GET

/energy/info

Descrição

Fornece parâmetros como o preço atual da energia, quanta energia está disponível, o endereço de depósito e outras informações (por ex., a hora do servidor, se o sistema está ativo).

Requisição

curl -X GET https://api.tron.discount/energy/info

Resposta

{
  "isSystemActive": true,
  "maximumEnergyAvailable": 1155882352,
  "energyUnitPriceInSun": 50,
  "minEnergyOrderAmount": 32000,
  "depositAddress": "TSD2AWZeyvE4CFvSfYZ1wiPhKoXxWurLUe",
  "serverTime": "2025-04-05T15:24:05.785059Z"
}

Descrição dos campos

Campo Tipo Descrição
isSystemActive Boolean Indica se o marketplace está operacional.
maximumEnergyAvailable Integer Número total de unidades de energia atualmente disponíveis para compra.
energyUnitPriceInSun Integer O custo (em SUN) por unidade de energia. (1 TRX = 1.000.000 SUN)
minEnergyOrderAmount Integer Quantidade mínima de energia (unidades) para um único pedido.
depositAddress String Endereço Tron para o qual os compradores enviam TRX. O sistema delega automaticamente a energia ao remetente assim que o pagamento é recebido.
serverTime String Carimbo de data/hora do servidor no formato ISO.
GET

/energy/order/{depositHash}

Descrição

Recupera o status de um pedido de compra associado ao hash de transação de depósito fornecido.

Requisição

curl -X GET https://api.tron.discount/energy/order/d663302b6a303053b8de9a018ea14cbaca9d0cf0e38a498cc86d04748e3bec14

Resposta

{
  "depositHash": "d663302b6a303053b8de9a018ea14cbaca9d0cf0e38a498cc86d04748e3bec14",
  "delegationHash": "b9458d06b1f05ff5d1b2448afa6efb548f7792dd6997ab9cb4e2ce6fbbd560a0",
  "refundHash": null,
  "status": "ResourcesDelegated",
  "created": "2024-06-01T14:38:32",
  "executed": "2024-06-01T14:40:10",
  "targetAddress": "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf",
  "depositAmount": 3.89,
  "energyAmount": 32416
}

Descrição dos campos

Campo Tipo Descrição
depositHash String Hash de transação do depósito (TRX enviados à plataforma).
delegationHash String Hash de transação da delegação on-chain (se houver).
refundHash String Hash de transação de qualquer reembolso (se aplicável; caso contrário, null).
status String Status do pedido (por ex., «ResourcesDelegated», «Refunded», «Pending», etc.). Veja as descrições de status abaixo.
created String Carimbo de data/hora de quando o pedido foi detectado pela primeira vez.
executed String Carimbo de data/hora de quando o sistema delegou ou processou o pedido com sucesso.
targetAddress String Endereço Tron que recebeu a energia delegada.
depositAmount Number Quantidade de TRX recebida da transação de depósito.
energyAmount Integer Quantidade de unidades de energia delegadas ao endereço de destino.

Valores de status do pedido

Valores possíveis para o campo status:
Status Descrição
Created O pedido foi criado, mas ainda não foi processado.
Pending Pagamento recebido e pedido em processamento.
ResourcesDelegated A energia foi delegada com sucesso ao endereço de destino.
RefundRequested Um reembolso foi solicitado, mas ainda não foi processado.
PendingRefund O reembolso está sendo processado.
Refunded Os TRX foram reembolsados ao remetente.
POST

/energy/order

Chave de API

Descrição

Cria um pedido e debita o seu custo do saldo pré-pago. Ao contrário do depósito, não é necessária qualquer transferência on-chain por pedido.

Carregue o saldo enviando TRX para o seu endereço de recarga pessoal, apresentado no seu painel. Configurações do comprador

Requisição

curl -X POST https://api.tron.discount/energy/order \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiveAddress": "TW7X17...uCntDs2",
    "resourceValue": 32000,
    "rentDurationInHours": 1,
    "clientOrderId": "order-2024-001"
  }'

Campos do pedido

Campo Tipo Descrição
receiveAddress String Endereço Tron que receberá a energia delegada. Obrigatório.
resourceValue Integer Quantidade de unidades de energia a comprar. Obrigatório, no mínimo minEnergyOrderAmount.
rentDurationInHours Integer Duração do aluguer em horas. Opcional; o único valor suportado é 1, que também é o valor predefinido.
clientOrderId String O seu próprio número de pedido, até 64 caracteres. Opcional mas fortemente recomendado: repetir um pedido com o mesmo valor devolve o pedido original em vez de o cobrar duas vezes.

Resposta

{
  "id": 1024,
  "status": "Created",
  "chargedInSun": 1600000,
  "priceInSun": 50,
  "balance": 96.920000
}

Descrição dos campos

Campo Tipo Descrição
id Integer Identificador do pedido. Utilize-o para consultar o estado mais tarde.
status String Estado do pedido, com os mesmos valores do fluxo de depósito. Um pedido acabado de aceitar é «Created».
chargedInSun Integer Montante debitado por este pedido, em SUN.
priceInSun Integer Preço por unidade de energia fixado no momento em que o pedido foi aceite.
balance Number Saldo pré-pago restante em TRX após o débito.

Erros

Um pedido recusado devolve um corpo JSON com um código estável legível por máquina e uma mensagem legível por humanos. Baseie a sua lógica no código: a mensagem não faz parte do contrato e pode mudar a qualquer momento.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance: 1.500000 TRX, required 4 TRX"
}
HTTP code Descrição
400 insufficient_balance Saldo pré-pago insuficiente para este pedido. Carregue o seu endereço e repita o pedido com o mesmo clientOrderId. Nada foi debitado.
400 invalid_address receiveAddress não é um endereço Tron válido. A soma de verificação base58check é validada, pelo que um erro de escrita é rejeitado em vez de ser delegado para o vazio.
400 invalid_resource_value resourceValue está abaixo de minEnergyOrderAmount ou acima do máximo permitido para um único pedido.
400 invalid_rent_duration rentDurationInHours não é 1. A plataforma só aluga energia por uma hora.
400 invalid_client_order_id clientOrderId excede os 64 caracteres.
400 invalid_request O corpo do pedido está ausente ou ilegível.
401 — A chave está ausente, revogada ou é desconhecida.
503 system_inactive O sistema não está a aceitar pedidos neste momento. Tente novamente mais tarde; nada foi debitado.
GET

/account/recharge-address

Chave de API

Descrição

Retorna seu endereço pessoal de recarga. ready é false enquanto o endereço ainda não foi emitido: para uma conta recém-criada ou logo após uma regeneração que não terminou a tempo.

Requisição

curl -X GET https://api.tron.discount/account/recharge-address \
  -H "X-Api-Key: tde_your_key_here"

Resposta

{
  "address": "TQmZ1p...c8XA1",
  "ready": true,
  "nextChangeAllowedAt": "2026-09-12T10:00:00Z"
}
POST

/account/recharge-address/regenerate

Chave de API

Descrição

Substitui seu endereço de recarga por um novo. Permitido uma vez por dia.

O endereço antigo continua aceitando depósitos por 180 dias após a alteração. Transferências que chegarem depois NÃO são creditadas automaticamente.

Requisição

curl -X POST https://api.tron.discount/account/recharge-address/regenerate \
  -H "X-Api-Key: tde_your_key_here"

Resposta

{
  "newAddress": "TAqM7b...pkTdZx",
  "oldAddress": "TQmZ1p...c8XA1",
  "oldAddressActiveUntil": "2027-03-10T10:00:00Z",
  "nextChangeAllowedAt": "2026-09-12T10:00:00Z"
}

Erros

Código HTTP code Significado
429 address_change_too_soon Menos de um dia desde a alteração anterior. O cabeçalho Retry-After informa quantos segundos aguardar.
GET

/energy/order/api/{id}

Chave de API

Descrição

Devolve o estado de um pedido feito pela API. Os pedidos pagos com o saldo não têm hash de depósito, pelo que são identificados pelo id devolvido no momento da aceitação.

Apenas os seus pedidos são visíveis: um id de outra conta devolve 404.

Requisição

curl -X GET https://api.tron.discount/energy/order/api/1024 \
  -H "X-Api-Key: YOUR_API_KEY"

Resposta

{
  "id": 1024,
  "clientOrderId": "order-2024-001",
  "status": "ResourcesDelegated",
  "receiveAddress": "TW7X17...uCntDs2",
  "resourceValue": 32000,
  "rentDurationInHours": 1,
  "chargedInSun": 1600000,
  "created": "2025-04-05T15:24:05.785059Z",
  "updated": "2025-04-05T15:24:41.120344Z"
}

Os valores de estado são os mesmos do fluxo de depósito, indicados acima.

Notas adicionais

Autenticação

Os endpoints GET de informação da plataforma e de pedidos por depósito continuam públicos e não precisam de chave. Comprar energia com o saldo exige uma chave de API no cabeçalho X-Api-Key.

Gerar uma nova chave invalida imediatamente a anterior, e a chave é apresentada apenas uma vez.

Duas formas de encomendar

Enviar TRX para o endereço de depósito cria um pedido implicitamente e não precisa de chave. Encomendar a partir do saldo pré-pago exige uma chamada à API e nenhuma transferência on-chain. Ambos são processados pela mesma cadeia e partilham os mesmos estados.

Unidades de energia e SUN

Lembre-se: 1 TRX = 1.000.000 SUN. Então, se energyUnitPriceInSun for 50, isso significa 0.000050 TRX por unidade de energia.

Criação implícita de pedidos

Um «pedido» é criado automaticamente sempre que TRX são enviados ao endereço de depósito. Use o hash de transação do depósito para acompanhar o status.

Hora do servidor

Os horários são fornecidos no formato ISO 8601 (UTC). Considere os fusos horários ao compará-los com os horários locais.