Testing Payments Safely
Before going to production, you need confidence that your agent integration handles every scenario safely. This guide covers the testing environments (agent sandbox and Tempo Testnet), counterparty and time-window scenarios, and the migration to production. For policy semantics and the amount-threshold trio (APPROVED / REQUIRES_APPROVAL / DENIED), run the three-tier threshold test in Testing Spending Policies.Prerequisites
An agent with an SDK key (Quickstart), or an agent sandbox (below)
For testnet scenarios: a funded Tempo Testnet wallet linked to your agent
Choose Your Environment
Fastest Lane: Agent Sandbox
The quickest way to test the payment lifecycle is the agent sandbox:POST /api/agents/sandbox creates a test workspace, agent, wallet, and SDK keys in one call, with no email verification or human approval. Sandbox test payments exercise policy evaluation, spend tracking, receipts, and audit logs without an onchain transfer, so you don’t need a signer or a funded wallet.
See the Agent Sandbox Quickstart for the full flow, including claiming the sandbox later.
Tempo Testnet
When you want real onchain transactions, use Tempo Testnet:
Tempo Testnet gives you real onchain transactions with real policy enforcement, using free test
tokens. Your core request code can stay the same when you switch to production, but production
credentials, custody, policies, approvals, webhooks, monitoring, and incident controls must be
configured separately. The Quickstart covers creating and funding a testnet
wallet; use the Production Readiness Checklist before enabling live
funds.
Test Plan
This guide walks through two scenarios beyond the amount thresholds:
For amount-based outcomes: a
REQUIRES_APPROVAL payment appears in Pending Approvals in the dashboard, where a human can approve or reject it; after approval, the agent can execute it (poll for the status change, or use webhooks to get notified). For handling DENIED and REQUIRES_APPROVAL statuses in code, see Error Handling.
Scenario 1: Blocked Counterparty
First create and assign the policy:1
Create the policy
Go to Policies → Create Policy.
2
Add rule
3
Assign it to your agent
Add it in the Permissions tab.
- Response
statusis"DENIED" reasonsexplains that the current payment controls do not allow the recipient- Amount doesn’t matter. The address itself is blocked
Scenario 2: Time Window Restriction
To test time-based restrictions, temporarily add a time window policy:1
Create a time window policy
2
Assign it to your agent
Add it in the Permissions tab.
3
Test outside the window
If it’s currently outside 9am-5pm in your timezone, any payment request will be denied with a
customer-facing schedule reason.If it’s during business hours, you can temporarily set the window to a past range (e.g., 02:00-03:00) to trigger the denial.
4
Clean up
Remove the time window policy after testing to avoid blocking your other tests.
Policy-rule time windows use the server’s local time. If you need to test a specific IANA
timezone, configure a wallet-level time window instead.
Checking Results in Bulk
After running your scenarios, review everything in one place:Transactions Page
Go to Transactions in the dashboard. You should see:- Confirmed transactions from approved-and-executed payments
- Denied/rejected entries from the blocked-counterparty and time-window scenarios
- A pending-approval entry for any payment that required approval
Audit Logs
Go to Audit Logs to see the policy evaluation trail for every request. Each entry shows:- Which policies were evaluated
- Which rules matched
- The final decision and reasoning
Via API
Testing x402 Micropayments
If your agent uses x402 protocol payments (paying for APIs), test the pre-authorize → record flow the same way. The request and response shapes are documented in the x402 SDK reference; the x402 guide covers the end-to-end flow.Moving to Production
Once your scenarios pass:- Create a production wallet on Base (USDC) or Solana (USDC)
- Fund it with real stablecoins
- Link it to your agent with production-appropriate limits
- Adjust policies for production thresholds (the test policies can remain as-is)
- Your integration code stays the same, no code changes needed
You can keep your testnet wallet and policies active alongside production. Many teams run test
agents permanently for regression testing.
Troubleshooting
For unexpected policy outcomes (DENIED when you expected REQUIRES_APPROVAL, the wrong policy triggering, org policies overriding agent policies), see the policy troubleshooting accordions.All scenarios return APPROVED (policies not enforcing)
All scenarios return APPROVED (policies not enforcing)
Check the Permissions tab on the agent detail page. Policies must be explicitly assigned to
the agent. Creating a policy doesn’t automatically apply it.
Time window tests pass when they shouldn't
Time window tests pass when they shouldn't
Double-check the timezone setting on the policy. If your local timezone doesn’t match the policy
timezone, the enforcement window may be offset.
Execute returns INSUFFICIENT_BALANCE after approval
Execute returns INSUFFICIENT_BALANCE after approval
The wallet balance was sufficient at request time but dropped before execution. This can happen
if other transactions executed between request and execute. Re-fund the testnet wallet.
Next Steps
Secure Your Agent
Production-ready policy configurations
Recipes
Copy-paste solutions for specific tasks
Error Handling
Handle every error code gracefully
Policy Reference
All policy types and rule operators