Metti in sicurezza il tuo portafoglio agente prima di andare in diretta.
Andare in produzione con i pagamenti degli agenti non è la stessa lista di controllo di una normale integrazione API. Aggiungi: una scelta deliberata del tipo di portafoglio, una politica di spesa tarata (non predefinita), rotazione dei segreti API e webhook su una cadenza stabilita, una revisione settimanale del registro di audit e un runbook di risposta agli incidenti che è stato esercitato almeno una volta. Senza questi, spedisci e impari a tue spese.
Prima di iniziare.
- Un'integrazione agente funzionante end-to-end in test - vedi add-payments-to-agent e test-without-real-money.
- Controlli di spesa configurati - vedi controlli di spesa (questa guida presume che una politica sia già in atto).
- Un gestore di segreti (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, ecc.) - i segreti nei file .env non sono sufficienti.
- Un ingegnere di guardia chiaramente identificato con accesso amministrativo al dashboard del wallet.
- 15 minuti di tempo concentrato. La checklist qui sotto non è aspirazionale - lavoraci riga per riga.
Esegui la checklist pre-lancio.
Undici elementi. Ognuno è una domanda sì/no con un unico proprietario. Se un elemento non è selezionato, non andare live - lavora su quell'elemento fino alla chiusura prima. Il costo di un elemento mancante in produzione è sempre maggiore del costo di completarlo ora.
# 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.Pianifica la rotazione della chiave API e del segreto del webhook.
Trimestrale è la cadenza predefinita; ruota immediatamente in caso di: sospetto di fuga, partenza del lead engineer, incidente di sicurezza altrove nell'azienda. Il modello a due chiavi consente di scambiare le chiavi senza tempi di inattività: crea la nuova chiave, distribuiscila ovunque, verifica, quindi revoca la vecchia.
// 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)I segreti di firma webhook ruotano in modo simile attraverso il dashboard - abilita un secondo segreto, ridistribuisci il gestore per accettare entrambi, quindi ritira il vecchio. Entrambi con cadenza trimestrale e promemoria nel calendario.
Imposta la revisione settimanale dell'audit.
Tre cose da controllare ogni settimana: nuove controparti (qualunque cosa non vista prima merita un controllo di sanità di 30 secondi), pagamenti rifiutati (l'autorizzazione alla spesa ha fatto il suo lavoro - l'agente si è bloccato da qualche parte?), e pagamenti fuori orario (un pagamento alle 3 del mattino da un agente che nominalmente funziona solo durante l'orario lavorativo è il tipo di segnale che cattura gli attacchi di iniezione 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})Scrivi (e esercitati) il runbook per gli incidenti.
Un runbook è valido solo quanto recentemente è stato testato. Qui sotto c'è il modello - copialo nel wiki del tuo team, modifica per le tue specifiche e pianifica un'esercitazione di 30 minuti nel prossimo trimestre. Cronometralo; correggi qualsiasi cosa l'esercitazione riveli come mancante.
# 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.Cinque cose che colgono i team nel loro primo incidente di produzione.
Trattare un nuovo agente come 'proprio come il vecchio'
Ogni agente ottiene il proprio profilo, le proprie chiavi, la propria politica di spesa. Se riutilizzi le chiavi tra gli agenti 'perché sono simili', una singola compromissione della chiave colpisce ogni agente contemporaneamente. Creare un nuovo profilo agente richiede una chiamata API; l'isolamento per agente vale il minuto che costa farlo correttamente.
Permesso di spesa dimensionato per stima, non per dati
Scegli l'indennità e il limite per transazione da un'ipotesi e due cose possono succedere: troppo basso e l'agente raggiunge il limite a metà giornata ogni giorno mentre debugghi 'pagamento rifiutato'; troppo alto e il controllo è solo teatro. Entro la prima settimana, guarda la spesa giornaliera effettiva e imposta l'indennità a 2-3 volte quella - non 1x (troppo stretto) e non 100x (effettivamente illimitato). È una modifica del dashboard, quindi il riaggiustamento è economico.
Il segreto di firma del webhook non è mai stato ruotato
Un incidente che rivela il segreto del webhook significa che un attaccante può falsificare webhook che sembrano eventi payment.received legittimi, il che può ingannare il tuo gestore nel consegnare lavoro per cui non è mai stato pagato. Ruota il segreto (webhooks.rotateSecret) con la stessa cadenza delle chiavi API (trimestrale) o ogni volta che sospetti un'esposizione, e verifica sempre le consegne con webhooks.verify rispetto al segreto attuale.
Registri di audit che nessuno legge
Un registro di audit cattura solo le cose se qualcuno lo guarda. La maggior parte dei team abilita il registro, non lo guarda mai e scopre i problemi dalle lamentele dei clienti. Pianifica una revisione settimanale di 15 minuti: nuovi controparte, pagamenti rifiutati, pagamenti fuori orario. Il costo è minimo; il tempo per rilevare scende da settimane a giorni.
Nessun drill sul runbook dell'incidente
Un runbook che non è mai stato esercitato è fiction. Scegli una data trimestrale, simula uno scenario di chiave trapelata, misura quanto tempo ci vuole per revocare e contenere. Il primo esercizio rivela sempre qualcosa che manca (l'ingegnere che sa come ruotare è in vacanza, il runbook è dietro un link Notion scaduto). Meglio scoprirlo in un esercizio che alle 3 del mattino durante un vero incidente.
Dopo il pass di sicurezza.
La sicurezza non è mai completata, ma il resto dello stack operativo beneficia di una base pulita. Inasprisci i controlli di spesa man mano che i dati di utilizzo effettivi si accumulano, indurisci la gestione dei webhook contro il carico e verifica l'identità dell'agente affinché le controparti si fidino del tuo profilo pubblico.
Imposta controlli di spesa per l'agente che sopravvivono all'iniezione di prompt
I modelli di webhook di cui i programmatori chiedono di più
Guadagna i badge di verifica di GitHub e del dominio
Riferimento completo su docs.blockchain0x.com. Glossario correlato: Coinbase Smart Wallet. Superficie di prodotto: Portafogli degli agenti.