Copy page

Calculation API

Hold'em equity

Work out each player's share of the pot — their win, tie, and loss probability — for a Texas Hold'em situation. Give each player an exact hand or a range, and optionally a board and dead cards.

POST /v1/calculations/equity/holdem

Smallest runnable example

The minimal call: one hand against another, preflop.

cURL
curl https://api.pokerworks.io/v1/calculations/equity/holdem \
  -H "Authorization: Bearer pw_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "players": [
      { "id": "hero",    "mode": "hand", "hand": ["As", "Ah"] },
      { "id": "villain", "mode": "hand", "hand": ["Kd", "Kc"] }
    ]
  }'

The public TypeScript SDK is coming soon as @pokerworks/sdk; until it is published, treat cURL and the OpenAPI reference as the beta integration source of truth.

Important inputs

• players — two or more players. Each has an id and a mode:
  • mode: "hand" — an exact two-card hand, e.g. ["As", "Ah"].
  • mode: "range" — a set of hand classes, e.g. { "classes": ["JJ", "QQ", "AKs"] }.
• board (optional) — up to five community cards already dealt (flop, turn, river).
• dead (optional) — up to 44 cards removed from the deck so they can't appear.
• iterations (optional) — Monte Carlo sample count when the scenario is too large to enumerate exactly. Maximum 1_000_000; default is 100_000.
• exactSampleThreshold (optional) — maximum exact-combo sample size before using Monte Carlo. Maximum 1_000_000.
• seed (optional) — integer seed for reproducible Monte Carlo runs.
• variant (optional) — currently nlhe.

Cards use two-character notation: rank A K Q J T 9 … 2 plus suit s h d c, e.g. As or Td. Range classes use poker shorthand such as AA, AKs, or AQo; a range can include includeCombos, excludeCombos, and optional weight: 1. Player id values are 1-64 characters, labels are optional, and requests support 2-9 players.

Response highlights

• Each player's win / tie / loss probability and overall equity.
• The method used — exact enumeration for small scenarios, otherwise a seeded Monte Carlo estimate with its sample count and margin of error.
• The standard envelope: requestId, creditsCharged, engine, method, warnings, and result.

result contains board_cards, dead_cards, street, sampleCount, chopPct, and players. Each player result includes id, optional label, winPct, tiePct, equityPct, potShare, wins, ties, rawComboCount, effectiveComboCount, and optional marginOfErrorPct.

Common mistakes

• Using a management token (pw_mgmt_…) — calculation calls need a product key (pw_test_ / pw_live_). See Authentication & API keys.
• Reusing a card across hands, the board, or dead cards — every card must be unique.
• Treating a large range-vs-range result as exact — those return a Monte Carlo estimate; read marginOfErrorPct instead.

Reference

Full schema and all fields → API reference