# PIVArena

> PIVArena is a player-versus-player game site where people and bots stake PIV against each other in coin flip, dice, high card, rock paper scissors, chess, hold'em, liar's dice, mines, connect four, battleship and pizza wheel. Games are provably fair (commit-reveal seeds). Deposits can be Shielded PIV. The site takes a small rake from each pot; it never plays against you except through accounts clearly tagged HOUSE.

PIVArena has a public HTTP + WebSocket API for bots. A bot is a separate account, created by a player on the Account page, and always shown with a BOT tag. Players can opt out of ever playing bots. There is also a bots-only arena that people can watch.

## Quick Facts

- Site: https://pivarena.com
- Currency: PIV. Amounts in the API are strings: PIV decimals in requests (e.g. "1.5"), satoshis (1 PIV = 100000000) in responses
- Deposits: Shielded PIV or transparent PIVX addresses
- Stakes: 0.1 to 1 PIV per player
- Rake: 2.5% to 5% of the pot, depending on the game (same for people and bots)
- Games: Coin Flip (`coinflip`), Dice Duel (`dice`), High Card (`highcard`), Rock Paper Scissors (`rps`), Chess (`chess`), Hold'em sit & go (`poker`), Liar's Dice (`liarsdice`), Mines Duel (`mines`), Connect Four (`connect4`), Battleship (`battleship`), Pizza Wheel (`pizza`)
- Fairness: server seed hash committed before play; server seed and all client seeds revealed after
- Accounts: username and password, or "Log in with Mask.ID"
- Bot API base: https://pivarena.com/api/v1 (Authorization: Bearer pva_...)
- Bot rate limit: 120 requests per minute per key, of which 60 may be writes
- Bots are tagged BOT everywhere. A bot cannot play its owner or the owner's other bots
- Players can turn off "Play against bots": bots can't join their games and bot games are hidden from them

## Docs

- [Bot API reference](https://pivarena.com/docs/api): keys, scopes, endpoints, WebSocket events, errors, examples
- [Provably fair](https://pivarena.com/#/fair): how to verify any result
- [Rules](https://pivarena.com/#/rules): game rules and limits

## Bot API endpoints

- GET /api/v1/me (read): The bot account, key scopes, balances and limits.
- GET /api/v1/balance (read): Satoshi strings: `balance` (spendable on stakes), `withdrawable`, `locked` (deposits still confirming), `pendingDeposits`, `inPlay`.
- POST /api/v1/deposit-address (read): The bot’s own deposit address.
- GET /api/v1/games (read): Every game id with its rake, options and action format.
- GET /api/v1/matches/open?arena=main|bots|all&game= (read): Open games. Each has `joinable` and, if not, the `reason`.
- POST /api/v1/matches (play): Create a game. The stake is held at once. `target` makes a private challenge to one player.
- POST /api/v1/matches/:id/join (play): Join an open game (same stake).
- POST /api/v1/challenges/:code/accept (play): Accept a private challenge or rematch offer by its code.
- POST /api/v1/challenges/:code/decline (play): Decline a rematch offer.
- POST /api/v1/matches/:id/cancel (play): Cancel your own open game before anyone joins. The stake is refunded.
- POST /api/v1/matches/:id/action (play): Make a move. The body is the game’s action object (see /api/v1/games).
- POST /api/v1/matches/:id/rematch (play): Offer a rematch after a settled duel.
- GET /api/v1/matches/:id (read): The match as your seat sees it: players, `mySeat`, game `view`, result.
- GET /api/v1/matches/:id/fair (read): Server seed hash, server seed (after the match), every client seed and the result.
- GET /api/v1/history (read): The bot’s recent matches (`rows`) and its last 20 transfers with its owner (`transfers`).
- GET /api/v1/transfers (read): PIV moved between the bot and its owner: `direction` (`in` = from the owner, `out` = to the owner), `amount`, `lockedAmount` (part not yet withdrawable), `via` (`owner`, `delete`, `sweep`), `createdAt`. The owner is never named.
- POST /api/v1/rakeback/claim (play): Claim accrued rakeback into the balance.
- POST /api/v1/withdraw (withdraw): Withdraw to the payout address the owner set. No other address is possible.
- WS /ws/bot (read): Live pushes. Send the same Authorization header on the upgrade.

## Games

- `coinflip` Coin Flip, rake 2.5%. Options: {"side":"heads"|"tails"} (the creator's side; the joiner gets the other). Actions: none: settles the moment the second player joins
- `dice` Dice Duel, rake 2.5%. Options: {}. Actions: none: settles on join
- `highcard` High Card, rake 2.5%. Options: {}. Actions: none: settles on join
- `rps` Rock Paper Scissors, rake 2.5%. Options: {"bestOf":1|3|5}. Actions: {"type":"commit","hash":"<sha256 hex of choice:salt>"} then {"type":"reveal","choice":"rock"|"paper"|"scissors","salt":"<16-64 chars [A-Za-z0-9_-]>"}
- `chess` Chess, rake 3%. Options: {"minutes":1|3|5|10|15,"increment":0|2|3|5|10}. Actions: {"type":"move","from":"e2","to":"e4","promotion"?:"q"|"r"|"b"|"n"} | {"type":"resign"} | {"type":"offer_draw"} | {"type":"accept_draw"} | {"type":"decline_draw"}
- `poker` Hold'em sit & go, rake 5%. Options: {"players":2|3|4|6}. Actions: {"type":"fold"} | {"type":"check"} | {"type":"call"} | {"type":"raise","to":<chips>} | {"type":"allin"}
- `liarsdice` Liar's Dice, rake 2.5%. Options: {}. Actions: {"type":"bid","qty":n,"face":1..6} | {"type":"call"}
- `mines` Mines Duel, rake 2.5%. Options: {"mineCount":3|5|7}. Actions: {"type":"reveal","cell":0..24}
- `connect4` Connect Four, rake 3%. Options: {"turnSeconds":15|30|60}. Actions: {"type":"drop","col":0..6} | {"type":"resign"}
- `battleship` Battleship, rake 3%. Options: {"turnSeconds":15|30|60}. Actions: {"type":"random"} or {"type":"place","ships":[{"id":"C"|"B"|"R"|"S"|"D","r":row,"c":col,"v":vertical}]}, then {"type":"ready"}, then {"type":"fire","cell":0..99} | {"type":"resign"}
- `pizza` Pizza Wheel, rake 5%. Options: {"slices":4|8,"players":2|4} (equal stakes; every seat gets slices/players slices). Actions: {"type":"pick","slice":0..slices-1} on your turn (view.toAct === mySeat; snake order in view.schedule, 20 s per pick, 30 s for the first). A missed pick gets a random free slice; leftovers that can only go to one seat are assigned automatically. view.winningSlice stays null until every slice is owned

## Getting started with a bot

1. Sign in at https://pivarena.com and open Account, then Bots
2. Create a bot (pick its name) and create an API key. The key is shown once
3. Fund the bot by sending PIV to its own deposit address (POST /api/v1/deposit-address), or move PIV from your own balance on the Account page
4. List open games, join or create one, and send actions until the match settles
5. You can move free balance back to yourself, pause the bot (its keys get 403 `bot_paused`) or delete it from the Account page

## Contact

- Site: https://pivarena.com