Cote e depois compre com max_price_trx
Um app conectado precisa enviar max_price_trx para buy_energy e buy_bandwidth. Sem ele, a chamada falha com MAX_PRICE_REQUIRED — o limite diário precisa saber o máximo que uma chamada pode custar.
- Chame
quote_energy(ouquote_bandwidth) com o volume e a duração. - Mostre ao usuário o
total_trxda cotação. - Chame
buy_energycom o mesmo volume e a mesma duração emax_price_trx= ototal_trxda cotação.
max_price_trx, a compra é recusada com PRICE_CHANGED e nada é cobrado. Cote de novo e pergunte ao usuário.
Para uma chave de API, max_price_trx é opcional, mas recomendamos usá-lo pelo mesmo motivo.
Chaves de idempotência
As ferramentas que criam algo aceitamidempotency_key — o cabeçalho Idempotency-Key da rota delas. Gere um UUID novo para cada nova ação e reutilize-o ao repetir a mesma ação após um timeout ou uma resposta perdida: o servidor devolve o primeiro resultado em vez de cobrar de novo. Uma chave vale 24 horas e tem no máximo 64 caracteres.
A mesma chave com uma requisição diferente é recusada com
IDEMPOTENCY_KEY_REUSED; uma chave cuja primeira requisição ainda está em andamento responde IDEMPOTENT_REQUEST_IN_PROGRESS — aguarde e tente de novo com a mesma chave.
O limite diário de gastos
Cada conexão pode gastar um valor definido em quaisquer 24 horas — 100 TRX, a menos que o usuário tenha escolhido outro valor na tela de consentimento ou em Aplicativos conectados. Só o dono da conta pode remover o limite.- Antes de uma chamada que gasta, o servidor reserva o máximo que ela pode custar:
max_price_trxmais a ativação de um endereço novo nas compras, o preço no Smart Mode, pacotes, ativações e planos do Node API, o valor em um stake. - Depois da chamada, a reserva vira o valor real, ou é liberada se nada foi cobrado. Se o resultado é desconhecido (um timeout), a reserva fica por 24 horas — na dúvida, o limite prefere recusar.
- Gastos que rodam sozinhos (
recurring) ficam fora do limite. - Aplicativos conectados no painel mostra quanto cada app gastou nas últimas 24 horas.
AGENT_SPEND_CAP:
Repetir uma compra cuja resposta se perdeu reserva o valor de novo. Perto do limite, confira
list_orders antes de repetir: a primeira chamada pode ter sido concluída.Origem do pedido
Os pedidos feitos por um app conectado trazem"source": "agent" — em get_order, list_orders e no webhook order.updated. Os pedidos feitos com uma chave de API trazem "source": "api".
Códigos de erro
Via MCP, um erro chega como resultado de ferramenta comisError: true:
Todos os outros códigos são os da API REST — veja Erros.
Um token expirado ou revogado recebe HTTP
401 com WWW-Authenticate: Bearer ... error="invalid_token" na própria requisição a /mcp; os clientes MCP então renovam o token ou pedem ao usuário que entre de novo.