# Documentation

> Get every round in JSON seconds after the table settles it, with history and statistics ready to use, and build your bot, site or dashboard without copying results by hand.

This page covers what applies to every API, such as authentication, the trial, limits and errors, and each API has its own page with the endpoints, the parameters and what every field in the response means.

Source: https://lynxmetrics.com/en/docs

## APIs

Pick an API to see how it responds. They all live at `https://api.lynxmetrics.com/v1/` followed by the API slug, and responses come inside `data`, with dates in UTC.

### Live casino

- [Bac Bo Live](https://lynxmetrics.com/en/docs/bacbo-live.md): `/v1/bacbo-live`, In Bac Bo Live, Player and Banker roll two dice each. Results, dice and tie multipliers.
- [Lightning Baccarat](https://lynxmetrics.com/en/docs/lightning-baccarat.md): `/v1/lightning-baccarat`, Rounds from Evolution's Lightning Baccarat table: Player and Banker cards, score, winner, pairs and naturals. Lightning multipliers not included.
- [Baccarat 1](https://lynxmetrics.com/en/docs/baccarat-1.md): `/v1/baccarat-1`, Rounds from Pragmatic Play's Baccarat 1 table: Player and Banker cards, score, winner, pairs and naturals.

## Authentication

Each key works for one API only and starts with `sk-lynx`, so create a key in the dashboard for every API you use and send it in the `x-api-key` header, replacing `{api}` with its slug. A key for one API calling another gets `key_wrong_api`. In the dashboard each key is shown masked, with a button to copy it whenever you want and another to rotate it, which swaps the key for a new one and makes the old one stop working within moments.

```bash
curl https://api.lynxmetrics.com/v1/{api}/latest \
  -H "x-api-key: YOUR_KEY"
```

## Catalog

`GET /v1/apis` is open, no key needed, and lists the APIs with their category, status, each one's plans with price and limits and the trial rules in `trial`, and you can filter with `?category=`.

```json
GET /v1/apis

{
  "data": [
    {
      "slug": "bacbo-live",
      "name": "Bac Bo Live",
      "category": "live-casino",
      "provider": "Evolution",
      "status": "live",
      "description": "In Bac Bo Live, Player and Banker roll two dice each. Results, dice and tie multipliers.",
      "plans": [
        {
          "id": "pro",
          "priceCents": 2190,
          "currency": "BRL",
          "maxResults": 250,
          "maxStatsSample": 250,
          "historyDays": 7,
          "requestsPerMinute": 60,
          "maxStreams": 1
        },
        {
          "id": "business",
          "priceCents": 4990,
          "currency": "BRL",
          "maxResults": 1000,
          "maxStatsSample": 1000,
          "historyDays": null,
          "requestsPerMinute": 400,
          "maxStreams": 5
        }
      ],
      "trial": {
        "plan": "pro",
        "durationMinutes": 120,
        "cooldownHours": 24,
        "requiresVerifiedEmail": true,
        "startsOnFirstRequest": true
      }
    }
  ],
  "categories": ["live-casino"]
}
```

## Real time

There are three ways to receive every round, from the fastest to the simplest. All three deliver the same object, so you can start with the simplest and switch later without touching the rest of your code.

1. The `/stream` of each API: an open connection that receives the round the moment it closes. Only opening it counts toward the per-minute limit. Recommended for anything that runs all day.
2. `/latest?wait=20`: a regular request that only answers when the next round closes, or after 20 seconds. It is one request per round, with no open connection to keep, and works from any language that can make a GET.
3. `/latest` polled from time to time: it works, but every poll counts toward the per-minute limit and the round arrives with the delay of your interval. Send the `ETag` in `if-none-match` to get `304` when nothing changed.

Ready-made code for each one, in Python, Node.js and PHP, is in the documentation of each API, under Code examples. To see whether a table is delivering rounds right now, check the [status page](https://lynxmetrics.com/en/status).

## Trial and subscription

Each subscription is an API with a fixed identifier such as `coral-7k2m`, and so is the trial. With a confirmed email, you start each API's trial in your dashboard, which lives in a trial API and gives you a key that works for `trial.durationMinutes` minutes with the `trial.plan` limits and then returns `trial_expired`. Those minutes start counting on the key's first call, not when you created it, so it waits without expiring until you integrate. The next trial of the same API opens up `trial.cooldownHours` hours after the previous one ends, with the same identifier and a new key, and anyone who already subscribes to that API doesn't need a trial. When you subscribe to the trial API, it becomes paid with the same identifier and the same usage, and the trial key becomes a regular key of the plan, with no expiry, so your integration doesn't change. You can subscribe to the same API as many times as you like, each subscription with its own name, plan, keys, per minute limit and usage, and each key works while its subscription is active. Once it ends, the keys return `subscription_required`, and with a pending payment they keep working for 3 days while Stripe tries to charge again, then return `payment_pending` until the payment goes through.

## Limits

Limits come from the plan of the subscription the key belongs to, or from the trial plan while a trial key is valid: the maximum `limit`, the size of `sample` and how many days back `before` can go. A value above the maximum is lowered to the maximum, usage is counted per subscription and the numbers for each plan are in each API's documentation. Each plan also has a requests per minute limit, which applies to each subscription adding up all of its keys, so subscribing to the same API twice gives you two separate limits, and the trial uses the limit of its plan. You can burst up to that number at once, and your allowance refills gradually over the minute. Every response to an accepted key includes `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, which says in how many seconds the allowance is full again; the errors that come before the limit, such as an invalid key, the wrong API and an ended subscription, do not carry those headers, and going over the limit returns 429 `rate_limited` with `Retry-After`, telling you how many seconds to wait.

## Errors

Every error carries a code that never changes and a message in your account's language.

```json
{
  "error": {
    "code": "key_wrong_api",
    "message": "This key belongs to another API."
  }
}
```

| code | HTTP |  |
| --- | --- | --- |
| `bad_request` | 400 | A parameter has an invalid format, such as a before date that is not ISO 8601. |
| `unauthorized` | 401 | Missing, invalid or revoked key. |
| `key_wrong_api` | 403 | The key belongs to another API. |
| `trial_expired` | 403 | The trial key has ended, so subscribe to the trial API in your dashboard and the same key works again. |
| `subscription_required` | 403 | The subscription the key belongs to isn't active. |
| `payment_pending` | 402 | The payment for the subscription the key belongs to has been pending for more than 3 days. |
| `plan_limit` | 403 | The request goes beyond what your plan on this API allows, such as older history. |
| `not_found` | 404 | This API doesn't exist or isn't live yet. |
| `route_not_found` | 404 | This path doesn't exist. |
| `rate_limited` | 429 | Too many requests in a short time, so wait the seconds in Retry-After and try again. |
| `too_many_streams` | 429 | The API has all /stream connections busy right now, so try again shortly. Going over your plan's connection count does not cause this error: the key's oldest connection is ended and the new one takes its place. |
| `internal_error` | 500 | Unexpected error on our side. |
| `upstream_error` | 502 | We couldn't read the data right now, so please try again shortly. |
| `timeout` | 504 | The request took more than 10 seconds, try again in a moment. |
