SAYLOR The result you are building
Finished result: An externally enforced wallet policy with dedicated low-balance accounts, allowlisted networks/assets/origins/destinations, per-call and rolling caps, simulation/decoding, approval thresholds, reconciliation, rotation, and emergency pause.
Use this guide when
- An agent may purchase APIs or initiate blockchain payments.
- You need to bound x402 or tool-driven spending before autonomy.
Do not use it as a substitute for
- Do not place seed phrases/private keys in prompts, frontend code, repositories, or ordinary logs.
- Do not rely on natural-language budget instructions as the only spending control.
Before you change anything
- Wallet architecture and signer/custody mechanism.
- Allowed networks, assets, recipients/vendors, and purposes.
- Per-call/day/month caps plus approval thresholds.
- Transaction simulation/decoding, receipts, and emergency controls.
Understand the system before fixing it
Ability to sign is not permission to pay. Policy engine must authorize exact decoded transaction independently of agent text.
Caps need aggregation. Attackers or loops can split payments below per-call threshold; enforce rolling and destination/task totals.
Simulation is evidence, not guarantee. State can change before landing; still verify confirmed transaction and reconcile balances.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Unknown destination/origin | Trust | Resolve service identity and allowlist | Reject until independently approved. |
| Amount under per-call but total high | Limit splitting | Aggregate by task/vendor/window | Block rolling cap and require approval. |
| Simulation differs from intent | Transaction composition | Decode programs/accounts/amounts/approvals | Reject unknown instructions or mutable recipient. |
| Receipt absent after timeout | Ambiguous payment | Reconcile signature/idempotency/provider | Do not sign a replacement automatically. |
Step-by-step procedure
01 Segregate wallet and signer
Why: Blast radius follows balance and key reach. Do: Use dedicated low-balance buyer wallet; keep receiving, treasury, and operating wallets separate; store keys in supported custody/secret boundary. Read the result: Agent never receives raw key material. Next: Fund only bounded operating amount.
02 Express hard policy
Why: Human prose cannot reliably constrain execution. Do: Allowlist chain IDs, asset contracts/mints, recipients/vendors/origins, program IDs, methods/purposes; set max per call/task/vendor/day/month and fee/slippage limits. Read the result: Default deny unknown values and cap splitting via aggregate counters. Next: Version policy and owner.
03 Decode and simulate
Why: A displayed label can hide approvals, delegates, extra instructions, or wrong network. Do: Decode transaction/message and compare every instruction/account/amount to intent/policy; simulate at current state. Read the result: Unknown program, transfer, approval, delegate, recipient, or excessive fee blocks signing. Next: Bind approval to transaction hash/details and expiry.
04 Require exact approval
Why: High-impact exceptions need informed consent. Do: Show network, asset, amount/max, fiat estimate, recipient/vendor, purpose, fees, reversibility, and decoded instructions; approval token binds all fields. Read the result: Any rebuilt/changed transaction invalidates approval. Next: Never approve generic future spending.
05 Sign, confirm, reconcile
Why: Submission is not settlement. Do: Record intent/idempotency, signature, confirmation, receipt, balances, and service fulfillment. Reconcile ambiguity before retry. Read the result: One intent maps to one payment and one fulfillment. Next: Alert policy and balance deviations.
06 Test pause and recovery
Why: A control not tested will fail during incident. Do: Trigger caps, unknown network/destination, split attempts, malicious transaction, timeout/duplicate, key rotation, and emergency pause. Read the result: Signer refuses without model discretion and pause stops new signing immediately. Next: Document refund/support and incident owner.
Worked example
Starting problem: Agent buys $0.50 API calls but loops 200 times in one hour.
Evidence collected
- Every call is below $1 per-call cap.
- No rolling task/vendor cap exists.
- Wallet holds $500.
- Service responses are duplicates caused by retry bug.
Decision: Per-call control is ineffective against loops and splitting; wallet balance creates unnecessary blast radius.
Actions taken
- Reduced wallet balance and added task/vendor/hour/day caps.
- Added idempotency and duplicate-result reuse.
- Required approval above cumulative threshold and tested emergency pause.
Proof of completion: Loop stops at aggregate limit; duplicates do not repay; pause blocks signer; reconciliation matches calls, payments, receipts, and balance.
Why this example matters: Budget must be enforced across the logical job and time window.
Verify, recover, and hand off
Completion tests
- Unknown networks/assets/origins/recipients/programs are denied.
- Per-call and aggregate caps cannot be bypassed by splitting.
- Decoded transaction exactly matches approved intent.
- Signature/confirmation/receipt/fulfillment reconcile.
- Key is never model-visible or logged.
- Pause/rotation and low-balance recovery are tested.
Rollback or safe recovery
- Emergency-pause signer and revoke agent access.
- Move remaining funds using trusted manual recovery workflow if key is suspected compromised.
- Restore prior policy version only after outstanding payments reconcile.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Legitimate payment blocked | Allowlist/policy lacks exact vendor/network/asset | Add narrow reviewed entry; do not wildcard. |
| Fiat cap differs | Price oracle/staleness policy unclear | Use bounded max and observed price source/time. |
| Approval replay works | Token not bound to transaction/user/expiry | Cryptographically bind and mark one-time. |
| Balance mismatch | Fees, pending tx, duplicate, or unknown transfer | Pause and reconcile every signature before resuming. |
Reusable handoff record
- Wallet/signer architecture and maximum exposed balance.
- Versioned allowlist/caps/approval policy.
- Decode/simulation/confirmation evidence.
- Payment-service reconciliation and audit record.
- Pause, key rotation, incident, and recovery procedure.
For agents
This guide also defines a structured diagnose/propose/execute contract for building an agent-facing tool around this workflow (a design reference, not a live endpoint on this site today):
Required inputs: context, evidence, constraints, success. Returned output: diagnosis, plan, verification, handoff.
Refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: score confidence from the number and quality of independent observations, not from how familiar the error looks.
References
- https://docs.x402.org/core-concepts/wallet
- https://docs.x402.org/getting-started/quickstart-for-buyers
- https://owasp.org/www-project-top-10-for-large-language-model-applications/