Sandbox

Complete guide to testing in the TransX402 sandbox environment — fund wallets, make test payments, and validate your integration.

What is the Sandbox?

The sandbox is a testing environment that lets you test your TransX402 integration without using real money. By default it targets CAMP Testnet — a public testnet chain (https://testnet-rpc.onchainfolio.com/rpc) with test IDRX and Permit2. The facilitator sponsors settle gas; merchants fund wallets with test IDRX and ETH via the treasury faucet (/sandbox/fund).

Optional: run a local Anvil Base fork with SANDBOX_FUNDING_MODE=anvil and docker compose --profile anvil up (developer tooling only — not the default).

Sandbox vs Production

Getting Started

1. Get a Sandbox API Key

When you register at dashboard.transx402.com, a sandbox API key is automatically created. You can also create additional sandbox keys on the API Keys page:

ipk_sandbox_abc123def456...

2. Fund a Test Wallet

Before making test payments, fund a wallet with test IDRX (and optionally ETH for gas on browser Path 4). There are two ways:

Via API

IDRX:

curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress...",
    "amount": "1000000"
  }'

ETH (optional token — omit for IDRX):

curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress...",
    "amount": "0.01",
    "token": "ETH"
  }'

Response:

{
  "txHash": "0x...",
  "address": "0xYourWalletAddress...",
  "amount": "0.01",
  "token": "ETH",
  "balance": "10000000000000000"
}

Via Dashboard

Go to the Sandbox page in the dashboard. Use the Fund IDRX and Fund ETH cards (amounts go to your registered merchant wallet), then click the fund button on each card.

On CAMP Testnet (treasury funding), the faucet can transfer both test IDRX and native ETH. The first browser payment may prompt a MetaMask Spending Cap (approve Permit2); later payments are signature-only.

3. Use Built-in Test Wallets

The sandbox provides pre-funded test wallets. Get the wallet list:

curl https://api.transx402.com/sandbox/wallets \
  -H "X-API-Key: ipk_sandbox_abc123..."

Response:

{
  "wallets": [
    {
      "address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
      "ethBalance": "10000.0",
      "idrxBalance": "10000000000",
      "privateKey": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
    }
  ]
}

These are Anvil's deterministic accounts with 10,000 ETH and plenty of test IDRX. The private keys are safe to use in sandbox since they only work on the Anvil chain.

Testing Payments

Basic Testing Flow

1. Install integration — Use a sandbox API key in the JS library or WordPress plugin
2. Fund wallet — Fill a test wallet with IDRX (and ETH if needed) via /sandbox/fund or the Dashboard Sandbox page
3. Access content — Open a paywalled page
4. Pay — Click "Pay with IDRX", connect wallet, and sign
5. Verify — Check the payment in the dashboard or via the /payments API

Testing with the JS Library

import { createBrowserClient } from '@transx402/client/browser';
 
// Pick exactly one: environment OR facilitatorUrl. Chain params come from GET /config.
const client = createBrowserClient({
  apiKey: 'ipk_sandbox_abc123...',
  environment: 'camp', // 'local' | 'camp' | 'base'
});
 
const response = await client.fetch('https://mysite.com/api/premium-content');

camp and base use the same hosted facilitator; your API key selects sandbox vs production chain config from GET /config.

Browser wallets use Path 4: one-time on-chain Permit2 approve (user pays gas), then signature-only payments. Agents use Path 3 (createAgentClient) with sponsored approve via signTransaction.

CDN / WordPress can still use TransX402.create({ apiKey, environment }) from the browser bundle.

Testing with cURL

# 1. Check health
curl https://api.transx402.com/health
 
# 2. View supported tokens
curl https://api.transx402.com/tokens
 
# 3. Fund test wallet
curl -X POST https://api.transx402.com/sandbox/fund \
  -H "X-API-Key: ipk_sandbox_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"address": "0xTestWallet", "amount": "500000"}'
 
# 4. Check payments
curl https://api.transx402.com/payments \
  -H "X-API-Key: ipk_sandbox_abc123..."

Resetting the Sandbox

If you need to start fresh (e.g., after intensive testing), you can reset the sandbox state:

curl -X POST https://api.transx402.com/sandbox/reset \
  -H "X-API-Key: ipk_sandbox_abc123..."

This will re-fork the Anvil chain from the latest Base mainnet block. All previous sandbox transactions will be lost, but the IDRX and Permit2 contracts remain available.

Differences from Production

Your integration code is exactly the same for sandbox and production. The only difference:

// Sandbox / CAMP
const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
  environment: 'camp', // 'local' | 'camp' | 'base'
});
 
// Production
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',
  environment: 'base',
});

Pick environment or facilitatorUrl (never both). Chain params come only from GET /config.

Local Development with Anvil (optional)

Anvil is not the default sandbox. Use it only when you want an offline Base fork:

# In .env:
# SANDBOX_FUNDING_MODE=anvil
# SANDBOX_RPC_URL=http://host.docker.internal:8546   # or host-mapped Anvil
 
docker compose --profile anvil up -d

Anvil listens on port 8546 locally. /sandbox/wallets and /sandbox/reset work only in Anvil mode.

Why Anvil Fork (optional)?

Testing Tips

1. Always test in sandbox first before switching to production
2. Use webhooks to verify payment notifications are sent correctly
3. Test error scenarios — try paying with insufficient balance, expired deadline, etc.
4. Check the dashboard — make sure payments appear on the Payments page
5. Test across wallets — MetaMask, Coinbase Wallet, etc.