Saltar para o conteúdo principal

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.
  1. Chame quote_energy (ou quote_bandwidth) com o volume e a duração.
  2. Mostre ao usuário o total_trx da cotação.
  3. Chame buy_energy com o mesmo volume e a mesma duração e max_price_trx = o total_trx da cotação.
Se o preço subir acima de 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 aceitam idempotency_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_trx mais 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.
Uma chamada que não cabe falha com 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 com isError: true:
Via REST, o mesmo código chega no formato de erro padrão. 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.