x402 Payments

The API supports the x402 protocol for paying with cryptocurrency directly via HTTP headers. This enables AI agents and crypto-native users to pay for playtests without going through Stripe.

Supported Chains & Tokens

Token	Chain	Network ID
USDC	Base	eip155:8453
USDC	Ethereum	eip155:1
USDC	Solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
ETH	Base	eip155:8453
ETH	Ethereum	eip155:1
SOL	Solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

How It Works

Per-Playtest Payment

When creating a playtest via POST /api/v1/games/:gameId/playtests with insufficient credit, you can opt into x402 payment:

Step 1: Send the request with the X-Payment-Method: x402 header. Optionally specify chain and currency:

curl -X POST https://app.weplaytestgames.com/api/v1/games/game_xyz/playtests \
  -H "Authorization: Bearer wpg_sk_..." \
  -H "Content-Type: application/json" \
  -H "X-Payment-Method: x402" \
  -H "X-Payment-Chain: base" \
  -H "X-Payment-Currency: USDC" \
  -d '{"visibility": "private", "quantity": 1}'

Header	Required	Description
X-Payment-Method	Yes	Must be x402
X-Payment-Chain	No	base (default), ethereum, or solana
X-Payment-Currency	No	USDC (default), ETH, or SOL

Valid combinations: Base (USDC, ETH), Ethereum (USDC, ETH), Solana (USDC, SOL).

Step 2: If credit is insufficient, the server responds with 402 Payment Required and payment instructions:

HTTP/1.1 402 Payment Required
X-Payment: {
  "scheme": "exact",
  "network": "eip155:8453",
  "maxAmountRequired": "20000000",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "receiver": "0x...",
  "description": "Purchase 1x 60-min playtest for Dungeon Crawlers",
  "extra": {
    "playtestRequestId": "...",
    "gameId": "game_xyz",
    "x402PaymentId": "..."
  }
}

Step 3: Sign and submit the on-chain transaction, then retry with the payment proof:

curl -X POST https://app.weplaytestgames.com/api/v1/games/game_xyz/playtests \
  -H "Authorization: Bearer wpg_sk_..." \
  -H "Content-Type: application/json" \
  -H 'X-Payment: {"txHash":"0xabc...","chain":"base","currency":"USDC"}' \
  -d '{"visibility": "private", "quantity": 1}'

Step 4: The server verifies the payment on-chain and activates the playtest.

Credit Top-Up via x402

You can also top up your account credit with crypto:

POST /api/v1/billing/credit/x402

Scope: game_owner

Same x402 flow, but credits your account balance instead of activating a specific playtest. This lets you add credit with crypto and spend it via normal API calls.

Confirmation Times

Chain	Confirmations	Typical Time
Base	1 block	~2 seconds
Ethereum	2 blocks	~30 seconds
Solana	Finalized	~15 seconds

Failure Handling

Scenario	What Happens
Transaction reverted	No activation, no credit. Retry with a new payment.
Server timeout during verification	Client receives 402. A reconciliation job checks every 5 minutes and activates or credits the account.
Overpayment	Excess is added as account credit.
Underpayment	Rejected. Retry with the correct amount.

Frontend Crypto Payments

The web dashboard also supports crypto top-ups without the x402 protocol:

1. Select amount and token/chain
2. Receive a wallet address and exact crypto amount
3. Send the payment or connect your wallet (EVM/Solana)
4. Credit is added once the transaction confirms

This flow uses POST /payments/credit/crypto (cookie-auth) with a polling endpoint for confirmation status.