Canlıya geçmeden önce ajan cüzdanınızı güvence altına alın.
Ajan ödemeleri ile üretime geçmek, normal bir API entegrasyonu ile aynı kontrol listesi değildir. Ekleyin: kasıtlı bir cüzdan türü seçimi, ayarlanmış bir harcama politikası (varsayılanlar değil), belirtilen bir döngüde API ve webhook gizli anahtar döngüsü, haftalık denetim kaydı incelemesi ve en az bir kez tatbik edilmiş bir olay müdahale kılavuzu. Bunlar olmadan, gönderim yapar ve zor yoldan öğrenirsiniz.
Başlamadan önce.
- Testte uçtan uca çalışan bir ajan entegrasyonu - ajan-a-ödemeler-ekle ve gerçek-para-olmadan-test-et'e bakın.
- Harcamalar kontrolü yapılandırıldı - harcama kontrollerine bakın (bu kılavuz bir politikanın zaten mevcut olduğunu varsayıyor).
- Bir gizli yöneticisi (AWS Secrets Manager, GCP Secret Manager, Vault, 1Password, vb.) - .env dosyalarındaki gizli bilgiler yeterli değildir.
- Cüzdan kontrol paneline yönetici erişimi olan açıkça tanımlanmış bir çağrı mühendisi.
- 15 dakikalık odaklanmış zaman. Aşağıdaki kontrol listesi hedef değil - satır satır çalışın.
Ön lansman kontrol listesini çalıştırın.
On bir madde. Her biri tek bir sahibi olan evet/hayır sorusudur. Herhangi bir madde işaretlenmemişse, canlıya geçmeyin - önce o maddeyi tamamlayın. Üretimde kaçırılan bir maddenin maliyeti, onu şimdi bitirmenin maliyetinden her zaman daha büyüktür.
# 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.API anahtarı ve webhook gizli anahtarının döngüsünü planlayın.
Üç aylık döngü varsayılan ritimdir; herhangi birinde hemen döndürün: şüpheli sızıntı, baş mühendis ayrılması, şirkette başka bir yerde güvenlik olayı. İki anahtar pencere modeli, anahtarları sıfır kesinti ile değiştirmenizi sağlar: yeni anahtarı oluşturun, her yere dağıtın, doğrulayın ve ardından eski anahtarı iptal edin.
// 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)Webhook imzalama gizli anahtarları, kontrol paneli aracılığıyla benzer şekilde döner - ikinci bir gizli anahtarı etkinleştirir, her ikisini kabul etmek için işleyiciyi yeniden dağıtır ve ardından eski olanı emekliye ayırırsınız. Her ikisi de takvim hatırlatmaları ile üç aylık bir döngüde.
Haftalık denetim incelemesini ayarlayın.
Her hafta bakılması gereken üç şey: yeni karşı taraflar (daha önce görülmemiş her şey 30 saniyelik bir akıl kontrolü gerektirir), reddedilen ödemeler (harcama izni işini yaptı - ajans bir yere takıldı mı?), ve mesai dışı ödemeler (normalde yalnızca iş saatlerinde çalışan bir ajandan 3'te gelen bir ödeme, enjeksiyon saldırılarını erken yakalayan türden bir sinyaldir).
// 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})Olay çalışma kitabını yazın (ve tatbik edin).
Bir çalışma kitabı, ne kadar yakın zamanda test edildiği kadar iyidir. Aşağıda şablon var - bunu ekibinizin wikisinde kopyalayın, özel gereksinimlerinize göre düzenleyin ve bir sonraki çeyrekte 30 dakikalık bir tatbikat planlayın. Zamanlayın; tatbikatın ortaya çıkardığı eksiklikleri düzeltin.
# 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.Takımları ilk üretim olaylarında yakalayan beş şey.
Yeni bir ajanı 'eskiyle aynı' olarak değerlendirmek
Her ajan kendi profilini, kendi anahtarlarını ve kendi harcama politikasını alır. Eğer anahtarları 'benzer oldukları için' ajanslar arasında yeniden kullanırsanız, tek bir anahtarın ele geçirilmesi her ajanın birden patlamasına neden olur. Yeni bir ajan profili oluşturmak bir API çağrısı alır; her ajanın izolasyonu, bunu doğru bir şekilde yapmak için harcanan dakikaya değerdir.
Harcama izni tahmine göre ayarlandı, veriye göre değil
Bir tahminden harcama limitini ve işlem başına üst sınırı seçin ve iki şeyden biri olur: çok düşükse, ajan her gün öğle saatlerinde 'ödeme reddedildi' hatasını ayıklarken limitin sınırına ulaşır; çok yüksekse kontrol sadece gösteridir. İlk hafta içinde, gerçek günlük harcamaya bakın ve harcama limitini bunun 2-3 katı olarak ayarlayın - 1 kat (çok sıkı) değil ve 100 kat (etkili olarak sınırsız) değil. Bu bir kontrol paneli değişikliği olduğundan, ayarlamak ucuzdur.
Webhook imza gizliliği asla değiştirilmedi
Webhook sırrını sızdıran bir olay, bir saldırganın meşru payment.received olaylarına benzeyen webhooks oluşturabileceği anlamına gelir; bu, işleyicinizi asla ödenmemiş bir işi teslim etmeye kandırabilir. Sırrı döndürün (webhooks.rotateSecret) API anahtarlarıyla aynı sıklıkta (üç aylık) veya herhangi bir zaman şüpheleniyorsanız, ve her zaman teslimatları mevcut sır ile webhooks.verify ile doğrulayın.
Kimsenin okumadığı denetim günlükleri
Bir denetim kaydı, yalnızca birisi ona bakarsa bir şeyleri yakalar. Çoğu ekip kaydı etkinleştirir, asla bakmaz ve müşteri şikayetlerinden sorunları öğrenir. Haftalık 15 dakikalık bir inceleme planlayın: yeni karşı taraflar, reddedilen ödemeler, mesai dışı ödemeler. Maliyet küçüktür; tespit süresi haftalardan günlere düşer.
Olay çalışma kitabında tatbikat yok
Hiç uygulanmamış bir çalışma kitabı kurgudur. Çeyrek bir tarih seçin, sızdırılmış anahtar senaryosunu simüle edin, iptal ve kontrol etmenin ne kadar sürdüğünü zamanlayın. İlk tatbikat her zaman bir şeyin eksik olduğunu ortaya çıkarır (döndürmeyi bilen mühendis tatilde, çalışma kitabı süresi dolmuş bir Notion bağlantısının arkasında). Bunu bir tatbikatta bulmak, gerçek bir olay sırasında 3'te bulmaktan daha iyidir.
Güvenlik geçişinden sonra.
Güvenlik asla tamamlanmaz, ancak operasyonel yığının geri kalanı temiz bir temel üzerinden fayda sağlar. Gerçek kullanım verileri birikdikçe harcama kontrollerini sıkılaştırın, yük karşısında webhook işlemlerini güçlendirin ve karşı tarafların kamu profilinize güvenmesi için ajan kimliğini doğrulayın.
İstem enjeksiyonuna dayanacak şekilde ajanın harcama kontrollerini ayarlayın
Geliştiricilerin en çok sorduğu webhook desenleri
GitHub ve alan adı doğrulama rozetlerini kazanın
Tam referans docs.blockchain0x.com'da. İlgili sözlük: Coinbase Akıllı Cüzdan. Ürün yüzeyi: Ajan cüzdanları.