라이브로 전환하기 전에 에이전트 지갑을 안전하게 보호하세요.
에이전트 결제로 프로덕션에 가는 것은 일반 API 통합과 동일한 체크리스트가 아닙니다. 추가: 의도적인 지갑 유형 선택, 조정된 지출 정책(기본값이 아님), 명시된 주기로 API 및 웹훅 비밀 회전, 주간 감사 로그 검토, 최소 한 번 훈련된 사고 대응 매뉴얼. 이러한 것들이 없으면, 귀하는 배포하고 힘든 방법으로 배웁니다.
시작하기 전에.
- 테스트에서 엔드 투 엔드로 작동하는 에이전트 통합 - 에이전트에 결제 추가 및 실제 돈 없이 테스트를 참조하십시오.
- 지출 제어가 구성되었습니다 - 지출 제어를 참조하십시오 (이 가이드는 정책이 이미 마련되어 있다고 가정합니다).
- 비밀 관리자(AWS Secrets Manager, GCP Secret Manager, Vault, 1Password 등) - .env 파일의 비밀만으로는 충분하지 않습니다.
- 지갑 대시보드에 관리자 액세스 권한이 있는 명확히 식별된 대기 엔지니어.
- 15분의 집중 시간. 아래 체크리스트는 목표가 아니므로 한 줄씩 진행하세요.
사전 출시 체크리스트를 실행하세요.
열한 개의 항목. 각 항목은 단일 소유자가 있는 예/아니오 질문입니다. 어떤 항목이 체크되지 않았다면, 라이브로 진행하지 마세요 - 먼저 그 항목을 마무리하세요. 프로덕션에서 놓친 항목의 비용은 항상 지금 완료하는 비용보다 큽니다.
# 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 키 및 웹후크 비밀 회전을 예약하세요.
분기별이 기본 주기입니다; 의심되는 유출, 주요 엔지니어 이탈, 회사 내 다른 보안 사고가 발생하면 즉시 회전합니다. 두 키 창 패턴을 사용하면 다운타임 없이 키를 교체할 수 있습니다: 새 키를 생성하고, 모든 곳에 배포하고, 검증한 후, 이전 키를 취소합니다.
// 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)웹훅 서명 비밀은 대시보드를 통해 유사하게 회전합니다. 두 번째 비밀을 활성화하고, 둘 다 수용할 수 있도록 핸들러를 재배포한 후, 이전 것을 폐기합니다. 두 가지 모두 분기별 주기로 일정 알림과 함께 진행됩니다.
주간 감사 검토를 설정하세요.
매주 살펴봐야 할 세 가지: 새로운 거래처(이전에 보지 못한 것은 30초의 정상성 검사를 받을 가치가 있음), 거부된 결제(지출 권한이 제대로 작동했는지 - 에이전트가 어딘가에 갇혔는지?), 그리고 비업무 시간 결제(정상적으로 업무 시간에만 작동하는 에이전트로부터 오전 3시에 이루어진 결제는 조기 주입 공격을 포착하는 신호입니다).
// 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})사고 런북을 작성하고 연습하세요.
런북은 얼마나 최근에 테스트되었는지에 따라 그 품질이 결정됩니다. 아래는 템플릿입니다 - 팀의 위키에 복사하고, 세부 사항에 맞게 편집하고, 다음 분기에 30분 훈련을 계획하세요. 시간을 측정하고, 훈련에서 드러나는 부족한 부분을 수정하세요.
# 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.팀이 첫 번째 운영 사고에서 걸리게 되는 다섯 가지 사항.
새 에이전트를 '이전과 똑같이' 취급하기
모든 에이전트는 고유한 프로필, 고유한 키 및 고유한 지출 정책을 가집니다. '비슷하기 때문에' 에이전트 간에 키를 재사용하면 단일 키가 손상되어 모든 에이전트가 동시에 영향을 받습니다. 새로운 에이전트 프로필을 생성하는 데는 하나의 API 호출이 필요하며, 에이전트별 격리는 이를 올바르게 수행하는 데 드는 시간의 가치가 있습니다.
데이터가 아닌 추측에 의해 크기가 결정된 지출 권한
허용량과 거래당 한도를 추측하여 설정하면 두 가지 중 하나가 발생합니다: 너무 낮으면 에이전트가 매일 중간에 한도에 도달하여 '결제 거부'를 디버깅하게 되고; 너무 높으면 제어가 허상입니다. 첫 주 내에 실제 일일 지출을 살펴보고 허용량을 2-3배로 설정하세요 - 1배(너무 타이트)도 아니고 100배(사실상 무제한)도 아닙니다. 이는 대시보드 변경이므로 재조정은 저렴합니다.
웹후크 서명 비밀이 한 번도 변경되지 않음
웹후크 비밀이 유출되는 사건은 공격자가 합법적인 payment.received 이벤트처럼 보이는 웹후크를 위조할 수 있음을 의미하며, 이는 핸들러가 결제되지 않은 작업을 전달하도록 속일 수 있습니다. 비밀을 회전시키십시오 (webhooks.rotateSecret) API 키와 같은 주기로 (분기별) 또는 노출이 의심될 때마다, 항상 현재 비밀에 대해 webhooks.verify로 배달을 확인하십시오.
아무도 읽지 않는 감사 로그
감사 로그는 누군가가 확인해야만 내용을 포착합니다. 대부분의 팀은 로그를 활성화하지만, 이를 확인하지 않고 고객 불만을 통해 문제를 발견합니다. 매주 15분 검토를 예약하십시오: 새로운 거래처, 거부된 결제, 비업무 시간 결제. 비용은 적고, 문제 탐지 시간은 몇 주에서 며칠로 단축됩니다.
사고 실행 매뉴얼에 대한 훈련 없음
한 번도 실행되지 않은 실행 계획은 허구입니다. 분기 날짜를 선택하고, 키 유출 시나리오를 시뮬레이션하고, 철회하고 차단하는 데 걸리는 시간을 측정합니다. 첫 번째 훈련은 항상 누락된 무언가를 드러냅니다(회전 방법을 아는 엔지니어가 휴가 중이거나, 실행 계획이 만료된 Notion 링크 뒤에 있습니다). 실제 사건 중 3시에 발견하는 것보다 훈련 중에 발견하는 것이 더 낫습니다.
보안 패스가 발급된 후.
보안은 결코 끝나지 않지만, 나머지 운영 스택은 깨끗한 기준선의 혜택을 받습니다. 실제 사용 데이터가 축적됨에 따라 지출 제어를 강화하고, 부하에 대한 웹후크 처리를 강화하며, 거래 상대방이 귀하의 공개 프로필을 신뢰할 수 있도록 에이전트 정체성을 확인하세요.
전체 참조는 docs.blockchain0x.com에 있습니다. 관련 용어집: Coinbase 스마트 지갑. 제품 표면: 에이전트 지갑.