# Poker API
> A complete Texas Hold’em toolkit in one fast, fully-local API. Calculate win, tie and equity probabilities for your hole cards against any number of opponents (1–9) on any board — pre-flop, flop, turn or river — using a Monte Carlo simulation with adjustable accuracy. Evaluate the best five-card hand from any five to seven cards and get its rank and tiebreakers, or describe a hand in plain language. Cards use the familiar notation (As, Td, 9h, 2c) and every endpoint works by GET or JSON POST. Pure server-side compute with no third-party upstream, so responses are instant and the service is always available. Ideal for poker trainers and study tools, game developers, hand-history trackers and odds widgets.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/poker-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 2 req/s
- **Basic** ($6/Mo) — 15,000 calls/Mo, 5 req/s
- **Pro** ($18/Mo) — 120,000 calls/Mo, 15 req/s
- **Mega** ($45/Mo) — 600,000 calls/Mo, 40 req/s

## Endpoints

### Poker

#### `GET /v1/describe` — Describe a hand

**Parameters:**
- `cards` (query, required, string) — 5 to 7 cards Example: `KhKdKs2h2d`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poker-api/v1/describe?cards=KhKdKs2h2d"
```

**Response:**
```json
{
    "data": {
        "hand": "Full House",
        "rank": 7,
        "cards": [
            "Kh",
            "Kd",
            "Ks",
            "2h",
            "2d"
        ],
        "description": "Full House (K high)",
        "tiebreakers": [
            "K",
            "2"
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:09.920Z",
        "request_id": "99aac6e1-3bfc-4638-b042-d72ff4d39705"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/evaluate` — Evaluate best 5-card hand

**Parameters:**
- `cards` (query, required, string) — 5 to 7 cards Example: `AsKsQsJsTs9d2c`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poker-api/v1/evaluate?cards=AsKsQsJsTs9d2c"
```

**Response:**
```json
{
    "data": {
        "hand": "Straight Flush",
        "rank": 9,
        "cards": [
            "As",
            "Ks",
            "Qs",
            "Js",
            "Ts",
            "9d",
            "2c"
        ],
        "tiebreakers": [
            "A"
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:09.993Z",
        "request_id": "b69c310c-e155-4497-a000-bdb07dae060d"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/odds` — Equity calculator (Monte Carlo)

**Parameters:**
- `hero` (query, required, string) — 2 hole cards (e.g. AsKs) Example: `AsKs`
- `opponents` (query, optional, string) — Number of opponents 1-9 (default 1) Example: `1`
- `board` (query, optional, string) — 0, 3, 4 or 5 community cards
- `iterations` (query, optional, string) — Simulation count 1000-500000 (default 25000) Example: `10000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poker-api/v1/odds?hero=AsKs&opponents=1&iterations=10000"
```

**Response:**
```json
{
    "data": {
        "hero": [
            "As",
            "Ks"
        ],
        "board": [],
        "method": "monte-carlo",
        "opponents": 1,
        "iterations": 10000,
        "tie_percent": 1.44,
        "win_percent": 66.5,
        "lose_percent": 32.06,
        "equity_percent": 67.22
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.182Z",
        "request_id": "e49a3e2d-e027-4eaf-a07b-9c9cf8fa6836"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/poker-api
OpenAPI spec: https://www.oanor.com/api/poker-api/openapi.json