Sport Feed API

Catalogue, fair probabilities and market results over HTTPS, WebSocket and RabbitMQ. This reference covers the /v1 API.

Available data

Choose a delivery method

The RabbitMQ Python and Java examples implement the join and recovery protocol. Use them as the starting point for an AMQP integration.

Start here

API conventions

Access and authentication

The HTTPS API and RabbitMQ use separate credentials. Both endpoints require your outbound public IP to be allowlisted.

Connection addresses

Trust the supplied public CA certificates and verify the server address. Keep the client clock within 0.5 seconds of UTC for AMQP freshness checks.

Required onboarding details

Configure HTTPS requests

Run in Bash. On macOS, enter bash first if your shell is zsh. Put the supplied API trust certificate in certs/api-ca.pem relative to the current directory.

export FEED_API_URL='https://13.42.174.100'
export FEED_API_CA_FILE="$PWD/certs/api-ca.pem"
read -r -s -p 'API key: ' FEED_API_KEY; printf '\n'
export FEED_API_KEY

Keep keys out of URLs and checked-in files. The commands below use the environment variables set here; the documentation does not make authenticated requests from your browser.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/sports"

Check network and certificate access

curl --silent --show-error --fail-with-body \
  --cacert "$FEED_API_CA_FILE" \
  "$FEED_API_URL/v1/health"

{
  "status": "ok",
  "ts": "2026-10-24T14:23:53.000Z"
}

/v1/health requires no API key, but network allowlisting still applies. An ok health response does not establish an AMQP join or make a cached price usable.

Run a reference consumer

Python and Java consumers maintain the price view, recover after gaps, and store results before acknowledging them.

1. Download the client examples

Download sport-feed-examples.tar.gz and place it in your Linux working directory. Run the setup and connection commands in the same Bash session.

tar -xzf sport-feed-examples.tar.gz
cd sport-feed-examples

python3 -m venv .venv
.venv/bin/pip install --require-hashes \
  -r examples/amqp/python/requirements.txt

mvn -f examples/amqp/java/pom.xml package

2. Set connection parameters

Place the supplied certificates in certs/. Replace yourclient and 1 with your assigned client ID and queue set. The example below selects football prices and event objects.

export FEED_AMQP_URL='amqps://3.11.110.34:5671/feed'
export FEED_API_URL='https://13.42.174.100'
export FEED_AMQP_CA_FILE="$PWD/certs/broker-ca.pem"
export FEED_API_CA_FILE="$PWD/certs/api-ca.pem"
export FEED_CLIENT='yourclient'
export FEED_QUEUE_SET='1'
export FEED_BINDINGS='football.#'
export FEED_EVENTS='1'
unset FEED_UNBIND
export FEED_RESULTS_FILE="$PWD/data/results.jsonl"
mkdir -p data

read -r -p 'Broker username: ' FEED_AMQP_USER
read -r -s -p 'Broker password: ' FEED_AMQP_PASSWORD; printf '\n'
read -r -s -p 'API key: ' FEED_API_KEY; printf '\n'
export FEED_AMQP_USER FEED_AMQP_PASSWORD FEED_API_KEY

For this example the queues are c_yourclient.prices.1 and c_yourclient.results.1. They must already exist. The client binds the prices queue; the operator has already bound heartbeats and results.

3. Start the consumer

.venv/bin/python examples/amqp/python/consumer.py

java -jar examples/amqp/java/target/amqp-consumer-1.0.0.jar

Run one of these. Stop it with Control+C. To copy a documentation block on Mac, use Copy or Select followed by ⌘C.

{"kind":"status","joined":true,"session":"s_example","join_version":1792851832100000,"rows":2,"events":1,"t":1792851832.1}
{"kind":"row","via":"update","market_id":"mk_01KAZ000000000000000000004","event_id":"ev_01KAZ000000000000000000002","version":1792851833000001,"state":"open","status":"active","t":1792851833.0}

kind messages are the example’s diagnostic output, not the raw AMQP payload. A successful join may contain zero rows. A later joined:false suspends every previously printed price.

4. Read prices through the suspension gate

In an application, use the consumer’s price(market_id) method when reading a price. It returns a suspended view with null probabilities while disconnected or stale. Reading the raw row cache bypasses this protection.

Keep FEED_RESULTS_FILE across restarts. Each active or standby process needs its own file. The journal is an example durable sink; a production application can replace it with a database transaction while preserving the store-before-ACK rule.

Catalogue endpoints

Discover IDs from the API, then use those IDs in price filters and RabbitMQ bindings. Sports and competitions appear only when they have listed events.

sport: football
  └─ competition: cp_…
       └─ event: ev_…
            ├─ market: mk_…  1x2 / match
            └─ market: mk_…  total / match / 2.5

List sports

Returns every sport with at least one listed event. Not paginated. The scheduled/live counts describe events, not open markets.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/sports"

{
  "data": [
    {
      "id": "football",
      "name": "Football",
      "events_scheduled": 0,
      "events_live": 1
    }
  ]
}

List competitions

Returns competitions with listed events, sorted by name. Use sport for a comma-separated list of sport slugs. country is null for international competitions.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/competitions?sport=football&limit=100"

{
  "data": [
    {
      "id": "cp_01KAZ000000000000000000001",
      "sport": "football",
      "name": "Example Premier Division",
      "country": "England"
    }
  ],
  "next_cursor": null
}

List events

Different filters combine with AND. Values within one comma-separated filter combine with OR. Events are sorted by scheduled_start, then id. Markets are not included in this list response.

# Replace this with an ID from /v1/competitions.
COMPETITION_ID='cp_01KAZ000000000000000000001'
curl --silent --show-error --fail-with-body --compressed --get \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  --data-urlencode "competition=$COMPETITION_ID" \
  --data-urlencode 'status=scheduled,live' \
  --data-urlencode 'limit=100' \
  "$FEED_API_URL/v1/events"

{
  "data": [
    {
      "id": "ev_01KAZ000000000000000000002",
      "sport": "football",
      "competition": {
        "id": "cp_01KAZ000000000000000000001",
        "name": "Example Premier Division"
      },
      "name": "Harbor FC vs Riverside United",
      "participants": [
        {
          "name": "Harbor FC",
          "role": "home"
        },
        {
          "name": "Riverside United",
          "role": "away"
        }
      ],
      "scheduled_start": "2026-10-24T14:00:00.000Z",
      "status": "live",
      "started_at": "2026-10-24T14:00:42.000Z",
      "ended_at": null,
      "end_reason": null,
      "resolved_at": null,
      "live": {
        "score": {
          "home": 1,
          "away": 0
        },
        "period": "1H",
        "clock": {
          "seconds": 1390,
          "running": true,
          "as_of": "2026-10-24T14:23:52.000Z"
        }
      },
      "updated_at": "2026-10-24T14:23:52.004Z",
      "version": 1792851832004001
    }
  ],
  "next_cursor": null
}

For a running clock, add elapsed time since clock.as_of to clock.seconds. Freeze it when running:false. Do not infer market availability from a running clock.

Get an event and its markets

Returns the event fields plus a markets array. Optional market_types and periods are comma-separated; every market type and period match are the defaults.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/events/ev_01KAZ000000000000000000002?market_types=1x2,total,handicap&periods=match"

{
  "id": "ev_01KAZ000000000000000000002",
  "sport": "football",
  "competition": {
    "id": "cp_01KAZ000000000000000000001",
    "name": "Example Premier Division"
  },
  "name": "Harbor FC vs Riverside United",
  "participants": [
    {
      "name": "Harbor FC",
      "role": "home"
    },
    {
      "name": "Riverside United",
      "role": "away"
    }
  ],
  "scheduled_start": "2026-10-24T14:00:00.000Z",
  "status": "live",
  "started_at": "2026-10-24T14:00:42.000Z",
  "ended_at": null,
  "end_reason": null,
  "resolved_at": null,
  "live": {
    "score": {
      "home": 1,
      "away": 0
    },
    "period": "1H",
    "clock": {
      "seconds": 1390,
      "running": true,
      "as_of": "2026-10-24T14:23:52.000Z"
    }
  },
  "updated_at": "2026-10-24T14:23:52.004Z",
  "version": 1792851832004001,
  "markets": [
    {
      "id": "mk_01KAZ000000000000000000003",
      "event_id": "ev_01KAZ000000000000000000002",
      "type": "1x2",
      "period": "match",
      "line": null,
      "status": "active",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC"
        },
        {
          "key": "draw",
          "name": "Draw"
        },
        {
          "key": "away",
          "name": "Riverside United"
        }
      ],
      "price": {
        "state": "open",
        "reason": null,
        "outcomes": [
          {
            "key": "home",
            "prob": 0.62,
            "fair_odds": 1.613
          },
          {
            "key": "draw",
            "prob": 0.23,
            "fair_odds": 4.348
          },
          {
            "key": "away",
            "prob": 0.15,
            "fair_odds": 6.667
          }
        ],
        "uncertainty": 0.008,
        "ts": "2026-10-24T14:23:52.004Z"
      },
      "result": null
    },
    {
      "id": "mk_01KAZ000000000000000000004",
      "event_id": "ev_01KAZ000000000000000000002",
      "type": "total",
      "period": "match",
      "line": 2.5,
      "status": "active",
      "outcomes": [
        {
          "key": "over",
          "name": "Over 2.5"
        },
        {
          "key": "under",
          "name": "Under 2.5"
        }
      ],
      "price": {
        "state": "open",
        "reason": null,
        "outcomes": [
          {
            "key": "over",
            "prob": 0.58,
            "fair_odds": 1.724
          },
          {
            "key": "under",
            "prob": 0.42,
            "fair_odds": 2.381
          }
        ],
        "uncertainty": 0.008,
        "ts": "2026-10-24T14:23:52.004Z"
      },
      "result": null
    },
    {
      "id": "mk_01KAZ000000000000000000005",
      "event_id": "ev_01KAZ000000000000000000002",
      "type": "handicap",
      "period": "match",
      "line": -1.5,
      "status": "active",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC (-1.5)"
        },
        {
          "key": "away",
          "name": "Riverside United (+1.5)"
        }
      ],
      "price": {
        "state": "open",
        "reason": null,
        "outcomes": [
          {
            "key": "home",
            "prob": 0.37,
            "fair_odds": 2.703
          },
          {
            "key": "away",
            "prob": 0.63,
            "fair_odds": 1.587
          }
        ],
        "uncertainty": 0.008,
        "ts": "2026-10-24T14:23:52.004Z"
      },
      "result": null
    }
  ]
}

Get one market

Returns a market with a nested price and nullable result. This shape differs from the flat PriceRow used by /v1/prices and AMQP.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/markets/mk_01KAZ000000000000000000004"

{
  "id": "mk_01KAZ000000000000000000004",
  "event_id": "ev_01KAZ000000000000000000002",
  "type": "total",
  "period": "match",
  "line": 2.5,
  "status": "active",
  "outcomes": [
    {
      "key": "over",
      "name": "Over 2.5"
    },
    {
      "key": "under",
      "name": "Under 2.5"
    }
  ],
  "price": {
    "state": "open",
    "reason": null,
    "outcomes": [
      {
        "key": "over",
        "prob": 0.58,
        "fair_odds": 1.724
      },
      {
        "key": "under",
        "prob": 0.42,
        "fair_odds": 2.381
      }
    ],
    "uncertainty": 0.008,
    "ts": "2026-10-24T14:23:52.004Z"
  },
  "result": null
}

Pagination and catalogue synchronization

1. Request the first page with your filters and limit (default 100; capped at 500).
2. Process data. If next_cursor is not null, pass it as cursor with exactly the same filters.
3. Continue until next_cursor:null. Tokens are opaque and valid for 10 minutes.

# jq extracts the token returned by your previous request.
NEXT_CURSOR=$(jq -r '.next_cursor // empty' competitions-page.json)
if [ -n "$NEXT_CURSOR" ]; then
  curl --silent --show-error --fail-with-body --compressed --get \
    --cacert "$FEED_API_CA_FILE" \
    --header "Authorization: Bearer $FEED_API_KEY" \
    --data-urlencode 'sport=football' \
    --data-urlencode 'limit=100' \
    --data-urlencode "cursor=$NEXT_CURSOR" \
    "$FEED_API_URL/v1/competitions"
fi

Save the first competitions response as competitions-page.json before running this continuation example. For event synchronization, use updated_since, read every page and merge by event ID/version. Avoid restricting it to scheduled,live when you need ended or cancelled events.

Final events older than 7 days with all markets settled, or ended/final events older than 30 days, may no longer be served. Their event and market detail endpoints can return 404. Keep the results your application needs.

Sports and market catalogue

Supported market types and their interpretation. Actual event and competition availability comes from the catalogue endpoints.

Supported sports

For tennis, NBA and NHL, every market is suspended with reason match_event from confirmed play or the scheduled start, whichever comes first. Event statuses and results continue. A sport enum appearing in a schema is not a promise that the sport is available.

Competition availability

Use GET /v1/competitions?sport=football for the competitions currently listed. Store the returned ID and name; bind by ID. A fixed league-name list cannot tell you which competitions have events today.

Tennis is grouped under men’s and women’s competitions; do not assume coverage is limited to a particular tour. NBA and NHL are the supported basketball and ice hockey leagues. A listed competition does not imply that every fixture, market type or line is currently available.

Football competition examples

The released coverage includes the competitions below. This is not an exhaustive list or a live availability report; discover current competition IDs through the API.

Market types and outcomes

The only period in this release is match. Total and handicap lines are whole numbers plus 0.5; no supported line can push. Discover lines from returned markets rather than constructing IDs from type and line.

Market status versus price state

Event statuses

live is not evidence that a price is usable. Always check the consumer gate, market status and price state.

Price snapshots and polling

Each price row contains one market, its event, named outcomes, its current price and its result. A row is a complete replacement, not a partial patch.

Get current prices

Without since, the response contains markets that are not removed for scheduled or live events. It is not paginated. Optional filters: sport, competition, event, market_types, periods. Fields combine with AND; comma-separated values combine with OR.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/prices?sport=football"

{
  "since": "illustrative-opaque-token",
  "version": 1792851832004001,
  "full": true,
  "data": [
    {
      "market_id": "mk_01KAZ000000000000000000003",
      "market": {
        "type": "1x2",
        "period": "match",
        "line": null,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC",
          "prob": 0.62,
          "fair_odds": 1.613
        },
        {
          "key": "draw",
          "name": "Draw",
          "prob": 0.23,
          "fair_odds": 4.348
        },
        {
          "key": "away",
          "name": "Riverside United",
          "prob": 0.15,
          "fair_odds": 6.667
        }
      ],
      "result": null,
      "version": 1792851832004001
    },
    {
      "market_id": "mk_01KAZ000000000000000000004",
      "market": {
        "type": "total",
        "period": "match",
        "line": 2.5,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "over",
          "name": "Over 2.5",
          "prob": 0.58,
          "fair_odds": 1.724
        },
        {
          "key": "under",
          "name": "Under 2.5",
          "prob": 0.42,
          "fair_odds": 2.381
        }
      ],
      "result": null,
      "version": 1792851832004001
    },
    {
      "market_id": "mk_01KAZ000000000000000000005",
      "market": {
        "type": "handicap",
        "period": "match",
        "line": -1.5,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC (-1.5)",
          "prob": 0.37,
          "fair_odds": 2.703
        },
        {
          "key": "away",
          "name": "Riverside United (+1.5)",
          "prob": 0.63,
          "fair_odds": 1.587
        }
      ],
      "result": null,
      "version": 1792851832004001
    }
  ]
}

The example since value is a placeholder. Use the token returned by your own request.

PriceRow fields

In the example, prob:0.58 is a 58% probability and fair_odds:1.724 is its reciprocal after rounding. Use state and the consumer’s freshness gate before using either value.

Poll changes with since

# Save the first /v1/prices?sport=football response as prices.json.
SINCE=$(jq -r '.since' prices.json)
curl --silent --show-error --fail-with-body --compressed --get \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  --data-urlencode 'sport=football' \
  --data-urlencode "since=$SINCE" \
  "$FEED_API_URL/v1/prices"

{
  "since": "illustrative-next-opaque-token",
  "version": 1792851844000001,
  "full": false,
  "data": [
    {
      "market_id": "mk_01KAZ000000000000000000004",
      "market": {
        "type": "total",
        "period": "match",
        "line": 2.5,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "suspended",
      "reason": "match_event",
      "uncertainty": null,
      "ts": "2026-10-24T14:24:04.000Z",
      "outcomes": [
        {
          "key": "over",
          "name": "Over 2.5",
          "prob": null,
          "fair_odds": null
        },
        {
          "key": "under",
          "name": "Under 2.5",
          "prob": null,
          "fair_odds": null
        }
      ],
      "result": null,
      "version": 1792851844000001
    }
  ]
}

A valid token lasts 10 minutes by default and belongs to its original filters. After expiry, filter changes or a service restart, expect a full replacement. A malformed token is rejected with 400. A valid delta can also become a full response when more than half of the current rows changed.

Rows missing from a full replacement may have ended or been removed. Fetch known market IDs when reconciling results. Changes that move a row outside your filters are not guaranteed to appear in REST deltas; refresh the full view to remove them.

Suspension and caution reasons

unstable and low_confidence can be caution or suspended. Suspended rows have null probabilities, fair odds and uncertainty. The reference consumer may additionally use the local reason disconnected; that is not a server reason.

{
  "market_id": "mk_01KAZ000000000000000000004",
  "market": {
    "type": "total",
    "period": "match",
    "line": 2.5,
    "status": "active"
  },
  "event": {
    "id": "ev_01KAZ000000000000000000002",
    "name": "Harbor FC vs Riverside United",
    "sport": "football",
    "competition_id": "cp_01KAZ000000000000000000001",
    "competition": "Example Premier Division",
    "status": "live",
    "scheduled_start": "2026-10-24T14:00:00.000Z"
  },
  "state": "suspended",
  "reason": "match_event",
  "uncertainty": null,
  "ts": "2026-10-24T14:24:04.000Z",
  "outcomes": [
    {
      "key": "over",
      "name": "Over 2.5",
      "prob": null,
      "fair_odds": null
    },
    {
      "key": "under",
      "name": "Under 2.5",
      "prob": null,
      "fair_odds": null
    }
  ],
  "result": null,
  "version": 1792851844000001
}

Polling limits

Every poll counts against the key’s REST request budget. A response over 2,000 rows is a large answer: at most one per key per 10 seconds by default. Respect Retry-After on 429 and 503, retaining your current since for the retry. Use streaming delivery when frequent large responses prevent the required update rate.

RabbitMQ connection and bindings

Connect with AMQP 0-9-1 over TLS, consume the assigned queues, then join an HTTPS snapshot before exposing prices.

Queues and exchanges

Queues are c_<client>.prices.<n> and c_<client>.results.<n>. Open separate channels for prices and results. Set the AMQP connection heartbeat to 10 seconds and results prefetch between 1 and 1,000.

The operator creates exchanges and durable queues. Do not declare, delete or purge them, and do not change result bindings. Every queue has one active consumer; an additional consumer is standby. Use an independently assigned queue set for each independent price view.

Routing keys and supported bindings

Price, event and result routing keys have the form <sport>.<competition_id>.<event_id>. Only the four binding shapes below are supported for your prices queue.

Replace cp_ID / ev_ID with discovered IDs. Multiple bindings select their union. Bind the same selection to feed.events when event objects are needed.

# Football prices plus one specific event; event ID is illustrative.
export FEED_BINDINGS='football.#,*.*.ev_01KAZ000000000000000000002'
export FEED_EVENTS='1'

There is no routing-key component for market type or line. If your application only needs totals, filter complete market rows locally. The join must still match the queue’s selection.

HTTPS join endpoint

Requires an AMQP-enabled API key, JSON content type and Accept-Encoding:gzip. The filter array is a union: separate filter objects combine with OR; fields within one filter combine with AND. Empty filter {} selects everything.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept-Encoding: gzip' \
  --data '{"filters":[{"sports":["football"]}]}' \
  "$FEED_API_URL/v1/prices/join"

{
  "version": 1792851832004001,
  "data": [
    {
      "market_id": "mk_01KAZ000000000000000000003",
      "market": {
        "type": "1x2",
        "period": "match",
        "line": null,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC",
          "prob": 0.62,
          "fair_odds": 1.613
        },
        {
          "key": "draw",
          "name": "Draw",
          "prob": 0.23,
          "fair_odds": 4.348
        },
        {
          "key": "away",
          "name": "Riverside United",
          "prob": 0.15,
          "fair_odds": 6.667
        }
      ],
      "result": null,
      "version": 1792851832004001
    },
    {
      "market_id": "mk_01KAZ000000000000000000004",
      "market": {
        "type": "total",
        "period": "match",
        "line": 2.5,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "over",
          "name": "Over 2.5",
          "prob": 0.58,
          "fair_odds": 1.724
        },
        {
          "key": "under",
          "name": "Under 2.5",
          "prob": 0.42,
          "fair_odds": 2.381
        }
      ],
      "result": null,
      "version": 1792851832004001
    },
    {
      "market_id": "mk_01KAZ000000000000000000005",
      "market": {
        "type": "handicap",
        "period": "match",
        "line": -1.5,
        "status": "active"
      },
      "event": {
        "id": "ev_01KAZ000000000000000000002",
        "name": "Harbor FC vs Riverside United",
        "sport": "football",
        "competition_id": "cp_01KAZ000000000000000000001",
        "competition": "Example Premier Division",
        "status": "live",
        "scheduled_start": "2026-10-24T14:00:00.000Z"
      },
      "state": "open",
      "reason": null,
      "uncertainty": 0.008,
      "ts": "2026-10-24T14:23:52.004Z",
      "outcomes": [
        {
          "key": "home",
          "name": "Harbor FC (-1.5)",
          "prob": 0.37,
          "fair_odds": 2.703
        },
        {
          "key": "away",
          "name": "Riverside United (+1.5)",
          "prob": 0.63,
          "fair_odds": 1.587
        }
      ],
      "result": null,
      "version": 1792851832004001
    }
  ]
}

The answer contains a snapshot version and complete rows in data. It is always gzip-compressed. There is no pagination, since or full flag. Calling this endpoint alone does not complete an AMQP join; follow the buffering procedure below.

Initial join procedure

1. Suspend the entire price view. Connect, open two channels, bind prices/events, start automatic-ACK consumption on prices and manual-ACK consumption on results.
2. Buffer prices and events in arrival order. Record the time each message is taken from the AMQP client library.
3. Wait for a fresh non-final heartbeat. It must be received within 3 seconds of sent_at. Record session and seq; discard buffered messages up to and including that heartbeat.
4. Fetch the join snapshot while continuing to buffer. Use the union of your binding filters. If you need event objects, read all event pages and retain matching events.
5. Install the snapshot, then replay buffered messages in order. Apply version and heartbeat checks. Only expose prices after replay completes without invalidating the join.

While the HTTPS join and event-page requests run, continue checking every heartbeat and the 3-second silence deadline. A changed session, sequence gap, final/stale heartbeat or silence invalidates the pending join; discard that attempt and restart from a fresh heartbeat.

A missing fresh heartbeat leaves a standby consumer suspended. If no heartbeat arrives within 10 seconds, back off and keep waiting. For join 429/503 responses, honor Retry-After; for network failure, a request over 30 seconds or another 5xx, retry with jittered 1–30 second backoff. After 60 seconds without a join answer, discard the buffer and start from a fresh heartbeat.

Changing the selection

Bindings persist in RabbitMQ. Suspend first, remove obsolete keys from both feed.prices and feed.events, reconnect, bind the new selection and join again. Set FEED_UNBIND to the obsolete keys when using the examples. Never purge a queue to change selection.

AMQP message reference

Raw broker bodies are UTF-8 JSON. The top-level type identifies the message. These examples show the broker payload, not the consumer’s diagnostic stdout.

price — full market row

Exchange: feed.prices. Body is a REST PriceRow plus "type":"price". Prices are current state; intermediate updates may be coalesced. Do not use this channel as a historical tick log.

{
  "type": "price",
  "market_id": "mk_01KAZ000000000000000000004",
  "market": {
    "type": "total",
    "period": "match",
    "line": 2.5,
    "status": "active"
  },
  "event": {
    "id": "ev_01KAZ000000000000000000002",
    "name": "Harbor FC vs Riverside United",
    "sport": "football",
    "competition_id": "cp_01KAZ000000000000000000001",
    "competition": "Example Premier Division",
    "status": "live",
    "scheduled_start": "2026-10-24T14:00:00.000Z"
  },
  "state": "open",
  "reason": null,
  "uncertainty": 0.008,
  "ts": "2026-10-24T14:23:52.004Z",
  "outcomes": [
    {
      "key": "over",
      "name": "Over 2.5",
      "prob": 0.58,
      "fair_odds": 1.724
    },
    {
      "key": "under",
      "name": "Under 2.5",
      "prob": 0.42,
      "fair_odds": 2.381
    }
  ],
  "result": null,
  "version": 1792851832004001
}

The outer type is the message type; market.type is the market type. Replace by market_id only when version is newer. See the field table for probability and state semantics.

event — full event object

Exchange: feed.events. Opt in by binding your prices queue to this exchange. Body is the catalogue Event plus "type":"event". This is where participants and football live score/clock are available.

{
  "type": "event",
  "id": "ev_01KAZ000000000000000000002",
  "sport": "football",
  "competition": {
    "id": "cp_01KAZ000000000000000000001",
    "name": "Example Premier Division"
  },
  "name": "Harbor FC vs Riverside United",
  "participants": [
    {
      "name": "Harbor FC",
      "role": "home"
    },
    {
      "name": "Riverside United",
      "role": "away"
    }
  ],
  "scheduled_start": "2026-10-24T14:00:00.000Z",
  "status": "live",
  "started_at": "2026-10-24T14:00:42.000Z",
  "ended_at": null,
  "end_reason": null,
  "resolved_at": null,
  "live": {
    "score": {
      "home": 1,
      "away": 0
    },
    "period": "1H",
    "clock": {
      "seconds": 1390,
      "running": true,
      "as_of": "2026-10-24T14:23:52.000Z"
    }
  },
  "updated_at": "2026-10-24T14:23:52.004Z",
  "version": 1792851832004001
}

Replace event objects by ID and version. Clock updates are not a per-second timer: an event update is sent when score, period or clock running state changes. Derive the display clock from seconds, running and as_of.

result — settlement or correction

Exchange: feed.results. Persistent delivery to your results queue. The body is a complete row plus "type":"result", including a non-null result. Results include every sport, irrespective of price bindings.

{
  "type": "result",
  "market_id": "mk_01KAZ000000000000000000004",
  "market": {
    "type": "total",
    "period": "match",
    "line": 2.5,
    "status": "settled"
  },
  "event": {
    "id": "ev_01KAZ000000000000000000002",
    "name": "Harbor FC vs Riverside United",
    "sport": "football",
    "competition_id": "cp_01KAZ000000000000000000001",
    "competition": "Example Premier Division",
    "status": "resolved",
    "scheduled_start": "2026-10-24T14:00:00.000Z"
  },
  "state": "suspended",
  "reason": "event_not_active",
  "uncertainty": null,
  "ts": "2026-10-24T16:02:10.441Z",
  "outcomes": [
    {
      "key": "over",
      "name": "Over 2.5",
      "prob": null,
      "fair_odds": null
    },
    {
      "key": "under",
      "name": "Under 2.5",
      "prob": null,
      "fair_odds": null
    }
  ],
  "result": {
    "winner": "over",
    "void": false,
    "revision": 1,
    "resolved_at": "2026-10-24T16:02:10.441Z"
  },
  "version": 1792857730441001
}

Redelivery is expected. Apply only a newer row version, persist it, then ACK. result.revision starts at 1 and increases for a correction. Details are in Results and settlement.

heartbeat — feed freshness

Exchange: feed.heartbeat. Fanout, empty routing key, already bound to the prices queue. The feed normally sends one each second.

{
  "type": "heartbeat",
  "session": "s_01KAZ000000000000000000006",
  "seq": 42,
  "sent_at": "2026-10-24T14:23:53.000Z",
  "as_of": "2026-10-24T14:23:52.900Z",
  "final": false
}

Suspended price example

Outcome keys/names remain present, but every probability and fair-odds value is null. Do not substitute the last open price.

{
  "type": "price",
  "market_id": "mk_01KAZ000000000000000000004",
  "market": {
    "type": "total",
    "period": "match",
    "line": 2.5,
    "status": "active"
  },
  "event": {
    "id": "ev_01KAZ000000000000000000002",
    "name": "Harbor FC vs Riverside United",
    "sport": "football",
    "competition_id": "cp_01KAZ000000000000000000001",
    "competition": "Example Premier Division",
    "status": "live",
    "scheduled_start": "2026-10-24T14:00:00.000Z"
  },
  "state": "suspended",
  "reason": "match_event",
  "uncertainty": null,
  "ts": "2026-10-24T14:24:04.000Z",
  "outcomes": [
    {
      "key": "over",
      "name": "Over 2.5",
      "prob": null,
      "fair_odds": null
    },
    {
      "key": "under",
      "name": "Under 2.5",
      "prob": null,
      "fair_odds": null
    }
  ],
  "result": null,
  "version": 1792851844000001
}

Versions, freshness and recovery

Maintain a separate local joined state. The application must suspend all prices whenever that state becomes invalid, even if cached rows still say open.

Merging the snapshot and queue

For each market/event, retain its last version. An object absent from the join snapshot counts as having the snapshot version. Apply a later message only when its version is greater than both the stored version and any remembered event-removal version.

The small version numbers above are explanatory. Actual versions are larger integers. Do not use ts or arrival order to choose between two copies of an object.

When to suspend and rejoin

Judge buffered heartbeat age using the time your code received it, not the time you later replay it. Check for missed deadlines after a stalled event loop. Rows still arriving do not replace the heartbeat requirement.

The 3-second silence threshold is not an end-to-end 3-second freshness guarantee. The protocol’s combined worst-case bound is about 8.6 seconds under its clock/timing assumptions. Inspect the latest heartbeat’s as_of to assess the publication watermark.

Events moving into or out of a selection

Moves are sent under both old and new routing keys. Determine current membership from the payload’s sport, competition ID and event ID. If a newer row/event no longer matches your bindings, remove that event and its rows only when the move is newer than every stored object for the event.

Remember the removal version until the next join. This prevents an old queued message from restoring a removed event or a delayed move from deleting newer snapshot data. Perform the version check before deciding to remove anything.

Standby and restart behavior

Each queue permits one active consumer. A standby process can be connected with no deliveries; it must remain suspended. On takeover, it waits for a fresh heartbeat and performs its own join. A reconnect or heartbeat alone does not reopen the price gate.

Keep each process’s result journal separate. Restarting the example reloads durable result versions so duplicate delivery does not apply the same settlement twice.

Results and settlement

Persist results independently of the price view. Ended events can still be waiting for settlement, and a published result can later be corrected.

Result object

{
  "winner": "over",
  "void": false,
  "revision": 1,
  "resolved_at": "2026-10-24T16:02:10.441Z"
}

A correction can replace a winner or void the market. The next example is an alternative later correction to the same market; it must arrive in a row with a newer version.

{
  "winner": null,
  "void": true,
  "revision": 2,
  "resolved_at": "2026-10-24T16:10:00.000Z"
}

Durable storage before acknowledgment

1. Validate the result message and identify market_id and version.
2. If the version is newer, commit the result and its version to durable storage together. Make any downstream settlement update idempotent.
3. Only after that commit succeeds, ACK the RabbitMQ delivery. A duplicate/older delivery can be acknowledged once a newer or identical result is already durably stored.
4. On a write failure, leave the delivery unacknowledged and stop or recover the consumer. Do not acknowledge malformed results as successfully stored.

Use a separate results channel with prefetch at most 1,000. Process results even while prices are suspended, and even when the result’s sport/event does not match your price bindings.

Reconcile missed results over REST

The result queue has a seven-day TTL and size bounds; it is not permanent storage. After a longer outage or suspected loss, list events updated since your last durable checkpoint, read all pages, then request each event’s detail to obtain market results. Do not add a scheduled/live-only status filter.

curl --silent --show-error --fail-with-body --compressed \
  --cacert "$FEED_API_CA_FILE" \
  --header "Authorization: Bearer $FEED_API_KEY" \
  "$FEED_API_URL/v1/events?updated_since=2026-10-21T00%3A00%3A00.000Z&limit=100"

Replace that timestamp with your checkpoint. For a known market ID, use GET /v1/markets/{market_id}. REST market objects carry result revisions; AMQP rows carry row versions as well. Compare like identifiers rather than inventing a row version from a revision.

REST retention is also finite: final events may disappear after 7 days once all markets are settled, and ended/final events may disappear after 30 days. If a required event is no longer available, contact the operator; the API cannot provide an unlimited archive.

Settlement rules by sport

Postponement and resumption: the reference start is the scheduled start as it stood 24 hours before kickoff, or when first listed if later. A postponed match retains its markets if it starts within 48 hours of that reference; otherwise it is cancelled and void. An interrupted match must resume and finish within the same 48-hour window, or all markets are void.

Do not settle a market yourself from the live score. Wait for the published result; an event can be ended before every market is resolved.

Limits and errors

Use HTTP status codes and RabbitMQ close reasons to choose a recovery action. Include the HTTP X-Request-Id when reporting an API failure.

HTTP error format

{
  "error": {
    "code": "not_found",
    "message": "Event not found",
    "request_id": "req_example01"
  }
}

error.request_id matches the X-Request-Id response header. Keyed REST requests provide RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Joins have a separate budget.

RabbitMQ refusals and closes

Delivery and request limits

Queue overflow drops oldest messages. Recovery depends on heartbeat checks and a fresh snapshot; durable results still require your own storage. Queue and publication values above describe the configured limits. Account limits may be changed by the operator.

Empty or suspended data

Empty catalogue/join: a filter can validly match nothing. Check current /v1/sports and /v1/competitions, then inspect your binding IDs. Repeated joins: check clock synchronization, slow processing, missed heartbeat sequences and duplicate consumers. Journal startup failure: preserve the file and reconcile it; do not delete it to force startup.

Integration testing

Run the disposable broker scenarios before testing an assigned production connection. The local harness uses synthetic data and its own credentials.

Local broker scenarios

# Run from the extracted sport-feed-examples directory on Linux with Docker.
bash examples/amqp/test.sh python
bash examples/amqp/test.sh java
# Or run both:
bash examples/amqp/test.sh all

The harness creates and removes its own RabbitMQ container with no published ports. Allow about 1 GiB for the image/tools and several minutes per language. It does not use your production account.

Checks for your application

• Discover an actual competition/event ID and verify its market/outcome mapping.
• Complete a join; compare a known event’s current market rows with REST.
• Disconnect the consumer and verify every application price read is suspended.
• Reconnect and verify prices stay suspended until snapshot replay completes.
• Deliver a duplicate result and confirm it does not settle the market twice.
• Deliver a newer correction and confirm the persisted result changes once.
• Fail the durable result write and verify the message is not acknowledged.
• Change bindings and verify obsolete events disappear without a queue purge.

Checkboxes are local review notes; they are not evidence of an executed test.

Run restart, duplicate delivery and write-failure tests against the disposable broker. On the assigned connection, verify credentials, catalogue access, a normal join and expected updates.

Schemas and client examples

Machine-readable contracts, sample payloads and client code for integration.

Download contracts

Contract revisions are recorded in the downloaded schemas. The HTTP path version is /v1.

Example payloads

Every JSON block has a download button. The files contain fictional data suitable for inspecting shapes and writing parser fixtures; they are not recordings of a live feed. Requesting the sample IDs will not find a real fixture.

Reference consumer code

Download all client examples, including the AMQP consumers, WebSocket libraries and local test fixtures.

WebSocket clients

The Python and JavaScript client libraries use WebSocket subscriptions, not RabbitMQ queues. Their snapshot and sequence rules are specified separately; do not apply the AMQP join procedure to a WebSocket connection.

Using this guide

This is a review copy and contains no account credentials. Schemas, example payloads and client code can be downloaded from the links above.