Get started

Quickstart

Copy as Markdown

# Quickstart

Send a test request before you use live credits.

## 1. Create a key

With an active Plus or Pro plan, create a test key in [Developers](/developers).

```bash
export OPONO_API_KEY='sk_test_REPLACE_WITH_YOUR_KEY'
```

Test output is synthetic and costs zero credits; Free has no API access.

## 2. Simulate a match

```bash
curl --request POST 'https://api.opono.com/v1/simulations' \
  --header "Authorization: Bearer $OPONO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: match-example-1' \
  --data '{"home":"Everton","away":"Chelsea","date":"2026-10-18","draws":1000}'
```

With a live key, this request reserves 1,000 simulated matches · 1 credit and settles the credits on delivery.

## 3. Read the response

```json
{
  "object": "simulation",
  "fixture_id": 19609874,
  "state": "provisional",
  "data_version": "2026-10-13:predicted:b167bda637016662e2585f872b25dea30f954c9a56bd5a345ff965b1663eee10",
  "livemode": false,
  "credits_charged": 0,
  "simulation": {
    "schema": "opono.simulation.v1",
    "basis": {
      "as_of": "2026-10-12T18:30:00Z",
      "data_version": "2026-10-13:predicted:b167bda637016662e2585f872b25dea30f954c9a56bd5a345ff965b1663eee10"
    },
    "result": {
      "home": 0.47,
      "draw": 0.26,
      "away": 0.27,
      "calibrated": true
    },
    "goals": {
      "expected": {
        "home": 1.69,
        "away": 1.27
      }
    },
    "model": {
      "public_name": "Opono Robin",
      "status": "unqualified"
    }
  }
}
```

This excerpt shows a synthetic result; result.home of 0.47 means a 47% home win estimate.

If you receive 202, wait retry_after_seconds and GET the returned result_url, preserving its reservation_id query parameter.

Keep polling until you receive a delivered simulation or a terminal failed or superseded job.

## 4. Use live output

Set OPONO_API_KEY to a sk_live_ key and select a returned [fixture ID](/docs/fixtures).

Reuse your Idempotency-Key and exact body after a network failure to avoid a second charge.

See the [simulation reference](/docs/reference/simulations) for the full response and [Jobs](/docs/jobs) for polling.

Send a test request before you use live credits.

1. Create a key

With an active Plus or Pro plan, create a test key in Developers.

bash

export OPONO_API_KEY='sk_test_REPLACE_WITH_YOUR_KEY'

Test output is synthetic and costs zero credits; Free has no API access.

2. Simulate a match

bash

curl --request POST 'https://api.opono.com/v1/simulations' \
  --header "Authorization: Bearer $OPONO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: match-example-1' \
  --data '{"home":"Everton","away":"Chelsea","date":"2026-10-18","draws":1000}'

With a live key, this request reserves 1,000 simulated matches · 1 credit and settles the credits on delivery.

3. Read the response

json

{
  "object": "simulation",
  "fixture_id": 19609874,
  "state": "provisional",
  "data_version": "2026-10-13:predicted:b167bda637016662e2585f872b25dea30f954c9a56bd5a345ff965b1663eee10",
  "livemode": false,
  "credits_charged": 0,
  "simulation": {
    "schema": "opono.simulation.v1",
    "basis": {
      "as_of": "2026-10-12T18:30:00Z",
      "data_version": "2026-10-13:predicted:b167bda637016662e2585f872b25dea30f954c9a56bd5a345ff965b1663eee10"
    },
    "result": {
      "home": 0.47,
      "draw": 0.26,
      "away": 0.27,
      "calibrated": true
    },
    "goals": {
      "expected": {
        "home": 1.69,
        "away": 1.27
      }
    },
    "model": {
      "public_name": "Opono Robin",
      "status": "unqualified"
    }
  }
}

This excerpt shows a synthetic result; result.home of 0.47 means a 47% home win estimate.

If you receive 202, wait retry_after_seconds and GET the returned result_url, preserving its reservation_id query parameter.

Keep polling until you receive a delivered simulation or a terminal failed or superseded job.

4. Use live output

Set OPONO_API_KEY to a sk_live_ key and select a returned fixture ID.

Reuse your Idempotency-Key and exact body after a network failure to avoid a second charge.

See the simulation reference for the full response and Jobs for polling.