For developers / Application APIs

Arcade server

A WebSocket server for eight games, with a handful of HTTP routes beside it. For seven of the eight, a client sends no game input at all - the input is a transaction, and the socket is how you watch it land.

A socket, not an API

One process runs eight game rooms plus a lobby on one event loop, reads the chain over its own socket to the node, and fans the result out to every connected client. The interface is the WebSocket; the HTTP routes exist for health checks and for the two figures the site's chrome draws on every page.

The game input is a transaction, not a frame

Steering in the arena, a bet on the curve, a spin, a bet on the board - all of them are transactions the player sends to a contract. This socket carries who you are watching, a liveness ping, and the server's view of what the chain did. Nothing a client sends over it authorises anything or changes an outcome.

The claw room is the deliberate exception: driving a claw would be a transaction per frame, so the intents ride the socket. Even there the seam is narrow - three verbs, none of which carries a position, a time or a verdict, and the driver is authorised by a preimage the browser already published on chain in its own pull.

Connecting

Endpoint	Value
Socket	wss://minigame.picklechain.xyz/ws/<room>the site's own nginx forwards the upgrade
HTTP	https://minigame.picklechain.xyz/api/the same process, with the prefix stripped
A stack you run	http://127.0.0.1:3008the arcade site; the server itself is on the container network
Origin	checked on the upgradean Origin not on the configured list is refused 403 before the handshake, so the socket never opens

An unknown path under /ws/ is refused 404 at upgrade, and a connection over the limits below is refused 429 - both as a plain HTTP response on the raw socket, before any WebSocket handshake. A client that only handles theerror event of its socket will see a generic failure; read the status if you want to know which.

The nine rooms

/ws/arena

room

On join: `hello`, then a full snapshot of the arena.

The snake arena. Steering is a transaction, so the socket carries no input for it.

/ws/crash

room

On join: `hello`, then the whole round: phase, time left, the commitment, every bet placed and every cash-out judged so far.

The curve. Bets are transactions.

/ws/claw

room

On join: `hello`, then the cabinet: what is left, where each capsule stands, the machine's constants and every attempt being driven.

The claw cabinet, and the ONLY room whose gameplay input rides this socket rather than the chain - a transaction per frame is not a game.

/ws/patch

room

On join: `hello`, then the machine: the bet ladder, the paytable, the meter and the spins still open.

The reels. A spin is a transaction; the socket watches it.

/ws/trellis

room

On join: `hello`, then the table: every cell's multiplier, the current snapshot, the line so far and the bets still standing.

The board. Bets are transactions; the socket has one verb, and it buys nothing.

/ws/stack

room

On join: `hello`, then `stack`: every run being climbed with its rules state, the day's board and the rules' constants.

The tower. A start and every tap are transactions; the socket only listens, and says what the rules made of each tap.

/ws/derby

room

On join: `hello`, then `derby`: the current and next race, recent history, the rules and the paddock.

The race. A bet is a transaction; the socket only listens, and every runner is one of the chain's own oracle feeds.

/ws/glide

room

On join: `hello`, then `glide`: the day's board, every run in the air, the canyon cards and the rules.

The canyon. A start and every flap are transactions; the socket only listens, and the canyon it draws comes from a live price feed.

/ws/hall

room

On join: `hello` alone.

The lobby. Somebody who has not chosen a game sits here, and it is counted in the socket total.

Every room answers the same opening sequence: a hello frame carrying the room name, the number playing, the number watching and the settle operator's address, then a full snapshot of that room's state. Both counts are ROOM-RELATIVE - they used to come from the arena whatever room you had asked for, which announced players who were not there.

What a client may send

watch

every room

Shape: {"t":"watch","account":"0x…"}

Says which account this socket is following, so the server can address one player directly - a refused join has to reach the person it was refused for. In the reels room it also arms that account.

Worth knowing. It AUTHORISES NOTHING. The account is not verified, the contract decides who may play, and the address must match a 40-hex pattern or the message is ignored in silence.

ping

every room

Shape: {"t":"ping","id":<any>}

Answered with `{t:"pong", id}`. The server also sends protocol-level pings and terminates a socket that stops answering them.

Worth knowing. This is not the liveness mechanism the server relies on; it is the one a client can observe.

claim / drive / drop / release

the claw room only

Shape: {"t":"claim","tx":"0x…","secret":"0x…"} and three verbs after it

Takes the wheel of an attempt and drives it. The proof is a preimage: the hash of the secret must equal the seed the pull published on chain, so the only client that can drive an attempt is the one that made it - no signature, no challenge, no round trip.

Worth knowing. None of the verbs carries a position, a time or a verdict. A wrong secret is refused and counted and never logged. A reconnect takes the wheel from the previous socket, which is told so.

quote

the trellis room only

Shape: {"t":"quote", …}

Asks the operator to sign the price already printed in a square.

Worth knowing. It carries no stake and no account, and the contract checks the clock, the lock and the float itself. A flood of them costs this process signatures and nothing else.

javascript

const socket = new WebSocket("wss://minigame.picklechain.xyz/ws/crash");

socket.addEventListener("open", () => {
  // Tell the server which account to address directly. It verifies nothing:
  // this only decides who a per-player frame is sent to.
  socket.send(JSON.stringify({ t: "watch", account: myAddress }));
});

socket.addEventListener("message", (event) => {
  const frame = JSON.parse(event.data);
  switch (frame.t) {
    case "hello": /* room, playing, watching, operator */ break;
    case "full":  /* the whole room, sent once after hello */ break;
    case "chain": /* resyncing, and the range of mini-blocks lost, if any */ break;
    default:      /* IGNORE. The frame list is not versioned and rooms gain frames. */
  }
});

What the server sends

Every frame is a JSON object with a `t` discriminator. `hello` arrives first and carries the room, the number playing, the number watching and the operator's address; a full snapshot follows. After that the room pushes what changed.

Across the eight rooms: chain, tick, state, full, bet, settled, settle-failed, refused, refunded, refund-due, fulfil-failed, pull, claimed, released, blocked, armed, quote, feed, unsealed, void, race, started, finished, paddock, board, run, points, flight, over, cancelled, canyons, eat, death, pong.

A gap in the chain is announced, and it means something different per room

The chain frame carries resyncing and the range of mini-blocks the reader could not fetch. It is broadcast to every room, and each one treats it differently: a round that overlapped a lost range says its list of winners may be short rather than announcing it as everybody, and the claw room sends the lost range to its log so the stakes inside it can be found and refunded. A client that ignores this frame will draw a confident picture of an incomplete one.

The HTTP routes

/health

GET

Params: none
Returns: {ok, loop:{p50Ms, p99Ms, maxMs, windowMs}}

Liveness, plus the event loop's recent delay. Eight rooms, a physics step and every socket's fan-out share one loop, so a loop that stalls stalls every quote, every echo and every frame at once.

Worth knowing. This is the figure that answers `the arcade is slow sometimes`. It is measured over ten-second windows and reset each time.

/ready

GET

Params: none
Returns: {ok, reasons, miniBlock, appliedMiniBlock, appliedLagMs, resyncing, lost}

503 when the socket to the node is down, or when the last APPLIED mini-block is more than five seconds old.

Worth knowing. It measures what was applied, not what arrived. Measuring arrival meant a wedged dispatch chain answered 200 while no input had been applied for minutes, which is the exact failure this probe exists to catch.

/state

GET

Params: none
Returns: {total:{playing, sockets, spectators}, arena, crash, claw, patch, trellis, stack, derby, glide, …}

The whole arcade in one object: a summary per game and three numbers for the chrome every page draws. `playing` means somebody with something at stake right now, and each game measures that its own way.

Worth knowing. PUBLIC AND UNAUTHENTICATED, which decides what may appear on it. The crash summary withholds its point until the curve has stopped, and the claw summary carries the published commitment and never a link beneath it - one link is the outcome of the next pull nobody has made.

/inventory

GET

Params: none
Returns: {supply, remaining, claimed, cells, price, pullsPerAccount, commit, chainLeft, blocked, machine}

The cabinet on its own, so a page can state what is left without opening a socket.

Worth knowing. 503 when the claw room is not running.

/fair/{pullId}

GET

Params: the pull id in the path
Returns: one finished pull, whole

The seed the player published, every intent the server recorded, the tick the drop landed on and the verdict that came out of them - the arithmetic a reader can rerun.

Worth knowing. A pull still being driven is a 404, deliberately: its trace is not finished and its link is not revealed. A revealed link is served only because the fulfilment that finished the pull already put it on chain.

/stack

GET

Params: none
Returns: {playing, watching, day, pot, top, leaders}

Stack's day without a socket: the UTC day, its pot in wei, the chain's own top three and the tallest runs this server has finished today.

Worth knowing. 503 when the stack room is not running. The pot and the top three are read off the contract once a minute and after each finish, so they can trail a finish by a moment.

/stack/run/{runId}

GET

Params: the run id in the path
Returns: one run, whole: {id, a, t0Us, startMini, taps:[{us, mini, hash}], results, height, why, finished, rules}

Every tap of a run with the mini-block that carried it and what the rules made of it - the arithmetic a reader reruns with arcade-server/src/stack.js to check the height the operator reported.

Worth knowing. A 404 for a run this process never saw or has already let go of; it keeps the last five hundred. The chain still holds every tap, and the rules still apply to them.

/derby

GET

Params: none
Returns: {playing, watching, k, phase, card, unsettled, current, next, history, rules}

Derby's board for a page that has no socket yet: the current race and the next one, recent history, and the rules (the feed allowlist, the wall and night cards, the stake bounds and the seed).

Worth knowing. 503 when the derby room is not running. `unsettled` counts bets still waiting on a settle, across every race this process still holds.

/derby/race/{k}

GET

Params: the race number in the path
Returns: one race, whole: {k, state, card, gate, line, runners, handicaps, pools, startPrices, startRounds, lineRounds, roundsFrom, scores, winners, why, hashes, bets}

The lineup, the handicaps, the rounds both seals named, the scores, the winners and every bet - the arithmetic a reader reruns with arcade-server/src/derby.js against the same public rounds.

Worth knowing. A race this process never opened is a 404. `roundsFrom` says whether each end's rounds came from this room sealing them or were recomputed from the tape after a restart - the proof is the same either way.

/glide

GET

Params: none
Returns: {playing, watching, day, pot, top, leaders, canyons}

Glide's board for a page that has no socket yet, with every canyon's card alongside the day's pot and its leaders.

Worth knowing. 503 when the glide room is not running.

/glide/run/{id}

GET

Params: the run id in the path
Returns: one run, whole: {id, a, feed, symbol, r0, sigma, startUs, startMini, startHash, answers, flaps, result, rules}

r0, the rounds of the canyon this run flew, and every flap with the mini-block that carried it - the arithmetic a reader reruns with arcade-server/src/glide.js `replay` to get the same score.

Worth knowing. A run this process never saw or has already let go of is a 404.

All four are unauthenticated, which is what decides what may appear on them. Nothing that would give away an unfinished round is published: a crash point is withheld until the curve has stopped, and the claw's hash chain is published only as its commitment, with a link revealed on /fair solely because the fulfilment that finished that pull already put it on chain.

Limits, and what breaks them

Bound	Value
Sockets	256 total, 8 per addressthe upgrade is refused 429 before the handshake; the slot is released when the raw socket closes, not when the handshake succeeds
Origin	an allowlistthe upgrade is refused 403, so a page on another origin cannot drive this socket with a visitor's network
Frame size	4 KiBtwo orders of magnitude above the largest real message; the library's default is 100 MiB
Inbound rate	20 a second, burst 4045 and 90 in the claw room, because its driving is on this socket and a hand working a pad passes ten changes a second without trying
Overflow	the socket is closedclosing is kinder than ignoring - and in the claw room it ends a paid attempt, which is why that allowance is the wider one
Backpressure	512 KiB buffereda socket further behind than that is cut and terminated rather than written to; a client that never reads would otherwise grow the process's heap without limit
Liveness	a ping every half minuteanything that has not answered by the next one is terminated

A slow reader is disconnected, not buffered

The library buffers whatever it cannot write, in this process's heap, without limit. So a socket more than half a megabyte behind is cut and terminated rather than written to again - a handful of clients that open a socket and never read it would otherwise exhaust the container, which on a process holding a key is a remote kill. Half a megabyte is about fifty of the largest frames this server sends; no reading client is ever that far behind.

The message budget is wider in the claw room, and that is deliberate

Elsewhere a client sends a ping every few seconds and nothing else, so twenty messages a second can only be a broken or a hostile client. Claw's driving sends one message per change of intent - a press and a release are two - and a player working a pad with both hands passes ten a second without trying. Terminating that socket takes the wheel off somebody mid-attempt, and the attempt they paid for runs out against the rail. So the ceiling there sits above what a hand can produce rather than at it.