Sécurisez votre portefeuille d'agent avant de passer en direct.
Passer en production avec les paiements des agents n'est pas la même liste de contrôle qu'une intégration API normale. Ajoutez : un choix délibéré de type de portefeuille, une politique de dépenses ajustée (pas par défaut), une rotation des secrets API et webhook à une cadence définie, un examen hebdomadaire des journaux d'audit, et un manuel de réponse aux incidents qui a été testé au moins une fois. Sans cela, vous expédiez et apprenez à la dure.
Avant de commencer.
- Une intégration d'agent fonctionnelle de bout en bout en test - voir add-payments-to-agent et test-without-real-money.
- Contrôles de dépense configurés - voir contrôles de dépense (ce guide suppose qu'une politique est déjà en place).
- Un gestionnaire de secrets (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, etc) - les secrets dans les fichiers .env ne suffisent pas.
- Un ingénieur d'astreinte clairement identifié avec un accès administrateur au tableau de bord du portefeuille.
- 15 minutes de temps concentré. La liste de contrôle ci-dessous n'est pas aspirante - travaillez à travers elle ligne par ligne.
Exécutez la liste de contrôle avant le lancement.
Onze éléments. Chacun est une question oui/non avec un seul propriétaire. Si un élément n'est pas coché, ne mettez pas en ligne - travaillez d'abord cet élément jusqu'à sa clôture. Le coût d'un élément manqué en production est toujours plus élevé que le coût de sa finalisation maintenant.
# 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.Planifiez la rotation de la clé API et du secret du webhook.
Trimestriel est la cadence par défaut ; faites une rotation immédiatement sur l'un des éléments suivants : fuite suspectée, départ de l'ingénieur principal, incident de sécurité ailleurs dans l'entreprise. Le modèle de fenêtre à deux clés vous permet d'échanger des clés sans temps d'arrêt : créez la nouvelle clé, déployez-la partout, vérifiez, puis révoquez l'ancienne.
// 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)Les secrets de signature de webhook tournent de manière similaire via le tableau de bord - activez un deuxième secret, redéployez le gestionnaire pour accepter l'un ou l'autre, puis retirez l'ancien. Les deux à cadence trimestrielle avec des rappels de calendrier.
Configurez la révision hebdomadaire de l'audit.
Trois choses à examiner chaque semaine : nouveaux contreparties (tout ce qui n'a pas été vu auparavant mérite une vérification de santé de 30 secondes), paiements rejetés (la permission de dépense a fait son travail - l'agent s'est-il bloqué quelque part ?), et paiements en dehors des heures (un paiement à 3h du matin d'un agent qui fonctionne nominalement uniquement pendant les heures de bureau est le genre de signal qui détecte tôt les attaques par injection).
// 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})Rédigez (et entraînez-vous sur) le runbook d'incident.
Un runbook n'est aussi bon que la dernière fois qu'il a été testé. Ci-dessous se trouve le modèle - copiez-le dans le wiki de votre équipe, modifiez-le selon vos spécificités et planifiez un exercice de 30 minutes au cours du prochain trimestre. Chronométrez-le ; corrigez tout ce que l'exercice révèle comme manquant.
# 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.Cinq choses qui piègent les équipes lors de leur premier incident de production.
Traiter un nouvel agent comme 'juste comme l'ancien'
Chaque agent obtient son propre profil, ses propres clés, sa propre politique de dépense. Si vous réutilisez des clés entre agents 'parce qu'elles sont similaires', un compromis de clé unique affecte tous les agents en même temps. Créer un nouveau profil d'agent nécessite un appel API ; l'isolement par agent vaut la minute qu'il faut pour le faire correctement.
La permission de dépense est déterminée par estimation, pas par données
Choisissez l'allocation et le plafond par transaction à partir d'une estimation et deux choses peuvent se produire : trop bas et l'agent atteint la limite en milieu de journée chaque jour pendant que vous déboguez 'paiement rejeté' ; trop élevé et le contrôle est du théâtre. Au cours de la première semaine, regardez les dépenses quotidiennes réelles et fixez l'allocation à 2-3 fois cela - pas 1 fois (trop serré) et pas 100 fois (effectivement illimité). C'est un changement de tableau de bord, donc le réajustement est peu coûteux.
Le secret de signature du webhook n'a jamais été tourné
Un incident qui fuit le secret du webhook signifie qu'un attaquant peut falsifier des webhooks qui ressemblent à des événements payment.received légitimes, ce qui peut tromper votre gestionnaire en lui faisant livrer un travail qui n'a jamais été payé. Faites tourner le secret (webhooks.rotateSecret) avec la même cadence que les clés API (trimestriellement) ou chaque fois que vous soupçonnez une exposition, et vérifiez toujours les livraisons avec webhooks.verify par rapport au secret actuel.
Journaux d'audit que personne ne lit
Un journal d'audit ne capture les choses que si quelqu'un y jette un œil. La plupart des équipes activent le journal, ne le consultent jamais et découvrent des problèmes par le biais des plaintes des clients. Planifiez une revue hebdomadaire de 15 minutes : nouveaux partenaires, paiements rejetés, paiements hors heures. Le coût est minime ; le temps de détection passe de semaines à jours.
Pas d'exercice sur le manuel d'incidents
Un runbook qui n'a jamais été exercé est de la fiction. Choisissez une date trimestrielle, simulez un scénario de clé fuitée, chronométrez combien de temps il faut pour révoquer et contenir. Le premier exercice révèle toujours quelque chose qui manque (l'ingénieur qui sait comment faire la rotation est en vacances, le runbook est derrière un lien Notion expiré). Mieux vaut le découvrir lors d'un exercice que à 3h du matin lors d'un incident réel.
Après le passe de sécurité.
La sécurité n'est jamais terminée, mais le reste de la pile opérationnelle bénéficie d'une base propre. Renforcez les contrôles de dépenses à mesure que les données d'utilisation réelles s'accumulent, durcissez la gestion des webhooks contre la charge et vérifiez l'identité de l'agent afin que les contreparties fassent confiance à votre profil public.
Mettre en place des contrôles de dépenses d'agent qui survivent à l'injection d'invite
Les modèles de webhook dont les développeurs parlent le plus
Gagnez les badges de vérification GitHub et domaine
Référence complète à docs.blockchain0x.com. Glossaire associé : Coinbase Smart Wallet. Surface produit : Portefeuilles d'agent.