Orchestrator — pedidos em lote em uma única chamada

Envie até 100 endereços em uma única requisição e deixe o Netts realizar toda a sequência para cada um: ativar o endereço se necessário, recarregar sua Bandwidth se estiver insuficiente e, em seguida, alugar a Energy — dividindo grandes quantias em frações automaticamente.

Você recebe um 202 Accepted imediato com uma chave de rastreamento e nunca fica esperando na conexão. O progresso é então consultado a partir do endpoint de status.

Por que usar

Solicitar Energy para um novo endereço normalmente exige três chamadas separadas, na ordem correta, com sua própria lógica de novas tentativas entre elas. O orchestrator reduz isso a uma única requisição e executa a sequência por endereço:

probe → activation (if the address is not active) → bandwidth (if free < 400) → energy

Uma falha na ativação ou na Bandwidth não interrompe o pedido de Energy para esse endereço, e a falha em um endereço nunca afeta os demais.

URL base do endpoint

https://netts.io/apiv2/orchestrator

Cabeçalhos da Requisição

Cabeçalho	Obrigatório	Descrição
Content-Type	Sim	application/json
X-API-KEY	Sim	Sua chave de API do painel Netts
X-Real-IP	Sim	Endereço IP da sua lista de permissões
X-Idempotency-Key	Sim*	Sua chave para este pedido, 12–128 caracteres de `A-Z a-z 0-9 . _ : -`

* É obrigatório fornecer o cabeçalho X-Idempotency-Key ou o campo clientRequestId no corpo. Se você não enviar nenhum dos dois, a requisição será rejeitada com 5010.

A chave identifica o pedido como um todo. Repetir uma requisição com a mesma chave retorna o resultado original em vez de criar um segundo pedido — consulte Idempotência.

Criar um pedido — `POST /apiv2/orchestrator`

Corpo da requisição

json

{
    "clientRequestId": "my-batch-2026-01-01-001",
    "defaults": {
        "bandwidth": true,
        "bandwidthAmount": 400,
        "bandwidthPeriod": "1h",
        "check": true,
        "trx_send": false
    },
    "items": [
        { "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000 },
        { "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
        { "receiveAddress": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "amount": 61000, "bandwidth": false }
    ]
}

Campos de nível superior

Campo	Tipo	Obrigatório	Descrição
`items`	array	Sim	1 a 100 endereços. Duplicatas no mesmo pedido são rejeitadas.
`clientRequestId`	string	Não	Sua referência de pedido, 8–128 caracteres de `A-Z a-z 0-9 . _ : -`. Funciona também como a chave de idempotência caso o cabeçalho esteja ausente.
`defaults`	object	Não	Valores aplicados a todos os itens que não os substituam.

Campos do item

Todos os campos, exceto receiveAddress e amount, também podem ser definidos em defaults. Um valor no item tem precedência sobre o padrão.

Campo	Tipo	Padrão	Descrição
`receiveAddress`	string	—	Endereço TRON que recebe a Energy
`amount`	int	—	Energy para este endereço, 61 000 … 50 000 000
`bandwidth`	bool	`true`	Pedir Bandwidth para este endereço caso esteja insuficiente
`bandwidthAmount`	int	`400`	`400` ou `5000`
`bandwidthPeriod`	string	`1h`	`5m` ou `1h`
`check`	bool	veja abaixo	Verificar a Bandwidth gratuita primeiro e ignorar o pedido se houver o suficiente
`trx_send`	bool	`false`	Repassado ao serviço de Bandwidth
`activation`	bool	`true`	Ativar o endereço se ele não estiver ativo. Defina como `false` para pular a etapa em um endereço que você sabe que já está ativo.

check tem como padrão true quando bandwidthAmount é 400, e false caso contrário — pedir 5 000 unidades geralmente significa que você as deseja independentemente do que já estiver disponível.

As quantias são por endereço. Uma única requisição pode misturar quantias diferentes livremente; o único limite é o total.

Limites

Limite	Valor
Endereços por pedido	100
Energy por endereço	61 000 … 50 000 000
Energy total por pedido	50 000 000
Pedidos em andamento por conta	3
Endereços em andamento por conta	300
Saldo mínimo para ser aceito	4 TRX

O teto de 50 000 000 se aplica à soma de todos os endereços na requisição, não a cada um individualmente.

Resposta — aceito (202, código `10202`)

json

{
    "detail": {
        "code": 10202,
        "status": "accepted",
        "msg": "Order accepted for processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "itemsAccepted": 3,
            "statusUrl": "/apiv2/orchestrator/status/my-batch-2026-01-01-001",
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "amount": 65000,
                    "energyChunks": 1,
                    "activation": "planned",
                    "bandwidth": "planned",
                    "status": "queued"
                }
            ]
        }
    }
}

202 significa enfileirado, não executado. Nada foi cobrado ainda. Consulte statusUrl para obter o resultado.

trackingId é o par chave de idempotência + endereço — a identificação de um endereço dentro do seu pedido. Use-o em seus próprios logs e conciliações.

Exemplo

bash

curl -X POST https://netts.io/apiv2/orchestrator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: my-batch-2026-01-01-001" \
  -d '{
        "items": [
          {"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", "amount": 65000}
        ]
      }'

Verificar progresso — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Adicione ?address=T… para obter um único endereço em vez do pedido inteiro.

json

{
    "detail": {
        "code": 10000,
        "status": "processing",
        "data": {
            "idempotencyKey": "my-batch-2026-01-01-001",
            "requestId": 1234,
            "clientRequestId": "my-batch-2026-01-01-001",
            "summary": {
                "total": 3, "queued": 1, "processing": 1, "completed": 1,
                "partial": 0, "failed": 0, "insufficient_balance": 0,
                "credentials_revoked": 0, "cancelled": 0
            },
            "items": [
                {
                    "deliveryKey": 5001,
                    "trackingId": "my-batch-2026-01-01-001:TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                    "status": "completed",
                    "energy": {
                        "requested": 65000,
                        "delegated": 65000,
                        "status": "done",
                        "chunks": { "total": 1, "done": 1 },
                        "orderIds": ["1Hxxxxxxxxxx"],
                        "hashes": ["0000000000000000000000000000000000000000000000000000000000000000"]
                    },
                    "activation": { "status": "not_needed", "orderId": null, "hash": null },
                    "bandwidth": {
                        "status": "enough", "orderId": "B1Hxxxxxxxxxxxxxx",
                        "amount": 400, "period": "1h", "hashes": [], "skipReason": null
                    },
                    "attempts": 1,
                    "startedAt": "2026-01-01T00:00:00+00:00",
                    "finishedAt": "2026-01-01T00:00:03+00:00"
                }
            ]
        }
    }
}

Uma chave desconhecida, ou pertencente a outra conta, retorna 404.

Valores de status do endereço

Status	Significado
`queued`	Aguardando para ser processado
`processing`	Em andamento
`completed`	Toda a Energy solicitada foi delegada
`partial`	Algumas frações foram entregues, outras falharam
`failed`	Nada foi entregue
`insufficient_balance`	Interrompido — seu saldo caiu abaixo do mínimo
`credentials_revoked`	Sua chave de API foi removida ou desativada enquanto o pedido estava em execução
`cancelled`	Removido da fila pela sua solicitação de cancelamento

Valores de status da etapa

Etapa	Valores
`activation`	`not_needed`, `done`, `failed`, `skipped`, `skipped_unavailable`
`bandwidth`	`enough`, `done`, `failed`, `skipped`
`energy`	`done`, `partial`, `failed`

bandwidth.skipReason explica o motivo de skipped: option_off (você desativou a opção), energy_gt_600000 (pedidos grandes de Energy não precisam de recarga de Bandwidth).

Hashes de delegação

energy.hashes é o seu comprovante de entrega. Quando a Energy vem de um provedor externo, o hash não é conhecido no momento do pedido — ele é preenchido cerca de um minuto depois, e o endereço não é relatado como concluído até que os hashes sejam coletados ou a janela de espera expire. Um endereço em completed com um hash presente está totalmente liquidado.

Cancelar — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Remove da fila todos os endereços que ainda não começaram a ser processados.

json

{
    "detail": {
        "code": 10005,
        "status": "cancelled",
        "msg": "Order cancelled: 7 addresses removed from queue",
        "data": { "cancelled": 7 }
    }
}

Endereços já em processing não são interrompidos: parte de sua Energy já pode ter sido paga. O cancelamento opera no melhor esforço para o restante.

Idempotência

O pedido é identificado pela sua chave — o cabeçalho X-Idempotency-Key ou clientRequestId quando o cabeçalho estiver ausente.

Repetição de requisição	Resultado
Mesma chave, mesmo corpo	208 com o pedido original e `originalAcceptedAt` — nenhum segundo pedido criado
Mesma chave, corpo diferente	409 `4090 IDEMPOTENCY_CONFLICT`

Portanto, em caso de timeout de rede do seu lado, é seguro repetir exatamente a mesma requisição. Alterar o conteúdo sob uma chave já utilizada é rejeitado em vez de aplicado silenciosamente.

Dentro do pedido, cada endereço possui sua própria chave interna, portanto, uma repetição nunca cobra duas vezes um único endereço.

Cobrança

O orchestrator em si não cobra nada. Cada etapa é cobrada pelo serviço que a executa, em seu preço normal:

Etapa	Cobrado como
Ativação	dedução separada, número do pedido `A…`
Bandwidth	dedução separada, número do pedido `B1H…` — apenas quando efetivamente delegada
Energy	uma dedução por fração, número do pedido `1H…`

check: true com Bandwidth gratuita suficiente não custa nada — o status fica como enough e nenhum pedido é realizado. Grandes quantias de Energy ignoram a Bandwidth inteiramente.

Se o seu saldo acabar no meio do lote, os endereços restantes são finalizados como insufficient_balance sem que sejam tentados.

Referência de Códigos de Erro

Código	Descrição	Status HTTP
`10202`	Pedido aceito / já aceito	202 / 208
`10000`	Status retornado	200
`10005`	Pedido cancelado	200
`5004`	Campo inválido: formato de endereço, `amount` fora do intervalo, `bandwidthAmount` diferente de 400/5000, `bandwidthPeriod` diferente de 5m/1h, corpo não é um objeto JSON	400
`5005`	`items` ausente ou vazio	400
`5006`	`receiveAddress` duplicado em um mesmo pedido	400
`5009`	`X-Idempotency-Key` ou `clientRequestId` malformado	400
`5010`	Nem `X-Idempotency-Key` nem `clientRequestId` foram fornecidos	400
`5012`	Energy total na requisição excede 50 000 000	400
`-1`	Chave de API inválida / IP fora da lista de permissões	401
`1004`	Saldo abaixo do mínimo de 4 TRX	402
`-1`	Pedido não encontrado (ou não pertence a você)	404
`4090`	`IDEMPOTENCY_CONFLICT` — mesma chave, corpo diferente	409
`4220`	Validação da requisição falhou (detalhes em `data.errors`)	422
`429` / `5011`	Muitos pedidos, endereços ou frações em andamento	429
`5003`	Pedido não foi aceito — serviço temporariamente indisponível, seguro tentar novamente	503

Um 503 na criação é à prova de falhas: nada foi armazenado e nada foi cobrado.

Limites de Taxa

Limitado por IP de origem:

Período	Limite
1 segundo	20 requisições

Limite de Taxa Excedido (429)

json

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

Observações

202 não é um comprovante de entrega. Trate-o como "enfileirado". O resultado fica disponível no endpoint de status.
Os endereços são processados em paralelo, até 5 de cada vez dentro de um pedido, para que um lote grande não fique travado por conta de um único endereço lento. A ordem de conclusão não é garantida.
O fracionamento é automático: quantias acima de 1 000 000 são divididas em frações iguais, cada uma se tornando seu próprio pedido de Energy. energy.orderIds e energy.hashes listam todas elas.
Não há webhook para pedidos do orchestrator como um todo. Cada delegação de Energy ainda produz o webhook habitual delegation.confirmed, consulte Webhooks.
Endpoints relacionados: Activator, Bandwidth, Order 1H.

Orchestrator — pedidos em lote em uma única chamada ​

Por que usar ​

URL base do endpoint ​

Cabeçalhos da Requisição ​

Criar um pedido — POST /apiv2/orchestrator ​

Corpo da requisição ​

Campos de nível superior ​

Campos do item ​

Limites ​

Resposta — aceito (202, código 10202) ​

Exemplo ​

Verificar progresso — GET /apiv2/orchestrator/status/{idempotencyKey} ​

Valores de status do endereço ​

Valores de status da etapa ​

Hashes de delegação ​

Cancelar — POST /apiv2/orchestrator/cancel/{idempotencyKey} ​

Idempotência ​

Cobrança ​

Referência de Códigos de Erro ​

Limites de Taxa ​

Limite de Taxa Excedido (429) ​

Observações ​

Orchestrator — pedidos em lote em uma única chamada

Por que usar

URL base do endpoint

Cabeçalhos da Requisição

Criar um pedido — `POST /apiv2/orchestrator`

Corpo da requisição

Campos de nível superior

Campos do item

Limites

Resposta — aceito (202, código `10202`)

Exemplo

Verificar progresso — `GET /apiv2/orchestrator/status/{idempotencyKey}`

Valores de status do endereço

Valores de status da etapa

Hashes de delegação

Cancelar — `POST /apiv2/orchestrator/cancel/{idempotencyKey}`

Idempotência

Cobrança

Referência de Códigos de Erro

Limites de Taxa

Limite de Taxa Excedido (429)

Observações