---
title: "Base Sepolia runbook"
description: "Funding and verifying the Base Sepolia test wallet."
source: https://docs.tx402.io/operations/base-testnet/
---

# 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

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.

```sh
# 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

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    |

- Base Sepolia ETH: [https://www.alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia) or the Coinbase faucet.
- Base Sepolia USDC: [https://faucet.circle.com](https://faucet.circle.com) (select Base Sepolia).

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

```sh
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](/start/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:

```sh
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

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

| 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 |

## More documentation

- Documentation index (Markdown): https://docs.tx402.io/sitemap.md
- Machine index: https://docs.tx402.io/llms.txt · full text: https://docs.tx402.io/llms-full.txt
- This page: https://docs.tx402.io/operations/base-testnet/