Buyer quickstart

How to call and pay for Quartermaster paid endpoints as an x402 buyer. No account, no API key - just a wallet.

The model in one paragraph

Quartermaster is the seller. You are the buyer. You call a paid endpoint; if you have not paid, it returns 402 Payment Required with machine-readable payment requirements. An x402-capable client reads those requirements, signs a USDC payment on Base, and retries the request with the payment attached. Quartermaster verifies the payment through the facilitator and returns the result. That is the whole loop - two requests, settled for under a cent of gas.

Cheapest endpoint to test with

Use the $0.001 HTTP error explainer:

https://quartermaster.surewhynot.app/v1/http-errors/429

price: 0.001 USDC
network: Base mainnet
asset: USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
payTo: 0xc2a36e22ecbf353086cf83e7beea78bc28a64083

1. See the unpaid 402 (no wallet needed)

curl -i "https://quartermaster.surewhynot.app/v1/http-errors/429"

You get HTTP 402 and a PAYMENT-REQUIRED header (base64 JSON). That is the payment challenge - scheme, network, asset, amount, and payTo.

2. Pay for it from Node/TypeScript

Install the buyer packages, then run one paid call. The full runnable script is in the repo at examples/buyer-test.ts.

npm install @x402/fetch @x402/evm viem dotenv

import "dotenv/config";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);

const payFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
});

const res = await payFetch("https://quartermaster.surewhynot.app/v1/http-errors/429");
console.log(res.status, await res.json());

3. .env (never commit this)

EVM_PRIVATE_KEY=0xYOUR_BURNER_WALLET_PRIVATE_KEY

Copy examples/.env.example to examples/.env, then run npm run buyer:test.

Expected successful response

HTTP 200
{
  "code": 429,
  "name": "Too Many Requests",
  "category": "client_error",
  "retryable": true,
  "retry_guidance": "Retry after the Retry-After interval; back off exponentially if absent."
}

Security - read this before you fund anything

Use a BURNER wallet only. Never a wallet that holds anything you care about.
Fund it with a tiny amount. A dollar or two of USDC covers hundreds of calls.
The private key stays on your machine. It only signs payments locally.
Never paste a seed phrase into a script, a website, or an AI chat. This needs a private key, not a seed phrase.
Never commit .env or any key file. Add .env and *.key to .gitignore.
Check the endpoint URL, the payTo, and the amount before you sign.

Troubleshooting

Unpaid request returns 402

Expected. Paid endpoints always return 402 until payment is attached.

Paid client still gets 402

Wallet lacks USDC on Base; wrong network; payment expired; the client did not attach the PAYMENT-SIGNATURE header; the facilitator rejected the payment; or the endpoint URL changed between the challenge and the retry. Confirm the wallet holds USDC on Base mainnet and that you are calling the exact URL from the challenge.

Payment seems to settle but no response

Quartermaster finalizes settlement just after sending the response, so the PAYMENT-RESPONSE header is often absent even on success. Verify on-chain with the transaction hash if you need proof.

Claude or another MCP client sees the server but paid tools fail

Standard MCP clients (Claude Desktop, Claude.ai) have no wallet and cannot pay. That is expected - the free tools still work. To pay, use the buyer script above with your own wallet, or an x402-aware client. See Connect.

Bazaar does not list a resource

No successful settlement yet; missing Bazaar metadata; wrong facilitator; stale indexing; or a resource/payTo mismatch. Listings appear after the first metadata-carrying settlement, with a few minutes of indexing lag.

llms.txt - agent-readable index . OpenAPI spec . MCP server . x402 Inspector . Service status . All tools