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. The sandbox uses Anvil — a local fork of the Base mainnet — so the IDRX and Permit2 contracts used are exactly the same as production, but all transactions are free.

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, you need to fund a wallet with test IDRX. There are two ways:

Via API

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

Response:

{
  "txHash": "0x...",
  "address": "0xYourWalletAddress...",
  "amount": "1000000",
  "token": "IDRX",
  "balance": "1000000"
}

Via Dashboard

Go to the Sandbox page in the dashboard, enter the wallet address and the amount of IDRX you want to fund, then click the Fund button.

3. Use Built-in Test Wallets

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

curl https://sandbox.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 via the /sandbox/fund endpoint
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

const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',
});
 
// This will route to sandbox.transx402.com automatically
const response = await client.fetch('https://mysite.com/api/premium-content');

Testing with cURL

# 1. Check health
curl https://sandbox.transx402.com/health
 
# 2. View supported tokens
curl https://sandbox.transx402.com/tokens
 
# 3. Fund test wallet
curl -X POST https://sandbox.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://sandbox.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://sandbox.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
const client = TransX402.create({
  apiKey: 'ipk_sandbox_abc123...',  // ipk_sandbox_ prefix
});
 
// Production (same code, just swap the key)
const client = TransX402.create({
  apiKey: 'ipk_live_xyz789...',     // ipk_live_ prefix
});

The library automatically detects the environment from the API key prefix and routes to the correct facilitator URL.

Local Development with Anvil

For local development, you can run your own Anvil instance using Docker Compose:

docker compose up

This will start:

• TransX402 API at http://localhost:3402
• PostgreSQL at localhost:5432
• Redis at localhost:6379
• Anvil (Base fork) at http://localhost:8545

Why Anvil Fork?

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.