unbalancedDocs

API preview

Unbalanced API

Send a no-limit hold’em cash hand up to the moment you act, plus any reads you have. Get back a legal action, its exact size, and a short reason.

PreviewEverything below runs against the preview API at https://api.unbalanced.dev. Endpoints marked at launch are part of the published contract but not served yet.

Every answer is checked against a full replay of the betting before it is returned, so the action is always legal and the amount always fits the stacks. Spots the rules settle are answered by rule. Spots that need judgment go to a model.

Quickstart

The preview needs Node.js 24 and pnpm. It binds to your own machine only.

1. Start the preview

Install once, then start the server. It listens on port 5290. Set UNBALANCED_PORT to pick another.

2. Check it is up

GET /healthz answers {"status":"ok"}.

3. Send a hand

Post the hand as JSON to /v1/decisions. This flop spot is settled by the rules, so the preview answers it without a model. Spots that need judgment return 503 temporarily_unavailable until a model provider is configured.

Authentication

At launch, every call that touches your project sends a project key as a bearer token. Keys are created in the API console and shown once. Test and live keys carry different prefixes.

Each key carries scopes. Each endpoint below lists the scope it needs.

ScopeAllows
decisions:writeQuote and analyze decisions.
decisions:readRecover a decision’s status and receipt.
usage:readList your project’s usage.
billing:readRead your credit balance.

Health, capabilities, pricing and the OpenAPI file are public. The local preview takes no key, and refuses requests sent from a browser page.

Describing a hand

A hand is the table as it stood when it was your turn: who sat where, the blinds, your cards, the board, and every action before yours. Unbalanced replays it to work out the pot, the stacks and the price to call.

  • Seats are numbered 1–9 clockwise, gaps allowed. Give each seat’s stack before it posted anything. Blind seats and positions are worked out from button_seat.
  • Cards are two characters, rank then suit, case-sensitive: As, Td, 9c.
  • The board has 0, 3, 4 or 5 cards in deal order. Its length sets the street.
  • Actions are in order, blinds included. Checks and folds carry no amount.
  • Assertions are optional. Send the pot, your stack or the price to call as you see them, and a mismatch comes back as a field-level error instead of a wrong answer.

The API never needs a username, account or table name, and it does not accept other players’ hole cards, showdown results or future cards. See the full Hand object.

Amounts and sizing

All money in a hand is an integer in one unit: usd_cent or chip. Billing is separate and always in USD micro-units, where 1,000,000 equals one dollar.

Bets, calls and raises give street_total: the player’s total put in on that street after acting, not the amount they added. The answer gives both.

SituationAnswer
You have 500 in and raise to 2,000raise, street_total: 2000, amount_added: 1500
You add 300 to call a total of 800call, street_total: 800
You call all-in for lesscall with all_in: true
Check or foldstreet_total: null, amount_added: 0

Opponent evidence

Add up to 24 labeled observations about the other players. Each has an id unique to the request and the seat it describes. Leaving evidence out and sending an empty list mean the same thing.

KindWhat it holds
readA sentence, marked observed or hypothetical. Hypothetical reads are treated as assumptions.
statisticCounts by outcome over real opportunities, in a stated context.
estimateYour own probabilities in basis points, totaling 10,000.
prior_handAn excerpt of a finished hand that shows a pattern. Up to four.

The answer lists the evidence IDs it used and labels every assumption it made, so you can tell your data apart from the model’s guesses.

Model, effort and speed

Everything in options is optional. Rule-settled spots ignore model settings and report them as null.

A model, effort or speed is never swapped for another. If the one you asked for is unavailable, the request fails instead.

Idempotency and retries

At launch, POST /v1/decisions requires an Idempotency-Key header: 16–128 characters from A–Z a–z 0–9 _ . ~ -. You are charged once per key.

  • If a call fails on the network, send the same key and the same body again. You get the original answer back.
  • The same key with a different body returns 409 idempotency_conflict.
  • While the first call is still running, a repeat returns 409 request_in_progress with a retry hint.
  • A 429 or 503 that was never accepted can be retried with the same key.

Answers stay recoverable for 15 minutes. After that, the receipt comes back with result_availability: "expired" and no answer, and nothing is charged again. Set replay_response: false to keep only the receipt.

Errors

Errors use the standard problem format (application/problem+json) with a stable code, the request_id, and a retry hint. Field errors point at the field with a JSON Pointer.

StatusCodesWhat to do
400, 413, 415invalid_json invalid_request missing_idempotency_key payload_too_large unsupported_media_typeFix the request.
401, 403, 404invalid_credentials insufficient_scope not_foundCheck the key, its scopes and the ID.
402insufficient_credits max_charge_exceededAdd credits or raise your limit.
409idempotency_conflict request_in_progress quote_invalidUse a new key, or wait and retry.
422invalid_hand not_hero_turn unsupported_ruleset invalid_evidence unsupported_options strategy_unavailableFix the field named in violations.
429, 503rate_limited capacity_exceeded temporarily_unavailableWait for Retry-After, then retry with the same key.
502, 504invalid_model_answer provider_error deadline_exceededNo answer and no charge. Retry as a new operation.

Limits

These are the preview’s limits. GET /v1/capabilities always reports the ones in force.

Rate-limited responses include X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After.