Skip to content
tx402

Base Sepolia runbook

The Base adapter’s automated suite is fully deterministic and needs no wallet: it runs against a local JSON-RPC stub (tools/evm-rpc-stub) and the local test merchant. This runbook is for the opt-in live test, which is required before release.

1. Create a dedicated wallet

Section titled “1. Create a dedicated wallet”

The rule is specific: “dedicated low-balance wallets funded only for automated Base Sepolia and Solana Devnet tests”. Do not reuse a wallet that holds anything you would mind losing, and do not reuse one that has ever touched mainnet — a testnet key that leaks is only harmless if it controls nothing else.

Terminal window
# Any tool that produces a secp256k1 key works. This one uses viem, which the workspace
# already has — run it through pnpm so it resolves from the package that depends on it.
pnpm --filter tx402 exec node -e "const {generatePrivateKey,privateKeyToAccount}=require('viem/accounts');
const k=generatePrivateKey();console.log('key    ', k);console.log('address', privateKeyToAccount(k).address)"

Run it from the repository root, like every other command on this page. viem is an optional peer dependency of tx402 rather than a workspace-root dependency, so a bare node -e from the root cannot resolve it — pnpm --filter is what runs the command inside the package that has it.

Store the key in a password manager or a secret manager. Never commit it, never pass it as a command-line flag — the CLI forbids it outright — and never paste it into an issue.

2. Fund it

Section titled “2. Fund it”

Two balances are needed, both small:

What Why Suggested
Sepolia ETH Not spent by tx402 — the buyer never broadcasts a transaction — but useful for any manual on-chain check 0.01 ETH
Base Sepolia USDC The asset the exact scheme authorizes 5 USDC

The USDC contract the SDK will use is the one in the signed manifest — 0x036CbD53842c5426634e7929541eC2318f3dCF7e — not whatever a faucet page happens to name. If a faucet sends a different token the balance read will simply report zero.

3. Run the live suite

Section titled “3. Run the live suite”
Terminal window
TX402_BASE_SEPOLIA_PRIVATE_KEY=0x… pnpm --filter tx402 exec vitest run test/base-sepolia.live.test.ts

Without the environment variable the file is skipped, which is why ordinary CI stays green with no wallet configured.

What it exercises for real: chain identity against the manifest’s published Base Sepolia RPC endpoints, a USDC balance read for your address, the full policy → reserve → sign path, and a real EIP-712 signature from your key. The merchant half is played by the local test merchant, which validates the authorization it receives.

What this test file does not exercise: settlement. /verify and /settle belong to the merchant, so the buyer SDK has no settlement path of its own to test, and this suite runs the merchant without a facilitator.

That is a property of this suite, not a limit of the test merchant. Given --facilitator, the same local merchant settles for real against a public x402 facilitator, and real testnet USDC moves — that is exactly what the quickstart does, and what tools/ttv measures the five-minute target against. A local merchant does not make the money fake; settlement does, and with a facilitator this one settles.

To close the loop against someone else’s merchant instead, point the same client at a real one:

Terminal window
TX402_BASE_SEPOLIA_PRIVATE_KEY=0x… \
TX402_LIVE_MERCHANT_URL=https://some-merchant.example/paid-resource \
  pnpm --filter tx402 exec vitest run test/base-sepolia.live.test.ts

4. Before release

Section titled “4. Before release”

The public testnet smoke suite must pass twice from clean environments, and T-019 asks for 50 Base Sepolia and 50 Solana Devnet calls with zero SDK-caused failures. Both need this wallet funded, so keep it topped up rather than draining it after a single run.

Troubleshooting

Section titled “Troubleshooting”
Symptom Cause
TX402_LIQUIDITY with available: "0" USDC is on the wrong network, or a faucet sent a different token contract
TX402_TRANSPORT with causeCategory: "timeout" Public RPC is slow; the per-provider budget is 600 ms
TX402_TRANSPORT with chain-id-mismatch An RPC endpoint answered for another chain — tx402 refuses to trust it
TX402_PAYMENT_REQUIRED_INVALID eip712-domain-… The merchant omitted extra.name/extra.version, or named a version the token does not use