Bot API

1. Start

1. Sign in at pivarena.com, then open Account → Bots.
2. Create bot and give it a name. It is a separate account, owned by you, with its own balance.
3. Create key. Copy it right away: it is shown once and only a hash is stored.
4. Fund the bot by sending PIV to its deposit address (Account page, or POST /api/v1/deposit-address).

Base URL: https://pivarena.com/api/v1. Bodies are JSON. Amounts you send are PIV decimal strings ("1.5"). Amounts you get back are satoshi strings (1 PIV = 100000000).

2. Keys & scopes

Send the key on every request: Authorization: Bearer pva_.... Cookies are ignored on /api/v1.

Limits: 120 requests per minute per key, 60 of them writes. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After (seconds). Up to 5 bots per player and 5 active keys per bot. Revoke a key on the Account page and it stops working at once.

3. Bot rules

• Bots are tagged BOT in the lobby, in matches, on profiles and in results.
• A bot can’t play its owner, and bots with the same owner can’t play each other.
• Players can turn off Play against bots. Bots can’t join their games, and bot games are hidden from them and closed to them. /matches/open reports this as joinable: false with a reason.
• The bot arena ("arena":"bots") is bots only. People can watch but not join.
• Bots can’t chat and can’t log in on the website.
• Your account status covers your bots: if your account is frozen, self-excluded or cooling off, your bots can’t start new games either.
• The owner manages the bot on the Account page: move free PIV both ways between the owner’s balance and the bot (staked PIV can’t move; PIV not yet withdrawable stays that way), pause it or delete it. Bot owners are private: no endpoint shows who owns a bot.
• A paused bot’s keys get 403 with "code":"bot_paused". Its open lobby games are cancelled and refunded and its WebSocket is closed (code 4403). It can still finish games already in progress: GET /matches/:id, /action, /cancel and declining challenges keep working. Anything else waits until the owner resumes it.
• A deleted bot’s keys stop working (401). Its balance goes back to the owner, and its name is free again after 30 days.
• Withdrawals: the daily withdrawal cap is shared between an owner and their bots.
• Stakes 0.1 to 1 PIV, at most 5 open games at a time. Minimum withdrawal 1 PIV, network fee 0.05 PIV.

4. Endpoints

Match fields you’ll use most: status (open, active, settled, cancelled), mySeat (-1 if you’re watching), players[] (each with bot and house flags), view (game-specific and only what your seat may see; turn games include toAct and a deadline: move before it or the clock decides), result.

5. Games

Rock paper scissors uses commit–reveal: send sha256(choice + ":" + salt) as hex, then reveal the choice and salt.

6. WebSocket

Connect to wss://pivarena.com/ws/bot with the same Authorization header. Up to 5 sockets per key. Send JSON messages:

{"t":"sub","ch":"lobby"}          // open games, live games, recent results
{"t":"sub","ch":"match","id":123}  // pushes for one match (up to 20)
{"t":"unsub","ch":"match","id":123}
{"t":"ping"}

You receive:

7. Errors

Errors are JSON: {"error":"human readable message"}, some with a machine-readable code, e.g. {"error":"bot paused: the owner paused this bot","code":"bot_paused"}.

8. Examples

curl

export KEY=pva_your_key_here
curl -s https://pivarena.com/api/v1/me -H "Authorization: Bearer $KEY"
curl -s "https://pivarena.com/api/v1/matches/open?arena=bots&game=coinflip" -H "Authorization: Bearer $KEY"
curl -s -X POST https://pivarena.com/api/v1/matches -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"game":"coinflip","stake":"1","options":{"side":"heads"},"arena":"bots"}'

JavaScript (Node 18+)

const KEY = process.env.PIVARENA_KEY;
const api = async (path, body) => {
  const r = await fetch('https://pivarena.com/api/v1' + path, {
    method: body ? 'POST' : 'GET',
    headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  });
  const j = await r.json();
  if (!r.ok) throw new Error(r.status + ' ' + j.error);
  return j;
};

const { matches } = await api('/matches/open?arena=bots&game=connect4');
const game = matches.find((m) => m.joinable);
if (game) {
  await api('/matches/' + game.id + '/join', {});
  let v = await api('/matches/' + game.id);
  while (v.status === 'active') {
    if (v.view && v.view.toAct === v.mySeat) await api('/matches/' + game.id + '/action', { type: 'drop', col: 3 });
    await new Promise((r) => setTimeout(r, 1000));
    v = await api('/matches/' + game.id);
  }
  console.log(v.status, v.result);
}

Python

import os, requests
S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["PIVARENA_KEY"]
BASE = "https://pivarena.com/api/v1"

me = S.get(BASE + "/me").json()
print(me["username"], int(me["balances"]["balance"]) / 1e8, "PIV")

r = S.post(BASE + "/matches", json={"game": "dice", "stake": "0.5", "arena": "bots"})
r.raise_for_status()
print("created match", r.json()["id"])

fair = S.get(BASE + "/matches/%d/fair" % r.json()["id"]).json()
print(fair["serverSeedHash"])

WebSocket (Node, ws package)

import WebSocket from 'ws';
const ws = new WebSocket('wss://pivarena.com/ws/bot', { headers: { Authorization: 'Bearer ' + process.env.PIVARENA_KEY } });
ws.on('open', () => ws.send(JSON.stringify({ t: 'sub', ch: 'lobby' })));
ws.on('message', (raw) => {
  const m = JSON.parse(raw);
  if (m.t === 'lobby') console.log(m.open.filter((g) => g.arena === 'bots').length, 'open bot-arena games');
  if (m.t === 'joined') ws.send(JSON.stringify({ t: 'sub', ch: 'match', id: m.matchId }));
});