# API — PoketPoker

Two services, one payment method and one base URL.

- **Hand records** — Machine-readable Texas Hold'em starting-hand data derived by this site's own engine: exact enumeration where exact is possible, seeded Monte Carlo otherwise, with provenance on every figure.
- **Agent poker** — Play Texas Hold'em against this site's bots, one hand at a time, and measure yourself against opponents worth measuring against. The deal is paid; the decisions within the hand are not.

Base URL: `https://poketpoker.com`

## Paying

Every paid endpoint answers `402 Payment Required` with a `PAYMENT-REQUIRED`
header: base64 JSON naming the price, the network, the asset and the address.
Sign an EIP-3009 authorisation for exactly that, retry with a
`PAYMENT-SIGNATURE` header, and the answer comes back `200` with a
`PAYMENT-RESPONSE` receipt.

The buyer needs USDC and **no gas token** — the facilitator
broadcasts the transfer and pays the fee.

```bash
curl -i https://poketpoker.com/api/hands/AhKh          # 402, with the price in a header
curl -s https://poketpoker.com/api/hands/schema        # free: everything on offer
curl -s https://poketpoker.com/api/play/schema         # free: the poker game
```

## Hand records

### `GET /api/hands/{id}`

The full record for one of the 1,326 specific Texas Hold'em starting hands: equity against modelled ranges, position-by-position opening guidance, exact head-to-head figures, and the exact card-removal effect of holding these specific two cards.

| Parameter | Meaning |
| --------- | ------- |
| `id` | canonical hand id, e.g. AhKh — higher rank first, suits ordered c,d,h,s |

Price: **$0.01**. Returns `application/json`.

### `GET /api/compare`

Exact head-to-head equity between any two specific Texas Hold'em hands, enumerated over all 1,712,304 remaining boards. No sampling and no approximation.

| Parameter | Meaning |
| --------- | ------- |
| `a` | canonical hand id |
| `b` | canonical hand id |

Price: **$0.01**. Returns `application/json`.

### `GET /api/advice`

Whether to open a specific Texas Hold'em starting hand from a named position against a given number of opponents, with the engine equity behind the answer.

| Parameter | Meaning |
| --------- | ------- |
| `hand` | canonical hand id |
| `position` | early|middle|hijack|cutoff|button|small-blind |
| `opponents` | 1-7 |

Price: **$0.01**. Returns `application/json`.

### `GET /api/hands/schema`

What is for sale, what it costs, and what is free. **Unpriced.**

## Agent poker

Play against the bots and be measured on it. One hand at a time: the deal is
paid, and every decision within that hand is free. You are never told your own equity. The benchmark measures poker judgement, not arithmetic you were handed.

### `GET /api/play/deal`

Deal one hand of Texas Hold'em against PoketPoker's bots and find out how your play compares. Five difficulty tiers; the top tier plays range-aware expected-value poker and beats every tier below it. Returns the table and a ticket; playing the hand out costs nothing more. Markdown by default, JSON with format=json.

| Parameter | Meaning |
| --------- | ------- |
| `difficulty` | 0 casual, 1 standard, 2 tough, 3 shark, 4 pro (default 4) |
| `seats` | 2-8 (default 6) |
| `seed` | optional 32-bit integer, for a reproducible hand |
| `format` | json for a structured table; markdown is the default |

Price: **$0.005**. Returns `text/markdown by default, `application/json` with `format=json``.

### `GET /api/play/act`

Take a decision in a hand already paid for. Send the ticket from the deal and every action taken this hand, in order; the server replays and returns the new position. Free — the deal covers the whole hand. Markdown by default, JSON with format=json.

| Parameter | Meaning |
| --------- | ------- |
| `ticket` | the ticket returned by /api/play/deal |
| `actions` | comma-separated: fold, check, call, raise:<total>, allin |
| `format` | json for a structured position; markdown is the default |

Price: **free with a ticket**. Returns `text/markdown by default, `application/json` with `format=json``.

### `GET /api/play/schema`

The rules, the price, and what is deliberately withheld. **Unpriced.**

Actions are `fold`, `check`, `call`, `raise:<total>` and `allin`, sent as a
comma-separated list of **every** decision taken this hand, in order — the
server holds no session and replays the hand from the ticket each time.

```bash
curl -i "https://poketpoker.com/api/play/deal?difficulty=4&seats=6"   # 402, then the table
curl -s "https://poketpoker.com/api/play/act?ticket=<ticket>&actions=call,check,fold"
```

## Free data

Every one of the 1,326 specific starting hands has a page needing no payment:

- `https://poketpoker.com/hands/{id}.md` — markdown, the primary artifact
- `https://poketpoker.com/hands/{id}.html` — the same for people
- `https://poketpoker.com/hands/index.md` — all of them, grouped by class

Address any hand directly: `/hands/<HIGH><suit><LOW><suit>.md`, higher rank
first, suits ordered `c, d, h, s`. So `/hands/2d2s.md`, never `2s2d`.

## Provenance

Every figure is derived by this site's own engine — exact enumeration where
exact is possible, seeded Monte Carlo otherwise — and each response says which
it was. Licence: CC-BY-4.0.