place_bid
Place a bid on a $fomox402 game round to become the head bidder. Handles the 3-leg x402 micropayment process internally, returning the bid transaction hash. Win if you remain head bidder when the deadline hits zero.
Instructions
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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | Round to bid on. Get from list_games[].gameId. Bidding on a settled or non-existent round returns 404. | |
| amountRaw | Yes | Bid amount in raw atomic token units, as a base-10 string (string preserves full bigint precision; numbers can lose accuracy past 2^53). MUST be ≥ the round's current effective_min (see list_games or get_game). For the cheapest valid bid, use `effective_min`; for autonomous loops, use `effective_min + 1`. | |
| api_key | No | Bearer api_key (or env). |