Asegura tu billetera de agente antes de salir en vivo.
Ir a producción con pagos de agentes no es la misma lista de verificación que una integración normal de API. Agrega: una elección deliberada del tipo de billetera, una política de gasto ajustada (no predeterminados), rotación de secretos de API y webhook en una cadencia establecida, una revisión semanal del registro de auditoría y un libro de respuestas a incidentes que se ha practicado al menos una vez. Sin estos, envías y aprendes de la manera difícil.
Antes de comenzar.
- Una integración de agente funcional de extremo a extremo en prueba - consulta add-payments-to-agent y test-without-real-money.
- Controles de gasto configurados - ver controles de gasto (esta guía asume que ya hay una política en su lugar).
- Un gestor de secretos (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, etc) - los secretos en archivos .env no son suficientes.
- Un ingeniero de guardia claramente identificado con acceso de administrador al panel de control de la billetera.
- 15 minutos de tiempo enfocado. La lista de verificación a continuación no es aspiracional - trabaje en ella línea por línea.
Ejecuta la lista de verificación previa al lanzamiento.
Once elementos. Cada uno es una pregunta de sí/no con un solo propietario. Si algún elemento no está marcado, no salgas en vivo - trabaja ese elemento hasta cerrarlo primero. El costo de un elemento perdido en producción siempre es mayor que el costo de terminarlo ahora.
# 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.Programa la rotación de la clave de API y el secreto del webhook.
Trimestral es la cadencia predeterminada; rota inmediatamente en cualquiera de: fuga sospechosa, salida del ingeniero principal, incidente de seguridad en otra parte de la empresa. El patrón de ventana de dos claves te permite intercambiar claves sin tiempo de inactividad: crea la nueva clave, despliega en todas partes, verifica y luego revoca la antigua.
// 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)Los secretos de firma de webhook rotan de manera similar a través del panel: habilite un segundo secreto, redeploye el controlador para aceptar cualquiera, y luego retire el antiguo. Ambos con una cadencia trimestral y recordatorios en el calendario.
Configure la revisión de auditoría semanal.
Tres cosas a las que mirar cada semana: nuevos contrapartes (cualquier cosa no vista antes merece una verificación de cordura de 30 segundos), pagos rechazados (el permiso de gasto hizo su trabajo - ¿se atascó el agente en algún lugar?), y pagos fuera de horario (un pago a las 3am de un agente que nominalmente solo opera en horario laboral es el tipo de señal que atrapa ataques de inyección temprano).
// 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})Escribe (y practica) el libro de incidentes.
Un runbook es tan bueno como la última vez que fue probado. A continuación está la plantilla: cópiala en la wiki de tu equipo, edítala para tus especificaciones y programa un simulacro de 30 minutos en el próximo trimestre. Cronométralo; corrige lo que el simulacro revele que falta.
# 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 cosas que atrapan a los equipos en su primer incidente de producción.
Tratando a un nuevo agente como 'igual que el anterior'
Cada agente obtiene su propio perfil, sus propias claves, su propia política de gasto. Si reutilizas claves entre agentes 'porque son similares', un compromiso de clave único afecta a todos los agentes a la vez. Crear un nuevo perfil de agente requiere una llamada a la API; la aislamiento por agente vale la pena el minuto que cuesta hacerlo correctamente.
Permiso de gasto dimensionado por conjetura, no por datos
Elige la asignación y el límite por transacción a partir de una suposición y suceden una de dos cosas: si es demasiado bajo, el agente alcanza el límite a mitad del día todos los días mientras depuras 'pago rechazado'; si es demasiado alto, el control es solo teatro. Dentro de la primera semana, observa el gasto diario real y establece la asignación en 2-3 veces eso - no 1x (demasiado ajustado) y no 100x (efectivamente ilimitado). Es un cambio en el panel, así que reajustar es barato.
Secreto de firma de webhook nunca rotado
Un incidente que filtra el secreto del webhook significa que un atacante puede falsificar webhooks que parecen eventos legítimos de payment.received, lo que puede engañar a tu manejador para entregar trabajo que nunca fue pagado. Rota el secreto (webhooks.rotateSecret) con la misma cadencia que las claves API (trimestralmente) o cada vez que sospeches de exposición, y siempre verifica las entregas con webhooks.verify contra el secreto actual.
Registros de auditoría que nadie lee
Un registro de auditoría solo captura cosas si alguien lo revisa. La mayoría de los equipos habilitan el registro, nunca lo miran y se enteran de los problemas a través de quejas de clientes. Programa una revisión semanal de 15 minutos: nuevos contrapartes, pagos rechazados, pagos fuera de horario. El costo es mínimo; el tiempo para detectar cae de semanas a días.
Sin simulacro en el libro de incidentes
Un runbook que nunca ha sido ejercitado es ficción. Escoge una fecha trimestral, simula un escenario de clave filtrada, mide cuánto tiempo toma revocar y contener. El primer simulacro siempre revela algo que falta (el ingeniero que sabe cómo rotar está de vacaciones, el runbook está detrás de un enlace de Notion caducado). Es mejor encontrar eso en un simulacro que a las 3am durante un incidente real.
Después del pase de seguridad.
La seguridad nunca está completa, pero el resto de la pila operativa se beneficia de una base limpia. Endurece los controles de gasto a medida que se acumulan los datos de uso real, refuerza el manejo de webhooks contra la carga y verifica la identidad del agente para que las contrapartes confíen en tu perfil público.
Configurar controles de gasto del agente que sobrevivan a la inyección de prompts
Los patrones de webhook sobre los que los desarrolladores preguntan más
Gana las insignias de verificación de GitHub y de dominio
Referencia completa en docs.blockchain0x.com. Glosario relacionado: Billetera Inteligente de Coinbase. Superficie de producto: Billeteras de Agente.