Configure controles de gastos do agente que sobrevivem à injeção de prompt.
Defina uma permissão de gasto no painel - uma concessão por período mais um limite por transação - e o backend a aplica em cada pagamento. Como ela reside no backend e a API é somente leitura, a injeção de prompt que sequestra o planejador do agente ainda não pode aumentar o limite. Seu código lê a permissão pela API para exibi-la ou planejar em torno dela.
Antes de você começar.
- Um agente existente (veja o add-payments-to-agent guide).
- Acesso ao painel para o espaço de trabalho que possui o agente - as permissões são definidas lá, não pela API.
- Uma ideia aproximada do gasto diário esperado - a concessão deve ser 2-3x o uso normal, não 100x, para que seja realmente estrutural.
- Uma chave API para ler a permissão (uma chave
sk_test_é adequada para este guia). - Familiaridade com o conceito de política de gastos do agente - este guia é seu contraparte operacional.
Defina a permissão no painel.
Abra o agente no painel do Blockchain0x e defina dois números: uma concessão por um período (um dia, uma semana ou 30 dias) e um limite por transação. A concessão limita o pior cenário ao longo de todo o período; o limite por transação impede que um único pedido anômalo gaste tudo de uma vez. Esta é uma ação do painel de propósito - é o limite definido por humanos dentro do qual o agente opera.
Amounts are USDC base units (6 decimals). An allowance_wei of "20000000" is 20 USDC; a per_tx_wei of "2000000" is 2 USDC. The period is a period_seconds value: 86400 for a day, 604800 for a week, 2592000 for 30 days.
Leia a permissão via a API.
Seu código pode buscar a permissão ao vivo para mostrá-la em uma interface ou para permitir que o agente verifique quanto espaço resta antes de tentar um pagamento. A rota é somente leitura - não há endpoint de mutação, que é exatamente o motivo pelo qual a chave do agente não pode ampliar seu próprio limite.
curl https://api.blockchain0x.com/v1/agents/agt_123/spend-permissions \
-H "Authorization: Bearer $BLOCKCHAIN0X_API_KEY"{
"allowance_wei": "20000000",
"per_tx_wei": "2000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"end_at": null,
"revoked_at": null
}Vincule-o no tempo ou revogue-o.
Dois campos transformam a permissão em um controle com limite de tempo. start_at e end_at definem a janela em que está ativo, para que você possa pré-estabelecer um orçamento para um trabalho agendado ou deixar um expirar por conta própria; fora da janela, não autoriza nada. revoked_at é o interruptor de desligamento: revogue do painel e a permissão cai para zero para qualquer pagamento avaliado posteriormente.
Para uma parada mais drástica, revogue ou rotacione a chave de API do agente com apiKeys.revoke ou apiKeys.rotate - isso corta a credencial completamente, não apenas o gasto. A revogação da permissão é a ação cirúrgica; a revogação da chave é o interruptor de emergência.
Gerencie um pagamento que atinge o limite.
Quando um pagamento excede a permissão ativa, o backend o rejeita antes que qualquer coisa toque a cadeia - nenhum fundo se move. Sua chamada payments.create retorna um erro; trate-o como qualquer outra chamada falhada, apresente-o ao seu operador e não tente novamente cegamente na mesma parede.
Para ver o que um agente tentou, observe o log de atividades do painel e reconcilie movimentos reais com transactions.get. Um aumento de tentativas rejeitadas é seu sinal de alerta precoce: ou uma permissão mal configurada, um loop descontrolado ou uma sondagem de injeção. Alerta sobre isso da mesma forma que você faria em qualquer pico de chamadas falhadas.
Cinco erros que derrotam o controle.
Colocando o limite de gasto no código do agente em vez do backend
As regras de gasto no planejador do agente ou no prompt do sistema não são limites de segurança. Um ataque de injeção de prompt que substitui o planejador também substitui o limite. O objetivo de uma permissão de gasto é que ela reside fora do escopo manipulável do agente - no backend, definida no painel - para que o agente não possa alterá-la. Configure-a lá, não com 'diga ao agente para não gastar mais de $X'.
Esperando que a chave de API do agente amplie o limite
A API é somente leitura para permissões de gasto: não há endpoint e nenhum método SDK que aumente uma concessão. Isso é intencional. Se um agente comprometido ou injetado pudesse chamar um endpoint de mutação com a chave que já possui, o controle seria inútil. Para alterar um limite, você usa o painel, onde a mudança é uma ação humana com um registro de auditoria.
Definindo uma concessão tão alta que nunca causa problemas
Uma permissão só protege você se for estrutural. Uma concessão definida em 100x o uso normal não interromperá um loop descontrolado até que já tenha gasto muito mais do que você gostaria. Defina a concessão e o limite por transação em cerca de 2-3x o uso esperado, depois amplie deliberadamente se o tráfego real provar que você precisa.
Esquecendo o limite por transação
allowance_wei limita o pior caso ao longo de todo o período; per_tx_wei limita qualquer pagamento único. Eles desempenham funções diferentes. Uma concessão generosa de período sem limite por transação ainda permite que um pedido anômalo - uma nova tentativa com bug, um preço malicioso - mova uma grande quantia em uma única vez. Defina ambos.
Nenhum interruptor de desligamento rápido ensaiado.
Quando algo parece errado às 2 da manhã, você quer um movimento que já praticou. Existem duas opções: revogar a permissão no painel (define revoked_at, allowance para zero), ou revogar/rotacionar a chave API do agente com apiKeys.revoke / apiKeys.rotate (corta completamente a credencial). Saiba qual você deve usar e que pode fazê-lo rapidamente.
Após a permissão estar em vigor.
Com a permissão aplicada, os seguimentos que mais compensam são a manipulação confiável de webhook (para que os eventos de pagamento realmente cheguem ao seu manipulador), verificação de identidade (para que as contrapartes confiem no perfil do agente) e uma revisão de segurança pré-lançamento (para que você não tenha deixado outra porta aberta).
Os padrões de webhook que os desenvolvedores mais perguntam
Ganhe os badges de verificação do GitHub e do domínio
Proteja sua carteira de agente antes de ir ao vivo
Referência completa em docs.blockchain0x.com. Superfície de produto: Controles de Gastos.