Quickstart¶
Your agent pays a live x402 offer, and you confirm that the payment was recognized. Start free on Base Sepolia with test USDC, then buy a real good on mainnet.
You need an agent that speaks MCP, or a script that uses a standard x402 v2 client. Both paths are below.
0. Pay from nothing in one command¶
With Node.js 20 or later, and nothing else:
It creates your own key in ~/.vauban-pay, with file permissions 0600, and does not print it. It gets 1 test USDC on Base Sepolia for that key, then pays our demo x402 offer with it. It prints the funding and payment transactions, and a line to read the payment back yourself. Test USDC has no real value.
To do the same on Starknet Sepolia, with test STRK instead of test USDC:
It creates your own Starknet key in ~/.vauban-pay, gets test STRK for it, deploys your account, pays our demo x402 offer on Starknet Sepolia and prints the transactions. Test STRK has no real value.
Steps 2 to 6 do the same by hand on Base Sepolia, so you can see each part and wire it into your own agent or program.
What you need for steps 2 to 6: Node.js 20 or later, and Foundry for the cast command.
0b. Try the research observations on a test network¶
95 research observations are served, per call, on each of three test networks. You pay with test money, which has no real value. Not financial advice. No return is promised.
- Base Sepolia:
https://demo.pay.vauban.tech/x402-base-sepolia/v1/observations/<observation>, 0.02 USDC per call. - Starknet Sepolia:
https://demo.pay.vauban.tech/starknet/v1/observations/<observation>, 0.01 STRK per call. - Solana devnet:
https://demo.pay.vauban.tech/x402-solana-devnet/v1/observations/<observation>, 0.02 USDC per call.
To read the price of one without paying, call its address with a plain GET: it answers 402, with the price in the PAYMENT-REQUIRED header.
To pay one, use a standard x402 v2 client, as in steps 2 to 6: the price and the network are in the 402. If a call answers 503 with a Retry-After header, that observation is not for sale at that moment and nothing is charged: call again after that many seconds.
The 95 observations are the same on each network. Replace <observation> above by one of these names:
btc-usdc-bipower-vol-1h-v1
btc-usdc-close-vwap-1h-v1
btc-usdc-downside-vol-1h-v1
btc-usdc-drawdown-1h-v1
btc-usdc-high-low-span-1h-v1
btc-usdc-mean-trade-15m-v1
btc-usdc-path-efficiency-1h-v1
btc-usdc-previous-day-pools-v1
btc-usdc-range-4h-v1
btc-usdc-realized-vol-15m-v1
btc-usdc-realized-vol-1h-v1
btc-usdc-realized-vol-4h-v1
btc-usdc-relative-volume-15m-v1
btc-usdc-return-15m-v1
btc-usdc-return-1h-v1
btc-usdc-return-4h-v1
btc-usdc-taker-flow-15m-v1
btc-usdc-taker-imbalance-1h-v1
btc-usdc-trade-count-15m-v1
eth-usdc-bipower-vol-1h-v1
eth-usdc-close-vwap-1h-v1
eth-usdc-downside-vol-1h-v1
eth-usdc-drawdown-1h-v1
eth-usdc-high-low-span-1h-v1
eth-usdc-mean-trade-15m-v1
eth-usdc-path-efficiency-1h-v1
eth-usdc-previous-day-pools-v1
eth-usdc-range-4h-v1
eth-usdc-realized-vol-15m-v1
eth-usdc-realized-vol-1h-v1
eth-usdc-realized-vol-4h-v1
eth-usdc-relative-volume-15m-v1
eth-usdc-return-15m-v1
eth-usdc-return-1h-v1
eth-usdc-return-4h-v1
eth-usdc-taker-flow-15m-v1
eth-usdc-taker-imbalance-1h-v1
eth-usdc-trade-count-15m-v1
pol-usdc-bipower-vol-1h-v1
pol-usdc-close-vwap-1h-v1
pol-usdc-downside-vol-1h-v1
pol-usdc-drawdown-1h-v1
pol-usdc-high-low-span-1h-v1
pol-usdc-mean-trade-15m-v1
pol-usdc-path-efficiency-1h-v1
pol-usdc-previous-day-pools-v1
pol-usdc-range-4h-v1
pol-usdc-realized-vol-15m-v1
pol-usdc-realized-vol-1h-v1
pol-usdc-realized-vol-4h-v1
pol-usdc-relative-volume-15m-v1
pol-usdc-return-15m-v1
pol-usdc-return-1h-v1
pol-usdc-return-4h-v1
pol-usdc-taker-flow-15m-v1
pol-usdc-taker-imbalance-1h-v1
pol-usdc-trade-count-15m-v1
sol-usdc-bipower-vol-1h-v1
sol-usdc-close-vwap-1h-v1
sol-usdc-downside-vol-1h-v1
sol-usdc-drawdown-1h-v1
sol-usdc-high-low-span-1h-v1
sol-usdc-mean-trade-15m-v1
sol-usdc-path-efficiency-1h-v1
sol-usdc-previous-day-pools-v1
sol-usdc-range-4h-v1
sol-usdc-realized-vol-15m-v1
sol-usdc-realized-vol-1h-v1
sol-usdc-realized-vol-4h-v1
sol-usdc-relative-volume-15m-v1
sol-usdc-return-15m-v1
sol-usdc-return-1h-v1
sol-usdc-return-4h-v1
sol-usdc-taker-flow-15m-v1
sol-usdc-taker-imbalance-1h-v1
sol-usdc-trade-count-15m-v1
strk-usdc-bipower-vol-1h-v1
strk-usdc-close-vwap-1h-v1
strk-usdc-downside-vol-1h-v1
strk-usdc-drawdown-1h-v1
strk-usdc-high-low-span-1h-v1
strk-usdc-mean-trade-15m-v1
strk-usdc-path-efficiency-1h-v1
strk-usdc-previous-day-pools-v1
strk-usdc-range-4h-v1
strk-usdc-realized-vol-15m-v1
strk-usdc-realized-vol-1h-v1
strk-usdc-realized-vol-4h-v1
strk-usdc-relative-volume-15m-v1
strk-usdc-return-15m-v1
strk-usdc-return-1h-v1
strk-usdc-return-4h-v1
strk-usdc-taker-flow-15m-v1
strk-usdc-taker-imbalance-1h-v1
strk-usdc-trade-count-15m-v1
1. Buy a real good¶
With the buy command¶
First time on Base: buy key new --network base makes your key and prints the address to fund with USDC. Then buy <url>, then the same line with --consent.
Make your key. It prints the address to fund.
Send USDC on Base to that address.
Read the offer, which pays nothing (exit code 2), then pay it with the consent token the first command printed.
npx -y @vauban-pay/mcp buy https://pay.vauban.tech/x402-base-mainnet/v1/intel
npx -y @vauban-pay/mcp buy https://pay.vauban.tech/x402-base-mainnet/v1/intel --consent <token>
You only need USDC on Base (network fees are included in the price): no Starknet account, no node.
key new writes a Web3 v3 keystore and the file of its random password side by side, ~/.vauban-pay/base-mainnet.keystore and base-mainnet.password, both readable by you only (mode 0600). buy finds them on its own. The password sits beside the keystore, so this protects like a plain key file with that mode, and no more. buy key address --network base prints the address again, never the key.
On Starknet, you need a Starknet account that holds STRK and is deployed. buy key new makes a Starknet key, kept in ~/.vauban-pay/starknet-mainnet.json (mode 0600, never printed), and prints the address to fund and deploy. Once it holds STRK, buy key deploy --rpc <url> prints the most deploying it costs and a consent token, and sends nothing. The same line with --consent <token> deploys it under that bound. buy contacts no Starknet node unless you name one, with --rpc <url> or STARKNET_RPC_URL; there is no default node.
Exit codes: 0 paid, 1 not paid, 2 consent needed, 3 sent but not confirmed (do not pay again before checking), 4 a facilitator on your own machine reported a simulated chain: that is not a payment.
With the MCP server or your own client¶
The steps are the same. What changes:
- the offer URL, the network, the asset and the payee: read them from the offer, as in step 4;
- your consent to spend real money, named per network in
PAY_MCP_EVM_I_ACCEPT_MAINNET_SPEND; - on Ethereum, the USDC contract in
PAY_MCP_EVM_ASSETS; - the Starknet mainnet endpoint and resource contract, named by the offer.
- the key: use a keystore of your own, outside
~/.vauban-pay. Thebuycommand of the package README refuses the keystore and password file that steps 0 and 2 leave there, because that password sits in clear beside the key.
2. Create a key for this purpose only¶
Use a key dedicated to agent payments, funded only with what you intend to spend, never a personal wallet's key. Any tool that writes a Web3 Secret Storage v3 keystore will do. With Foundry:
mkdir -p ~/.vauban-pay && cd ~/.vauban-pay && umask 077
openssl rand -base64 32 > payer.password
cast wallet new . payer --unsafe-password "$(cat payer.password)"
The keystore is the file payer, its password is in payer.password, and the command prints the address to fund. Both files are readable by you only.
3. Get test USDC¶
Ask Vauban for 1 test USDC on Base Sepolia, sent to the address of step 2:
cd ~/.vauban-pay
ADDR=$(cast wallet address --keystore payer --password-file payer.password)
curl -s -X POST https://demo.pay.vauban.tech/sponsor/v1/test-usdc \
-H 'content-type: application/json' -d "{\"address\":\"$ADDR\"}"
The answer carries the transaction hash. Each address is funded once. Test USDC has no real value. You only need test USDC: the payment is a signed EIP-3009 authorization, and the service submits it for you.
If the call is refused, open Circle's faucet, pick Base Sepolia and claim test USDC for the same address.
4. Read the offer¶
answers 402. The offer is in the PAYMENT-REQUIRED response header, as base64-encoded JSON:
import base64, json, urllib.request, urllib.error
URL = "https://demo.pay.vauban.tech/x402-base-sepolia/v1/quote"
try:
urllib.request.urlopen(URL)
except urllib.error.HTTPError as e: # 402 expected
h = e.headers["payment-required"]
offer = json.loads(base64.b64decode(h + "=" * (-len(h) % 4)))
print(offer["resource"], offer["accepts"])
The offer carries:
| field | value |
|---|---|
| scheme | exact, exact-pq |
| network | eip155:84532 (Base Sepolia) |
| asset | 0x036CbD53842c5426634e7929541eC2318f3dCF7e (test USDC) |
| amount | 1000000 (1 test USDC) |
| payTo | 0x2311C326dC8654FD75cffC5402fDb06D4095d360 |
5. Pay it¶
With the MCP server¶
Add @vauban-pay/mcp to your MCP client (Claude Desktop, Claude Code, any MCP client), with absolute paths to your two files:
{
"mcpServers": {
"vauban-pay": {
"command": "npx",
"args": ["-y", "@vauban-pay/mcp"],
"env": {
"PAY_MCP_EVM_KEYSTORE_PATH": "/home/you/.vauban-pay/payer",
"PAY_MCP_EVM_PASSWORD_PATH": "/home/you/.vauban-pay/payer.password",
"PAY_MCP_EVM_NETWORKS": "eip155:84532",
"PAY_MCP_EVM_PAYEES": "0x2311C326dC8654FD75cffC5402fDb06D4095d360",
"PAY_MCP_EVM_MAX_PER_PAYMENT": "1000000",
"PAY_MCP_EVM_MAX_PER_SESSION": "5000000"
}
}
}
}
That pays at most 1 test USDC per payment and 5 per session, on Base Sepolia only, to that one payee. Then ask your agent:
Use
pay_for_resourceonhttps://demo.pay.vauban.tech/x402-base-sepolia/v1/quote.
The outcome is paid, with the resource, the transaction and the payer. If it is unpayable, its code names the setting to fix.
With any x402 v2 client¶
Use the x402 foundation's own client, not the older v1 packages:
// Pay an x402 v2 URL with the x402 foundation's standard client.
// Usage: EVM_PRIVATE_KEY=0x... node pay.mjs <url>
import { wrapFetchWithPaymentFromConfig, x402HTTPClient, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
const url = process.argv[2];
const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
console.log("payer", account.address);
const payFetch = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
});
const res = await payFetch(url, { method: "GET" });
const body = await res.text();
const result = new x402HTTPClient(new x402Client()).parsePaymentResult({
status: res.status,
getHeader: (n) => res.headers.get(n),
body: (() => { try { return JSON.parse(body); } catch { return undefined; } })(),
});
console.log("status", res.status, result.paymentStatus);
console.log("payment header", JSON.stringify(result.header ?? null));
6. Confirm you are recognized¶
A settled payment returns 200. A receipt then records your EVM address as having paid for the resource, on Starknet. Read it with one call to your Starknet Sepolia node (JSON-RPC v0.10), at block "latest", its URL in STARKNET_SEPOLIA_RPC_URL. You need no Starknet account and no Starknet key.
- contract:
0x011e92d42cff92edd738ddc9405b3a53b5cce91371c4c520be20e2717f6ac8fa est_ouverte(payer): selector0x03600a7e6d7c7be91e03409ac690f0f4547fdb0f5147af3fcd4cc9ef9bbfbf35, calldata[payer], your EVM address as a plain hex felt
curl -s "$STARKNET_SEPOLIA_RPC_URL" \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"starknet_call","params":[{"contract_address":"0x011e92d42cff92edd738ddc9405b3a53b5cce91371c4c520be20e2717f6ac8fa","entry_point_selector":"0x03600a7e6d7c7be91e03409ac690f0f4547fdb0f5147af3fcd4cc9ef9bbfbf35","calldata":["0xYOUR_EVM_ADDRESS"]},"latest"]}'
It returns 0x1 once your payment is recognized, 0x0 otherwise. If it returns 0x0 right after paying, repeat the call a little later.