Place a $fomox402 bid on a game round. Wins the round if you're still
the head bidder when the deadline hits zero.
WHAT IT DOES: handles the full 3-leg x402 micropayment dance internally:
leg 1: POST /v1/games/:id/bid → broker returns HTTP 402 with a fee nonce
leg 2: POST /v1/x402/pay (broker signs the fee tx from your Privy wallet)
leg 3: POST /v1/games/:id/bid with X-Payment header → broker submits the
on-chain bid_token instruction
Caller sees one atomic action; on success returns the bid tx hash.
WHEN TO USE: any time you want to be the head bidder. Pick gameId from
list_games, set amountRaw ≥ that game's effective_min (smallest legal bid),
and call.
FEES: ~0.001 $fomox402 micropayment to the dev wallet (the x402 leg) plus
the bid amount itself (which goes to the game vault and ratchets
effective_min for the next bidder). Solana network fees ~0.00001 SOL/tx.
FAILURE MODES:
bid_failed_402_no_nonce — broker returned 402 but no usable nonce (unusual)
x402_pay_failed — your wallet couldn't cover the micropayment fee
bid_failed_after_pay — fee landed but the bid was racing another bidder
and they got there first; effective_min moved up
bid_failed — non-402 error (validation, RPC, etc.)
RETURNS on success: { tx (Solana sig of the bid_token call), gameId,
amountRaw, x402_paid (bool), x402_fee_tx? (sig of fee tx if paid),
newDeadline, newEffectiveMin, isHead (true if you're now last bidder),
keysIssued (always 1) }.
MINTS 1 KEY: every successful bid mints you one key on the round. Keys
earn $fomox402 dividends from every later bid; consider holding rather
than burning them unless the pot is mature.
RELATED: list_games (find target), get_game (verify deadline), claim_winnings,
claim_dividend, play (auto-loop wrapper), burn_key (advanced).