Proteja sua carteira de agente antes de entrar ao vivo.
Ir para produção com pagamentos de agentes não é a mesma lista de verificação que uma integração normal de API. Adicione: uma escolha deliberada do tipo de carteira, uma política de gastos ajustada (não padrões), rotação de segredos de API e webhook em uma cadência definida, uma revisão semanal de logs de auditoria e um runbook de resposta a incidentes que tenha sido treinado pelo menos uma vez. Sem isso, você envia e aprende da maneira difícil.
Antes de você começar.
- Uma integração de agente funcionando de ponta a ponta em teste - veja add-payments-to-agent e test-without-real-money.
- Controles de gasto configurados - veja controles de gasto (este guia assume que uma política já está em vigor).
- Um gerenciador de segredos (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, etc) - segredos em arquivos .env não são suficientes.
- Um engenheiro de plantão claramente identificado com acesso administrativo ao painel da carteira.
- 15 minutos de tempo focado. A lista de verificação abaixo não é aspiracional - trabalhe linha por linha.
Execute a lista de verificação pré-lançamento.
Onze itens. Cada um é uma pergunta de sim/não com um único proprietário. Se algum item não estiver marcado, não vá ao ar - trabalhe nesse item até a conclusão primeiro. O custo de um item perdido em produção é sempre maior do que o custo de finalizá-lo agora.
# Pre-launch security checklist for agent wallets.
[ ] Wallet type chosen with reasoned trade-offs (smart wallet vs EOA).
[ ] Spend permission set in the dashboard: an allowance per period + a per-transaction cap.
[ ] API keys scoped to the minimum the agent needs (read_wallet_metadata / pay_bills / receive_money).
[ ] All API keys stored in a secret manager (not env files committed to git).
[ ] Test keys and live keys cannot be swapped (boot-time prefix check in place).
[ ] Webhook secret rotated within the last 90 days (webhooks.rotateSecret).
[ ] Webhook URL pointed at production, not a tunnel.
[ ] Audit review scheduled; alerting in place for unusual events.
[ ] A spike of rejected payments triggers an alert (>5/hour from one agent).
[ ] Incident runbook exists, has been read by someone other than the author.
[ ] One person other than you knows how to revoke an API key in < 5 minutes.Agende a rotação da chave da API e do segredo do webhook.
Trimestral é a cadência padrão; gire imediatamente em qualquer um dos seguintes: suspeita de vazamento, saída do engenheiro principal, incidente de segurança em outra parte da empresa. O padrão de janela de duas chaves permite que você troque chaves sem tempo de inatividade: crie a nova chave, implemente-a em todos os lugares, verifique e, em seguida, revogue a antiga.
// One-time key rotation script. Run quarterly, on lead departure, on suspected leak.
import { createClient } from "@blockchain0x/node";
const client = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! });
async function rotate() {
// Scope the new key to only what the agent needs.
const fresh = await client.apiKeys.create({
name: `prod-${new Date().toISOString().slice(0, 10)}`,
scopes: ["read_wallet_metadata", "pay_bills", "receive_money"],
});
console.log("NEW KEY:", fresh.secret); // Store in secret manager NOW.
// Wait until the new key is deployed and verified working, THEN:
// await client.apiKeys.revoke(OLD_KEY_ID); // (or apiKeys.rotate in one call)
}# One-time key rotation script. Run quarterly, on lead departure, on suspected leak.
from blockchain0x import Client
import datetime, os
client = Client() # reads BLOCKCHAIN0X_API_KEY
def rotate():
fresh = client.api_keys.create(body={
"name": f"prod-{datetime.date.today().isoformat()}",
"scopes": ["read_wallet_metadata", "pay_bills", "receive_money"],
})
print("NEW KEY:", fresh["secret"]) # Store in secret manager NOW.
# Wait until new key is deployed and verified, THEN:
# client.api_keys.revoke(OLD_KEY_ID) # (or api_keys.rotate in one call)Os segredos de assinatura de webhook giram de maneira semelhante através do painel - habilite um segundo segredo, reimplante o manipulador para aceitar ambos, e depois retire o antigo. Ambos em uma cadência trimestral com lembretes de calendário.
Configure a revisão de auditoria semanal.
Três coisas para observar toda semana: novos parceiros (qualquer coisa não vista antes merece uma verificação de sanidade de 30 segundos), pagamentos rejeitados (a permissão de gasto fez seu trabalho - o agente ficou preso em algum lugar?), e pagamentos fora do horário (um pagamento às 3 da manhã de um agente que nominalmente só opera em horário comercial é o tipo de sinal que captura ataques de injeção precocemente).
// Weekly audit query over the webhook events YOU persisted (payment.received /
// payment.sent). There is no transactions.list API - your own store is the log.
const since = Date.now() - 7 * 24 * 60 * 60 * 1000;
const events = await db.paymentEvents.findMany({ where: { receivedAt: { gte: since } } });
const newCounterparties = events.filter((e) => e.counterpartyFirstSeen);
const offHours = events.filter((e) => {
const h = new Date(e.receivedAt).getUTCHours();
return h < 5 || h > 22;
});
// Reconcile anything that looks off against the chain:
// const tx = await client.transactions.get(event.txHash);
console.log({ newCounterparties, offHours });from datetime import datetime, timedelta, timezone
# Query your own persisted webhook events - the SDK has transactions.get(id),
# not a list endpoint, so your event store is the audit log.
since = datetime.now(timezone.utc) - timedelta(days=7)
events = db.payment_events.where(received_at__gte=since)
new_counterparties = [e for e in events if e.counterparty_first_seen]
off_hours = [e for e in events if not (5 <= e.received_at.hour <= 22)]
# Reconcile against the chain when something looks off:
# tx = client.transactions.get(event.tx_hash)
print({"new_counterparties": new_counterparties, "off_hours": off_hours})Escreva (e treine) o runbook de incidentes.
Um runbook é tão bom quanto a última vez que foi testado. Abaixo está o modelo - copie-o para o wiki da sua equipe, edite para suas especificidades e agende um exercício de 30 minutos no próximo trimestre. Cronometre; conserte o que o exercício revelar como ausente.
# Incident response runbook - Agent wallet compromise (suspected or confirmed)
## Trigger
Any of:
- Unrecognised counterparty receiving > $10 USDC.
- > 50 rejected payment attempts from one agent in an hour.
- Engineer reports they cannot account for a recent payment.
- A leaked API key surfaces in a public scan.
## Step 1 - Stop the bleeding (< 5 minutes)
- Revoke the suspect API key: dashboard, or apiKeys.revoke / apiKeys.rotate.
- Revoke the agent's spend permission in the dashboard (allowance to zero).
- A revoked key cannot move funds and a revoked permission authorizes nothing.
## Step 2 - Preserve evidence (< 15 minutes)
- Pull the last 24h from the dashboard activity log and your stored events.
- Note the agent's spend permission as it was at the time of the incident.
- Note the timestamps of any unrecognised payments and their txHash on Base
(fetch with transactions.get).
## Step 3 - Communicate (< 30 minutes)
- Inform the on-call lead and finance.
- If customer funds are affected, draft a notification template (do not send
until investigation is far enough along to be accurate).
## Step 4 - Root cause and remediation (24-72 hours)
- Determine: leaked key, compromised webhook secret, prompt-injection
bypass, integration bug, or other.
- Rotate every secret that could have been exposed.
- Tighten the spend permission (lower the allowance or per-transaction cap).
- File a post-mortem with timeline, RCA, and follow-ups.Cinco coisas que pegam as equipes em seu primeiro incidente de produção.
Tratando um novo agente como 'igual ao antigo'
Cada agente tem seu próprio perfil, suas próprias chaves, sua própria política de gastos. Se você reutilizar chaves entre agentes 'porque são semelhantes', uma única violação de chave compromete todos os agentes de uma vez. Criar um novo perfil de agente leva uma chamada de API; a isolação por agente vale o minuto que custa para fazê-lo corretamente.
Permissão de gasto dimensionada por palpite, não por dados
Defina a verba e o limite por transação no chute e uma de duas coisas acontece: se for baixo demais, o agente bate no limite no meio do dia, todos os dias, enquanto você depura 'payment rejected'; se for alto demais, o controle vira teatro. Na primeira semana, observe o gasto diário real e ajuste a verba para 2-3x esse valor - não 1x (restritivo demais) e não 100x (praticamente ilimitado). É uma alteração no dashboard, então recalibrar é barato.
Segredo de assinatura do webhook nunca rotacionado
Um incidente que vaza o segredo do webhook significa que um atacante pode forjar webhooks que parecem eventos legítimos de payment.received, o que pode enganar seu manipulador a entregar trabalho que nunca foi pago. Rotacione o segredo (webhooks.rotateSecret) na mesma cadência que as chaves da API (trimestralmente) ou sempre que suspeitar de exposição, e sempre verifique as entregas com webhooks.verify em relação ao segredo atual.
Logs de auditoria que ninguém lê
Um registro de auditoria só captura coisas se alguém olhar para ele. A maioria das equipes ativa o registro, nunca olha para ele e descobre sobre problemas por meio de reclamações de clientes. Agende uma revisão semanal de 15 minutos: novos parceiros, pagamentos rejeitados, pagamentos fora do horário. O custo é pequeno; o tempo para detectar cai de semanas para dias.
Sem simulação no runbook de incidentes
Um runbook que nunca foi exercitado é ficção. Escolha uma data trimestral, simule um cenário de chave vazada, cronometre quanto tempo leva para revogar e conter. O primeiro exercício sempre revela algo faltando (o engenheiro que sabe como rotacionar está de férias, o runbook está atrás de um link do Notion expirado). Melhor descobrir isso em um exercício do que às 3 da manhã durante um incidente real.
Após o passe de segurança.
A segurança nunca está concluída, mas o restante da pilha operacional se beneficia de uma base limpa. Aperte os controles de gastos à medida que os dados de uso real se acumulam, endureça o manuseio de webhooks contra carga e verifique a identidade do agente para que as contrapartes confiem em seu perfil público.
Configure controles de gastos do agente que sobrevivem à injeção de prompt
Os padrões de webhook que os desenvolvedores mais perguntam
Ganhe os badges de verificação do GitHub e do domínio
Referência completa em docs.blockchain0x.com. Glossário relacionado: Coinbase Smart Wallet. Superfície de produto: Carteiras de Agente.