# Line-move alerts and webhooks
Source: https://docs.oddswire.io/alerts

Native-price rules, current access, signed at-least-once delivery and receiver deduplication.

Alerts are a local private pilot. Owner/admin sessions configure targets/rules and inspect delivery logs. API keys and viewers cannot manage them. Control calls and outbound attempts are free, including at zero REST credits; no paid plan or external origin is enabled automatically.

## Create a target and rule

Use the account webhook-target and alert-rule endpoints in the reference. Each POST has a UUID `request_id`: retry identical content with the same ID, or receive 409 for conflicts. Target creation and rotation show a base64url signing secret **once**. A repeated response omits the secret; rotate explicitly if the first response was lost.

A rule binds to an active key ID owned by the account, explicit namespace/source, permanent `native_fixture_id` and exact `quote_key`. It requires current `alerts` and `odds` API grants, source/sport/family/beta access, plus a separate expiring account/source/region **alerts-purpose** review. Ordinary REST, history/export or paid access does not establish outbound rights. Working-source customer webhook rights remain unresolved.

Rules start at the current head without historical backfill. `threshold_bps` (1–10000) measures the **absolute change in gross probability**, not a relative odds percentage. `within_seconds` (1–3600) bounds the gap from the prior price's last recorded confirmation to the new observation. Direction `up|down|either` refers to probability; decimal 2.00→4.00 is −2500 bps. Comparisons are exact rational math; reported changes are strings with eight decimal places.

This watches adjacent observations of one native offer/outcome/side/depth. Unchanged confirmations refresh the baseline without adding ticks. Tied-time A→B→A survives replay/restarts. Stale, suspended, unknown-liquidity, missing-baseline and changed-metadata evidence do not become alerts. There is no sharp, fair-price, arbitrage or rolling-high/low opportunity signal. Current reference coverage is insufficient for those products.

## Receive signed raw bytes

The POST includes `Oddswire-Signature: t=<unix-seconds>,v1=<hex HMAC-SHA256>`. The signed message is the ASCII timestamp, a period, then the **exact raw request body**. Verify before JSON parsing with a ±300-second tolerance:

```python theme={null}
from oddswire import verify_webhook_signature

valid = verify_webhook_signature(raw_body, signature_header, signing_secret)
```

```typescript theme={null}
import { verifyWebhookSignature } from "@oddswire/client";

const valid = await verifyWebhookSignature(
  rawBody,
  signatureHeader,
  signingSecret,
);
```

After verification, parse the body and persistently deduplicate its `id`, atomically with your work/enqueue, before returning 2xx. The payload includes method, rule/region/threshold/window, canonical before/after observations with native identity, detected time and expiry. It is historical movement evidence, not a confirmed executable price. Never use an unsigned delivery header alone as your deduplication authority.

## Retries, logs and withdrawal

Delivery is **at least once**: retries preserve exact body/event/delivery IDs with a fresh timestamp and attempt number. A lost ACK or expired worker lease can duplicate a request; recovery records unknown delivery rather than inventing success. Targets serialize queued events, including retry waits.

2xx acknowledges delivery. Network uncertainty, 408/425/429 and 5xx retry with bounded exponential backoff/Retry-After, at most six attempts. Other 4xx and redirects stop. Freshness/kickoff expiry can stop retries earlier. Current key, grants, purpose review, metadata and active/fresh quote are rechecked before sending. Revoking the bound key stops delivery even if a replacement key exists.

Disable a rule/target to cancel its remaining work. An already in-flight request can finish after withdrawal or key rotation. Coordinate rotation with receivers that may briefly see the old in-flight signing key. Failed/blocked/expired deliveries remain in logs; there is no automatic dead-letter replay.

Logs expose states, attempts, safe failure reasons, statuses and durations, without payloads, signing secrets or receiver bodies. API lists show the latest 100 entries and bounded transitions. Source gaps, metadata changes and a full backlog appear on the rule; durable cursors are retained for recovery.

## Destination limits

Targets require public HTTPS/443, no URL credentials/query/fragment, and an exact operator-configured origin. Delivery validates DNS addresses on every dial, pins a safe public IP, refuses redirects and ignores environment proxies. Loopback HTTP is reserved for disposable local tests. Creating a target sends no ping. Real destination configuration, source-use approval, production capacity/retention and Telegram/Discord adapters remain separate work.


# Authentication and accounts
Source: https://docs.oddswire.io/authentication

Keep data keys, management sessions, roles and product grants distinct.

## Data keys

Send exactly one `X-API-Key` header. Never place credentials in URLs, cookies or WebSocket subprotocol values. The API rejects conflicting credentials. Create, rotate or revoke keys through the [workspace](https://oddswire.io/app/keys) or account-session endpoints. Raw keys are shown once; stored keys are hashes. Rotation atomically replaces the old key. The account has a three-active-key cap.

Both clients require exactly one `api_key` / `apiKey` or `session_token` / `sessionToken`. Their generated methods enforce the operation's credential type before making a network request. They accept HTTPS origins and development HTTP loopback origins, reject credential-bearing base URLs, and never follow redirects.

## Management sessions

`Authorization: Bearer <session>` manages the account. Data keys cannot create keys, change roles, enroll identities or operate billing/beta controls. Owner/admin sessions manage keys; only an owner changes existing member roles. Beta administration requires a separate global operator. Authentication does not imply these roles.

Production Clerk login and verified signup are configured on the Oddswire workspace. A CLI-issued local session is development-only evidence. New provider identities get **zero** API and Terminal grants. Signup, checkout redirects and client plan/role claims do not grant access.

API and Terminal are separate product scopes under one account. The root account ledger is authoritative for current grants, suspension and quota. The beta also requires exact recipient/region binding and current source-use approvals. Revocation and expiry apply to data reads, 304 revalidation and streams.

## Account selection

Management operations accept `X-Oddswire-Account` where listed by the contract. This selects an account in which the signed-in user must already have membership. It never changes tenant authorization. Free account introspection is useful before making a metered request.

Billing is **test mode only** and requires explicit enrollment. The test prices are fixtures, not a commercial offer. Source customer-use rights, Stripe sandbox verification and launch terms remain separate gates.


# Contract status and changelog
Source: https://docs.oddswire.io/changelog

Implemented local surfaces and remaining deployment boundaries.

## 10 November 2026 · REST v1 local pilot

Generated REST reference, Markdown/LLM exports and Python/TypeScript clients now follow the existing OpenAPI contract. Account/key, atomic credit, WebSocket, test-billing and invite-only beta services are available for local validation. Stable generated operation names are used by both clients; Python uses snake\_case.

The current API remains `/v1`. Within this version, consumers should tolerate added optional response fields and new missing/error codes. A future incompatible change requires a new version and a reviewed migration/deprecation policy. No six-month deprecation SLA or production uptime claim is established by this local build.

Real Clerk login, source customer-use rights, provider sandbox billing, package registry releases, Mintlify hosting/domain and public API deployment remain open. Roadmap data-proof and independent reference/recovery gates continue separately.


# Prices, coverage and fair values
Source: https://docs.oddswire.io/data

Read source identity, units, freshness and explicit missing data correctly.

Every data request names a namespace. Bulk odds also requires a `fixture` or `competition` filter. Discover fixtures and sources inside that namespace; never join separate stores by coincident numeric IDs. `books` contains **source/region IDs**, not brand slugs. Kambi brands share a pricing group and do not become independent sharp references.

## Quote identity and units

Preserve `quote_key`, native fixture/offer/outcome IDs, source/region, side and depth. More than one native offer may exist on the same canonical line. Reviewed grouping/orientation is explicit; source-local identity is not a reviewed match. Market family, period, quarter line and settlement terms must be compatible before comparison.

`decimal_odds`, native probabilities and sizes are decimal **strings**. A probability is not decimal odds. A team's NO contract is not the opposing 1X2 outcome. Fees, commissions, liquidity and settlement metadata remain source-specific. Unknown/nonzero exchange fees and push/split payouts are unsupported in the fair service.

## Freshness and missing coverage

`source_ts` is nullable. `seen_ts` is observation time. `confirmed_ts` records the last successful confirmation; unchanged successful observations refresh it without another price tick. `sent_ts` only records delivery and cannot refresh source freshness.

Read quote eligibility/state and age against `freshness_limit_seconds`; distinguish active, suspended, unavailable and stale states. Read **all** `missing[]` entries, including when `data` is nonempty. They identify uncollected, denied, stale, blocked, incompatible or insufficient coverage. A response is never proof that every planned bookmaker or market is covered.

The read-only API does not collect new prices. Free account coverage describes available scope and retained freshness; it is not an uptime guarantee. Fixture discovery may return no data. Bounded retained history requires separate history/export grants; opening/closing and as-of eligibility remain pre-match-only. Production coverage guarantees remain unverified.

## Fair price

`GET /v1/fair` requires fixture and settlement rule as well as namespace. Use discovered market metadata. The service reevaluates current reviewed inputs, eligibility, feed groups and configured weights. It exposes sources/method/filters and explicit insufficiency rather than serving an expired calculation.

There is currently **no configured eligible sharp reference**, so the pilot consensus is insufficient. Diagnostic vectors are not consensus prices. A 200 insufficient result still costs one credit. Technical source access does not confer customer display, derived-use or redistribution rights.

## In-play availability

Real working collectors remain pre-match-only. P4-08 adds a synthetic local
regulation-1X2 capability with an explicit API `inplay` feature grant. Read
`inplay.mode` on source/coverage metadata and `fixture_phase` on quotes; a
`local_test_only` mode is not real provider coverage. See [in-play scope and
session recovery](/inplay) before requesting `status=live`.


# Errors, credits and pagination
Source: https://docs.oddswire.io/errors

Handle missing data, structured failures, conditional requests and bounded traversal.

Both clients return a result containing the HTTP status, parsed page, `not_modified` (Python) / `notModified` (TypeScript), and selected response headers. `APIError` exposes status, problem code, request ID, structured problem and safe headers. Configuration/transport/protocol failures raise `ClientError`. No client automatically retries, logs a key or includes a raw response body in a transport exception.

| Status | Action |
| - | - |
| 200 / 201 | Inspect `data`, `missing` and `meta`; do not infer complete coverage. |
| 304 | No body. Reuse only the representation matching your ETag and query; current access and freshness were revalidated. |
| 400 / 422 | Fix `invalid_params`; do not retry unchanged. |
| 401 / 403 | Check key/session, current roles, entitlements and beta source permissions. Signup is not a grant. |
| 402 | Included quota unavailable/exhausted. Read free account usage and reset metadata; overage stays off. |
| 409 | A cursor or mutation conflicts with current authority. Restart discovery explicitly or reconcile the existing request UUID. |
| 410 | A beta invitation has expired; request a new reviewed invitation. |
| 429 | Abuse window, separate from billable credits. Inspect `Retry-After`; retry only deliberately. |
| 503 / 504 | Data/control unavailable or deadline exceeded. Preserve the error and request ID; never substitute cached active prices. |

Transport timeouts or disconnects have an unknown delivery outcome. A completed data page may have been charged. Check free account usage by request ID where available; do not silently retry or create a fresh billing mutation UUID. Refunds and payment invoices are separate from API credit counters.

## Conditional requests

```python theme={null}
first = client.list_odds({"namespace": namespace, "fixture": str(fixture_id)})
etag = first.headers.get("etag")
if etag:
    again = client.list_odds({"namespace": namespace, "fixture": str(fixture_id), "If-None-Match": etag})
    if again.not_modified:
        quotes = first.data  # Only this matching representation.
```

```typescript theme={null}
const first = await client.listOdds({ namespace, fixture: String(fixtureId) });
const etag = first.headers.etag;
if (etag) {
  const again = await client.listOdds({
    namespace,
    fixture: String(fixtureId),
    "If-None-Match": etag,
  });
  if (again.notModified) console.log("Matching representation unchanged");
}
```

## Explicitly bounded pages

Use `meta.next_cursor` unchanged with the same filters. Cursors bind query, scope, namespace and semantic data. A 409 requires an explicit fresh traversal; the client never restarts it automatically. The helpers below stop at the requested bound, propagate errors, and detect cursor cycles. Each successful page costs one credit.

```python theme={null}
for page in client.pages("listOdds", {"namespace": namespace, "fixture": str(fixture_id)}, max_pages=3):
    print(page.data["missing"])
```

```typescript theme={null}
for await (const page of client.pages(
  "listOdds",
  { namespace, fixture: String(fixtureId) },
  3,
)) {
  console.log(page.status);
}
```

Only completed successful data deliveries consume a credit, including empty/insufficient pages. Errors, 304, account/control/coverage and WebSocket messages are free, including at zero quota. `X-Oddswire-Credits-*`, `X-Oddswire-Credit-Cost`, `X-Oddswire-Usage-State` and `X-Request-ID` are admission/delivery metadata; free usage introspection is the final account authority.


# Historical prices and exports
Source: https://docs.oddswire.io/history

Received-time ticks, recorded as-of evidence, explicit line cutoffs and complete bounded files.

History is a local private pilot. It requires an API `history` grant and a current account/source/region/purpose review. Exports additionally require `history_export` and a separate export review. REST/Pro/Terminal access, signup and source technical access do not establish these permissions. Historical/export customer-use rights for the working sources remain unresolved; no new paid plan or data licence is activated.

## Permanent native identity

Supply `namespace`, source/region `books`, and `native_fixture_id` (up to ten source-local canonical fixture IDs from mappings' `native_fixture_id`). These are distinct from upstream `source_fixture_id` strings and reviewed group IDs. History keeps original source/native offer/outcome/side/depth identities. Mapping corrections never rewrite a tick or imply that today's grouping was valid in the past.

## Ticks and coverage

`GET /v1/history/ticks` requires inclusive received-time `from` and exclusive `until` bounds, at most 31 days. Tied observations order by immutable ingestion sequence. Unchanged successful observations refresh the separate confirmation journal, not tick history. Preserve decimal/probability strings, nullable `source_ts`, original `seen_ts` and native units; replay never refreshes those clocks.

Every page includes a `history` manifest with the actual retained range, prospective confirmation range/gaps, source-wide pending/quarantined evidence and explicit missing reasons. The free `/v1/history/coverage` control exposes PG evidence ranges, with a separate flag indicating whether selected canonical sink observations were verified. A retained range is not continuous coverage or an audit of every historical sink row. Empty/legacy/missing periods are not backfilled or advertised as multi-year data.

The pilot materializes at most 2,000 ticks or 500 native slots and uses normal 1–100 row pages. Narrow the selection on 422. Cursors bind account/key/grants, filters and the complete retained snapshot; a 409 needs an explicit restart. They never silently skip newly accepted work.

## As-of and lines

`GET /v1/history/snapshot` requires a nonfuture `as_of`. It selects the last recorded confirmation at or before that time per permanent native key, with capture sequence breaking ties. Original price observation time remains distinct from confirmation time. Missing, stale-at-as-of, suspended, unavailable and source-gap evidence remain explicit; no older active quote replaces a later suspension.

`GET /v1/history/lines` also requires an explicit `scheduled_start`. Opening means the first eligible **recorded** pre-start confirmation, not the bookmaker's genuine market opening. Closing uses the established scheduled-start policy: the last confirmation strictly before the requested start, with matching recorded kickoff/state, freshness and liquidity checks. A requested start not yet reached at `as_of` is `not_final`. Unknown legacy confirmations and incompatible/missing evidence do not produce a closing value.

All these results are historical evidence, not executable prices or a settlement/fee compatibility approval. Freshness limits are the current reviewed source policy used to evaluate the requested historical cutoff.

## Complete CSV and Parquet files

`GET /v1/history/export` uses `kind=ticks|snapshot|lines`, the corresponding time parameters, and `format=csv|parquet`. It exports the **whole bounded selection**, with no `limit` or `cursor`. Files are capped at 2 MiB; larger selections fail explicitly rather than truncating. A manifest row carries coverage/query metadata even for an empty selection. Parquet also embeds it in footer metadata.

Canonical decimals remain UTF-8 strings; IDs and nulls retain their meaning. Nested canonical/native fields live losslessly in `record_json`; arbitrary native text is not placed in spreadsheet formula cells. CSV empty decimal cells represent null; Parquet has nullable string columns. Parse IDs/sequences as integers or strings rather than through spreadsheet floating-point inference.

Both local clients return export bytes in the usual result's `data` field and safe content/disposition/digest headers. They never follow redirects or retry a charged download automatically. One completed successful history page or complete file costs one included credit, even when empty. Coverage, errors and 304 remain free; overage stays off. Rights and current access are rechecked before data/304 and after a download reservation.


# Build with Oddswire
Source: https://docs.oddswire.io/index

Explore the Oddswire sports odds API, including authentication, football fixtures, REST odds, WebSocket updates, and historical prices.

One odds engine, explicit source coverage, predictable API behavior.

Start with a [cURL](/quickstart-curl), [Python](/quickstart-python) or [TypeScript](/quickstart-typescript) quick start. Read the [REST reference](/reference/listOdds) when you need exact parameters.

## Before the first request

Oddswire is a **private pilot**. The customer workspace uses production Clerk login at `https://oddswire.io/app`; signup creates a workspace with zero data grants. The deployed API at `https://api.oddswire.io` requires separately reviewed access. Local quick starts still target `http://127.0.0.1:9113` and install clients from a private product checkout; packages are not published to registries. This public documentation repository does not contain the engine or SDK source.

1. Sign in to the [workspace](https://oddswire.io/app) and complete [invite-only onboarding](https://oddswire.io/beta). Production Clerk login is configured. CLI-issued sessions remain development-only access.
2. Review current API entitlements and [coverage](https://oddswire.io/app/coverage). New identities start with zero grants. Technical source access does not establish customer display or redistribution rights.
3. Create an account-owned key in [API keys](https://oddswire.io/app/keys). Copy it once into a private environment variable. API keys belong in headers.
4. Run one example. Successful data pages consume credits, including empty or insufficient results. Account/control calls and errors are free.

## Contracts and local clients

* [OpenAPI 3.1.2](/openapi.json): REST requests, parameters, response schemas and account controls.
* [AsyncAPI](/asyncapi.json) and [WebSocket wire schema](/websocket.schema.json): the separate streaming protocol.
* [Authentication](/authentication), [data and coverage](/data), [errors and credits](/errors), [streaming](/websocket).
* Every guide has a `.md` representation. Machine-readable indexes: [/llms.txt](https://docs.oddswire.io/llms.txt) and [/llms-full.txt](https://docs.oddswire.io/llms-full.txt).

The documentation exposes technical contracts without collecting your credentials. Use the authenticated [playground](https://oddswire.io/app/playground) for requests. [Historical prices and closing lines](/history) require separate grants and source-use review. Fair-price consensus currently has no configured eligible sharp reference.


# In-play scope and recovery
Source: https://docs.oddswire.io/inplay

Distinguish local lifecycle validation from real source coverage.

**Current working collectors are pre-match-only.** P4-08 verifies a synthetic local
BetRivers PA regulation-1X2 continuation. It does not establish native in-play
access, polling permission, latency, source rights or production availability.

Read `inplay.mode` on source discovery and account coverage: `pre_match_only` is
the default; `local_test_only` explicitly identifies the owned test capability.
Quotes include `fixture_phase` and, for that capability, `inplay` scope metadata.
No customer account or paid plan receives automatic in-play access.

A `status=live` scope needs a separate API `inplay` feature grant, plus the ordinary
source/family/namespace and odds grants. Streaming additionally requires
`websocket`. Default odds omit unentitled live quotes with explicit missing
reasons. Terminal access is separate.

A native start signal changes fixture phase; the clock reaching kickoff cannot
invent it. Suspension is a price state, separate from fixture phase. Disconnected,
stale, missing-snapshot, expired-review and ended states cannot be active prices.
`include_inactive=true` shows supported retained states and reasons.

After a source session gap, old quotes remain unavailable until a complete fresh
snapshot is accepted. Lifecycle/session metadata changes require clearing the
WebSocket view and subscribing again. Ordinary price changes use the existing
ordered snapshot/delta and cursor protocol. Delivery time, heartbeats and replay
never refresh source confirmation time. Read [WebSocket recovery](/websocket)
and [freshness and missing data](/data).

The local test uses a five-second quote-age limit. This is a test policy, not a
provider rate or latency promise. Fair calculations and historical opening/closing
and as-of eligibility remain pre-match-only. No scores, game timer, results or
settlement feed is included.


# Local read-only MCP
Source: https://docs.oddswire.io/mcp-client

Use bounded stdio tools through your existing API key and grants.

The local server uses the official MCP TypeScript SDK over stdio. It exposes twelve
read-only tools through the existing REST contract: account coverage/usage, sports,
sources, markets, fixtures, odds, fair price, history coverage, ticks, snapshots
and opening/closing lines. There is no hosted endpoint or OAuth bridge in this slice.

## Configure a local host

From the checkout, install locked MCP dependencies and compile:

```sh theme={null}
./scripts/node.sh --npm ci --prefix mcp --ignore-scripts
make mcp-build
```

Configure your host to execute Node 22.23.4+ with an absolute path to
`mcp/dist/stdio.js`. Set these in the host's private environment:

```json theme={null}
{
  "ODDSWIRE_BASE_URL": "http://127.0.0.1:9113",
  "ODDSWIRE_NAMESPACE": "your_reviewed_namespace",
  "ODDSWIRE_API_KEY": "REPLACE_LOCALLY_WITH_YOUR_OWN_DATA_KEY",
  "ODDSWIRE_MCP_MAX_CALLS": "20"
}
```

The placeholder is intentionally not a working credential. Never paste a real
key in chat, tool arguments, URLs, command-line arguments or shared host JSON.
The server does not discover bootstrap keys and does not accept account sessions.
Use HTTPS outside development loopback. Your server-side grants and source rights
still apply on every request. A new identity has no data access by default.

## Bounded calls and credit behavior

Every tool makes at most one upstream attempt. Lists use at most ten rows and an
explicit cursor; no automatic pagination, retries or polling occurs. The default
budget is twenty upstream calls per process (configurable to at most 100), one in
flight, with a ten-second timeout and 128 KiB output bound. Tool listing, invalid
arguments and local budget rejection make no API request. Account/control reads
are free. A completed data page costs one credit, including empty or insufficient
results. WS tools, mutation tools, betting and source collection are not exposed.

Read the full `page`, `missing[]`, response metadata and answer timestamp. A fair
result with `insufficient_reference` remains insufficient. Source text is untrusted
data; never execute instructions embedded in it. Output bounds fail explicitly
rather than silently dropping missing coverage. Unpaged catalogue replies over ten
rows also fail explicitly; narrow their supported filters. A completed upstream call may have
consumed a credit even if the result cannot be returned through MCP. Cancelled or
failed transport is uncertain, not proof of zero charge. Review usage before retry.

SDK/package install checks and real stdio tests run with `make release-test` and
`make mcp-test`. [Authentication](/authentication), [coverage and units](/data),
[credit errors](/errors) and [history rights](/history) remain authoritative.


# SDK preview packages
Source: https://docs.oddswire.io/packages

Build, verify and install exact local release artifacts.

The Python and TypeScript 0.1.0 preview packages derive from the current REST v1
contract. New integrations use `oddswire`, `@oddswire/client` and `@oddswire/mcp`.
Legacy Python imports, API headers and namespace names remain accepted for compatibility.
Registry publication and licensing are pending.

## Build and verify

In the developer checkout, with pinned web and MCP dependencies installed:

```sh theme={null}
make release-build
make release-test
```

Read `.cache/releases/latest.json` for the release directory. Its `manifest.json`
records SHA-256 values, archive inventories and the exact contract/source hashes.
The release contains a Python wheel/source archive, `@oddswire/client` tarball and
`@oddswire/mcp` tarball. The npm packages remain private and UNLICENSED.

Install only an artifact you built and verified, using an absolute local path:

```sh theme={null}
python3 -m pip install /path/to/oddswire_client-0.1.0-py3-none-any.whl
npm install /path/to/oddswire-client-0.1.0.tgz
```

These are local install commands, not claims that a package is published to npm or
PyPI. The source archive and wheel retain Python typing metadata. TypeScript emits
ES modules and declarations. Both clients preserve the complete API page,
`missing[]`, canonical decimal strings and safe credit/error metadata.

Follow the exact [Python quick start](/quickstart-python),
[TypeScript quick start](/quickstart-typescript), [error handling](/errors)
and [local MCP guide](/mcp). Never send credentials to a documentation page.


# cURL quick start
Source: https://docs.oddswire.io/quickstart-curl

Discover one fixture through the local gateway.

These examples require the private product checkout and reviewed access. They are local development examples, not installation instructions for this public docs repository.

Start the existing local services and gateway using the repository setup instructions. Create an account-owned key in the [workspace](https://oddswire.io/app/keys), set `ODDSWIRE_API_KEY` privately, and choose an entitled `ODDSWIRE_NAMESPACE`. Run `sh examples/quickstart.sh` from the checkout. This example needs cURL 7.76+ and deliberately accepts only the HTTP 127.0.0.1 origin.

```sh theme={null}
#!/bin/sh
set -eu
# Set ODDSWIRE_API_KEY privately. Never put a key in a URL or enable shell tracing.
: "${ODDSWIRE_API_KEY:?Set ODDSWIRE_API_KEY}"
: "${ODDSWIRE_NAMESPACE:?Choose an entitled namespace}"
base="${ODDSWIRE_BASE_URL:-http://127.0.0.1:9113}"
# Local-only example: do not change the origin without reviewing credential handling.
case "$base" in
  http://127.0.0.1:*) port="${base##*:}"; case "$port" in ""|*[!0-9]*) echo 'Invalid local port' >&2; exit 1;; esac ;;
  *) echo 'This cURL example requires the local gateway.' >&2; exit 1;;
esac
# Header configuration goes over stdin, not the process argument list.
case "$ODDSWIRE_API_KEY" in *[!A-Za-z0-9_-]*) echo 'Invalid example key format' >&2; exit 1;; esac
printf 'header = "X-API-Key: %s"\n' "$ODDSWIRE_API_KEY" |
  curl --config - --silent --show-error --fail-with-body --max-time 10 \
    --get "$base/v1/fixtures" --data-urlencode "namespace=$ODDSWIRE_NAMESPACE" --data-urlencode 'limit=1'
```

A successful fixture page costs one credit, even when empty. Errors return a nonzero cURL exit status and a structured problem body. The script has no automatic retries or redirect following. Use `/v1/account/entitlements` for free access introspection; use the returned fixture ID in `/v1/odds?namespace=...&fixture=...`. [Exact odds parameters](/reference/listOdds).


# Python quick start
Source: https://docs.oddswire.io/quickstart-python

A dependency-free Python 3.9+ client, installed from the checkout.

These examples require the private product checkout and reviewed access. They are local development examples, not installation instructions for this public docs repository.

Run from the repository root. These packages are local pilot builds, not published registry packages.

```sh theme={null}
python3 -m pip install ./sdk/python
# Set ODDSWIRE_API_KEY privately; do not paste it into chat or commit it.
export ODDSWIRE_NAMESPACE='oddswire_kambi'
python3 examples/quickstart.py
```

Choose a namespace listed by `get_entitlements()`. The name above is an example, not an access grant. The example makes one free introspection and up to two metered data calls. Fixture IDs come from discovery; numeric IDs in separate namespaces are unrelated.

```python theme={null}
import os
from oddswire import APIError, Client

client = Client(base_url=os.environ.get("ODDSWIRE_BASE_URL", "http://127.0.0.1:9113"),
                api_key=os.environ["ODDSWIRE_API_KEY"])
try:
    access = client.get_entitlements()  # Free; does not grant access.
    namespace = os.environ["ODDSWIRE_NAMESPACE"]  # Choose an entitled namespace.
    fixtures = client.list_fixtures({"namespace": namespace, "limit": 1})
    print("Fixture coverage:", fixtures.data["missing"])
    if fixtures.data["data"]:
        fixture_id = fixtures.data["data"][0]["fixture"]["id"]
        odds = client.list_odds({"namespace": namespace, "fixture": str(fixture_id), "limit": 3})
        print("Price coverage:", odds.data["missing"])
        for quote in odds.data["data"]:
            # Inspect state, eligibility, confirmation age, units and settlement.
            print(quote["quote_key"], quote["delivery"]["price"]["observation"]["value"])
    else:
        print("No fixtures in the current scope.")
except APIError as error:
    print(error.status, error.code, error.request_id)
    raise SystemExit(1) from None
```

Odds, probabilities and sizes stay strings. Use `decimal.Decimal` for calculations. Inspect `missing`, state, confirmation age, settlement and native units before comparing prices. An empty response is a valid result. [Error handling and conditional requests](/errors) explains timeouts, credit exhaustion, 304 and pagination.


# TypeScript quick start
Source: https://docs.oddswire.io/quickstart-typescript

Generated REST types and a small fetch client for Node 22.23.4+.

These examples require the private product checkout and reviewed access. They are local development examples, not installation instructions for this public docs repository.

Build the local client from the repository root:

```sh theme={null}
./scripts/node.sh --npm ci --prefix web
make sdk-build
# In your own TypeScript app, use its absolute checkout path:
npm install /absolute/path/to/Oddswire/sdk/typescript
# Set ODDSWIRE_API_KEY privately, and choose an entitled namespace.
export ODDSWIRE_NAMESPACE='oddswire_kambi'
```

The client is a local `@oddswire/client` package. It has not been published to npm. Compile the following as part of your Node TypeScript application. The checked-in source is `examples/quickstart.ts`; local tests compile and run that exact file.

```typescript theme={null}
import { Client, APIError } from "@oddswire/client";

const client = new Client({baseUrl: process.env.ODDSWIRE_BASE_URL ?? "http://127.0.0.1:9113", apiKey: process.env.ODDSWIRE_API_KEY});
try {
  await client.getEntitlements(); // Free; does not grant access.
  const namespace = process.env.ODDSWIRE_NAMESPACE;
  if (!namespace) throw new Error("Choose an entitled ODDSWIRE_NAMESPACE.");
  const fixtures = await client.listFixtures({namespace, limit: 1});
  console.log("Fixture coverage:", fixtures.data!.missing);
  const fixture = fixtures.data!.data[0];
  if (fixture) {
    const odds = await client.listOdds({namespace, fixture: String(fixture.fixture.id), limit: 3});
    console.log("Price coverage:", odds.data!.missing);
    for (const quote of odds.data!.data) {
      // Inspect state, eligibility, confirmation age, units and settlement.
      console.log(quote.quote_key, quote.delivery.price.observation.value);
    }
  } else console.log("No fixtures in the current scope.");
} catch (error) {
  if (error instanceof APIError) console.error(error.status, error.code, error.requestId);
  else console.error("Local configuration or transport failure.");
  process.exitCode = 1;
}
```

One free introspection and up to two metered data calls. Decimal values stay strings; avoid `Number()` for price arithmetic. Responses include `missing[]`, request metadata and credit headers. API keys stay on the server; use the authenticated [playground](https://oddswire.io/app/playground) from a browser. [Errors and pagination](/errors).


# Accept beta
Source: https://docs.oddswire.io/reference/acceptBeta

POST /v1/account/beta/accept
Accept beta: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`POST /v1/account/beta/accept`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BetaAccept"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 410 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing cancel
Source: https://docs.oddswire.io/reference/billingCancel

POST /v1/account/billing/cancel
Billing cancel: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/cancel`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing change
Source: https://docs.oddswire.io/reference/billingChange

POST /v1/account/billing/change
Billing change: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/change`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing checkout
Source: https://docs.oddswire.io/reference/billingCheckout

POST /v1/account/billing/checkout
Billing checkout: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/checkout`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing portal
Source: https://docs.oddswire.io/reference/billingPortal

POST /v1/account/billing/portal
Billing portal: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/portal`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing reconcile
Source: https://docs.oddswire.io/reference/billingReconcile

POST /v1/account/billing/reconcile
Billing reconcile: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/reconcile`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Billing refund
Source: https://docs.oddswire.io/reference/billingRefund

POST /v1/account/billing/refund
Billing refund: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`POST /v1/account/billing/refund`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BillingActionInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Create alert rule
Source: https://docs.oddswire.io/reference/createAlertRule

POST /v1/account/alert-rules
Create alert rule: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`POST /v1/account/alert-rules`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/AlertRuleInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 201 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Create key
Source: https://docs.oddswire.io/reference/createKey

POST /v1/account/keys
Create key: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`POST /v1/account/keys`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/CreateKey"
}
```

## Responses

| Status | Meaning |
| - | - |
| 201 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Create webhook target
Source: https://docs.oddswire.io/reference/createWebhookTarget

POST /v1/account/webhook-targets
Create webhook target: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`POST /v1/account/webhook-targets`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/AlertTargetInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 201 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Disable alert rule
Source: https://docs.oddswire.io/reference/disableAlertRule

POST /v1/account/alert-rules/{rule_id}/disable
Disable alert rule: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`POST /v1/account/alert-rules/{rule_id}/disable`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `rule_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/AlertMutation"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Disable webhook target
Source: https://docs.oddswire.io/reference/disableWebhookTarget

POST /v1/account/webhook-targets/{target_id}/disable
Disable webhook target: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`POST /v1/account/webhook-targets/{target_id}/disable`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `target_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/AlertMutation"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# End local session
Source: https://docs.oddswire.io/reference/endLocalSession

DELETE /v1/auth/session
End local session: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`DELETE /v1/auth/session`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Enroll session
Source: https://docs.oddswire.io/reference/enrollSession

POST /v1/auth/session
Enroll session: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`POST /v1/auth/session`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Export history
Source: https://docs.oddswire.io/reference/exportHistory

GET /v1/history/export
Export history: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/export`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `from` | query | No | Inclusive received seen\_ts; required for ticks/coverage. |
| `until` | query | No | Exclusive received seen\_ts; required for ticks/coverage; maximum 31-day interval. |
| `as_of` | query | No | Inclusive recorded confirmation cutoff. Required for snapshots/lines, cannot be in the future. |
| `scheduled_start` | query | No | Explicit scheduled kickoff; closing uses strictly earlier confirmations. Required for lines. |
| `kind` | query | Yes | Entire bounded selection; no implicit paging or asynchronous job. |
| `format` | query | Yes | One complete bounded file; one credit after successful delivery. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Complete bounded CSV or Parquet file with embedded coverage manifest. Requires both history and history\_export plus current account/source/region/purpose reviews. One credit on completed successful delivery; errors and 304 free. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get account
Source: https://docs.oddswire.io/reference/getAccount

GET /v1/account
Get account: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/account`

## Authentication

`ApiKey` or `AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get account coverage
Source: https://docs.oddswire.io/reference/getAccountCoverage

GET /v1/account/coverage
Get account coverage: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/account/coverage`

## Authentication

`ApiKey` or `AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get beta
Source: https://docs.oddswire.io/reference/getBeta

GET /v1/account/beta
Get beta: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`GET /v1/account/beta`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get billing
Source: https://docs.oddswire.io/reference/getBilling

GET /v1/account/billing
Get billing: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Test-only billing; owner session required for mutations, owner/admin for reads. Fixed test catalogue; enrollment ceiling controls source access. Checkout returns do not activate grants. Retry unresolved mutations with the same request UUID. UTC credit cycles, no usage refill, overage off, no Terminal billing or data rights granted.

`GET /v1/account/billing`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get entitlements
Source: https://docs.oddswire.io/reference/getEntitlements

GET /v1/account/entitlements
Get entitlements: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/account/entitlements`

## Authentication

`ApiKey` or `AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get fair
Source: https://docs.oddswire.io/reference/getFair

GET /v1/fair
Get fair: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/fair`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `fixture` | query | Yes | One reviewed group fixture ID. |
| `markets` | query | No | Exactly one payout family; default 1x2. |
| `period` | query | No | Market period; unsupported payout periods yield insufficient\_reference. |
| `method` | query | No | Margin removal method. |
| `settlement_rule` | query | Yes | Exact target settlement identity; never inferred across brands. |
| `line_quarters` | query | No | Required for totals/AH; absent for 1x2. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get history coverage
Source: https://docs.oddswire.io/reference/getHistoryCoverage

GET /v1/history/coverage
Get history coverage: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/coverage`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `limit` | query | No | Page size 1..100; coverage remains present on every page. |
| `cursor` | query | No | Opaque whole-query fingerprint; restart explicitly after 409. |
| `from` | query | Yes | Inclusive received seen\_ts; required for ticks/coverage. |
| `until` | query | Yes | Exclusive received seen\_ts; required for ticks/coverage; maximum 31-day interval. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Free bounded PG evidence coverage, not a continuous-coverage or whole-sink audit. Explicit history grants/reviews required. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get history lines
Source: https://docs.oddswire.io/reference/getHistoryLines

GET /v1/history/lines
Get history lines: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/lines`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `limit` | query | No | Page size 1..100; coverage remains present on every page. |
| `cursor` | query | No | Opaque whole-query fingerprint; restart explicitly after 409. |
| `as_of` | query | Yes | Inclusive recorded confirmation cutoff. Required for snapshots/lines, cannot be in the future. |
| `scheduled_start` | query | Yes | Explicit scheduled kickoff; closing uses strictly earlier confirmations. Required for lines. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get history snapshot
Source: https://docs.oddswire.io/reference/getHistorySnapshot

GET /v1/history/snapshot
Get history snapshot: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/snapshot`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `limit` | query | No | Page size 1..100; coverage remains present on every page. |
| `cursor` | query | No | Opaque whole-query fingerprint; restart explicitly after 409. |
| `as_of` | query | Yes | Inclusive recorded confirmation cutoff. Required for snapshots/lines, cannot be in the future. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Get usage
Source: https://docs.oddswire.io/reference/getUsage

GET /v1/account/usage
Get usage: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/account/usage`

## Authentication

`ApiKey` or `AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Invite beta
Source: https://docs.oddswire.io/reference/inviteBeta

POST /v1/admin/beta/invites
Invite beta: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`POST /v1/admin/beta/invites`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BetaInviteInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 201 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List account audit
Source: https://docs.oddswire.io/reference/listAccountAudit

GET /v1/account/audit
List account audit: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`GET /v1/account/audit`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List alert deliveries
Source: https://docs.oddswire.io/reference/listAlertDeliveries

GET /v1/account/alert-deliveries
List alert deliveries: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`GET /v1/account/alert-deliveries`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List alert rules
Source: https://docs.oddswire.io/reference/listAlertRules

GET /v1/account/alert-rules
List alert rules: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`GET /v1/account/alert-rules`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List competitions
Source: https://docs.oddswire.io/reference/listCompetitions

GET /v1/competitions
List competitions: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/competitions`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `sport` | query | No | Comma-separated sport IDs. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List fixtures
Source: https://docs.oddswire.io/reference/listFixtures

GET /v1/fixtures
List fixtures: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/fixtures`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `fixture` | query | No | Comma-separated namespace-scoped fixture/group IDs (max 25). |
| `competition` | query | No | Comma-separated competition IDs. |
| `sport` | query | No | Comma-separated sport IDs. |
| `books` | query | No | Source/region IDs, not brand IDs (comma separated). |
| `from` | query | No | Inclusive UTC-normalized RFC3339 kickoff bound. |
| `to` | query | No | Exclusive RFC3339 kickoff bound. |
| `status` | query | No | Stored fixture state. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List history ticks
Source: https://docs.oddswire.io/reference/listHistoryTicks

GET /v1/history/ticks
List history ticks: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/ticks`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `limit` | query | No | Page size 1..100; coverage remains present on every page. |
| `cursor` | query | No | Opaque whole-query fingerprint; restart explicitly after 409. |
| `from` | query | Yes | Inclusive received seen\_ts; required for ticks/coverage. |
| `until` | query | Yes | Exclusive received seen\_ts; required for ticks/coverage; maximum 31-day interval. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List keys
Source: https://docs.oddswire.io/reference/listKeys

GET /v1/account/keys
List keys: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`GET /v1/account/keys`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List mappings
Source: https://docs.oddswire.io/reference/listMappings

GET /v1/mappings
List mappings: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/mappings`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `fixture` | query | No | Comma-separated namespace-scoped fixture/group IDs (max 25). |
| `competition` | query | No | Comma-separated competition IDs. |
| `sport` | query | No | Comma-separated sport IDs. |
| `books` | query | No | Source/region IDs, not brand IDs (comma separated). |
| `from` | query | No | Inclusive UTC-normalized RFC3339 kickoff bound. |
| `to` | query | No | Exclusive RFC3339 kickoff bound. |
| `status` | query | No | Stored fixture state. |
| `native_fixture` | query | No | Exact native fixture ID; requires one source in books. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List markets
Source: https://docs.oddswire.io/reference/listMarkets

GET /v1/markets
List markets: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/markets`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `sport` | query | No | Comma-separated sport IDs. |
| `markets` | query | No | Families: 1x2,total,asian\_handicap. |
| `period` | query | No | Market period. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List members
Source: https://docs.oddswire.io/reference/listMembers

GET /v1/account/members
List members: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`GET /v1/account/members`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List odds
Source: https://docs.oddswire.io/reference/listOdds

GET /v1/odds
List odds: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/odds`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `fixture` | query | No | Comma-separated namespace-scoped fixture/group IDs (max 25). |
| `competition` | query | No | Comma-separated competition IDs. |
| `sport` | query | No | Comma-separated sport IDs. |
| `books` | query | No | Source/region IDs, not brand IDs (comma separated). |
| `from` | query | No | Inclusive UTC-normalized RFC3339 kickoff bound. |
| `to` | query | No | Exclusive RFC3339 kickoff bound. |
| `status` | query | No | Stored fixture state. |
| `markets` | query | No | Families: 1x2,total,asian\_handicap. |
| `period` | query | No | Market period. |
| `format` | query | No | Display format; canonical decimal/native units remain unchanged. |
| `include_inactive` | query | No | Explicitly include stale/suspended/unavailable retained quotes; invalid quotes remain excluded. |
| `line_quarters` | query | No | Exact signed home-relative quarter line in group orientation. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List sources
Source: https://docs.oddswire.io/reference/listSources

GET /v1/bookmakers
List sources: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/bookmakers`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List sports
Source: https://docs.oddswire.io/reference/listSports

GET /v1/sports
List sports: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/sports`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit pilot namespace; numeric IDs are scoped to it. |
| `limit` | query | No | Page size 1..100; default 25. |
| `cursor` | query | No | Opaque query-bound cursor; restart on 409 after data changes. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 402 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 414 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# List webhook targets
Source: https://docs.oddswire.io/reference/listWebhookTargets

GET /v1/account/webhook-targets
List webhook targets: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`GET /v1/account/webhook-targets`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Report beta
Source: https://docs.oddswire.io/reference/reportBeta

GET /v1/admin/beta
Report beta: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`GET /v1/admin/beta`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Review beta source
Source: https://docs.oddswire.io/reference/reviewBetaSource

PUT /v1/admin/beta/sources
Review beta source: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`PUT /v1/admin/beta/sources`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BetaPermission"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Revoke beta
Source: https://docs.oddswire.io/reference/revokeBeta

POST /v1/admin/beta/invites/{invite_id}/revoke
Revoke beta: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Invite-only personal API beta. Signup grants no data access. Acceptance requires the exact enrolled identity/account, approved region and acknowledgment. Source permissions, expiry and environment are revalidated on data reads. Global beta administration requires a separately provisioned operator, not a customer owner/admin. Invitations are shown once and never placed in URLs. Notices are local previews only; billing/Terminal are separate.

`POST /v1/admin/beta/invites/{invite_id}/revoke`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `invite_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/BetaRevoke"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Revoke key
Source: https://docs.oddswire.io/reference/revokeKey

DELETE /v1/account/keys/{key_id}
Revoke key: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`DELETE /v1/account/keys/{key_id}`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `key_id` | path | Yes | See the OpenAPI schema. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Rotate key
Source: https://docs.oddswire.io/reference/rotateKey

POST /v1/account/keys/{key_id}/rotate
Rotate key: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`POST /v1/account/keys/{key_id}/rotate`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `key_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/CreateKey"
}
```

## Responses

| Status | Meaning |
| - | - |
| 201 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Rotate webhook target
Source: https://docs.oddswire.io/reference/rotateWebhookTarget

POST /v1/account/webhook-targets/{target_id}/rotate
Rotate webhook target: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Owner/admin session only; API keys and viewers cannot manage alerts. Control calls and outbound attempts use no REST credits. Separate alerts/odds grants, account-owned key, expiring alerts purpose review and current source access are required for rules and dispatch. POST request\_id is an account-wide UUID idempotency key; retry identical content. Signing secrets appear once, including after rotation; duplicate mutation responses omit them. No external delivery is enabled automatically.

`POST /v1/account/webhook-targets/{target_id}/rotate`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `target_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/AlertMutation"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Set member role
Source: https://docs.oddswire.io/reference/setMemberRole

PUT /v1/account/members/{user_id}
Set member role: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Requires an explicit Bearer Clerk session (or CLI-only local session). API keys cannot manage accounts. Owner/admin manages keys and audit; only owner changes existing member roles. POST auth/session enrolls an identity with zero API/Terminal grants. Provider login is unavailable until Clerk is configured.

`PUT /v1/account/members/{user_id}`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |
| `user_id` | path | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/RoleChange"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Signed test-mode Stripe inbox receipt
Source: https://docs.oddswire.io/reference/stripeWebhook

POST /v1/billing/webhook
Signed test-mode Stripe inbox receipt: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Provider-signed incoming webhook. Application SDKs do not send this request.

`POST /v1/billing/webhook`

## Authentication

Stripe signature verification; no customer API key.

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `Stripe-Signature` | header | Yes | See the OpenAPI schema. |

## Request body

```json theme={null}
{
  "type": "object"
}
```

## Responses

| Status | Meaning |
| - | - |
| 202 | Durably accepted; fulfillment is asynchronous reconciliation. |
| 400 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 413 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Terminal board
Source: https://docs.oddswire.io/reference/terminalBoard

POST /v1/terminal/board
Terminal board: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Session-only Terminal product. Separate current Terminal grants and display/chart source-purpose/region reviews; API plans/keys and REST credits are not used. Private, no-store, bounded polling and native recorded history only.

`POST /v1/terminal/board`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/TerminalBoardInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Terminal chart
Source: https://docs.oddswire.io/reference/terminalChart

POST /v1/terminal/chart
Terminal chart: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Session-only Terminal product. Separate current Terminal grants and display/chart source-purpose/region reviews; API plans/keys and REST credits are not used. Private, no-store, bounded polling and native recorded history only.

`POST /v1/terminal/chart`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/TerminalChartInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Terminal context
Source: https://docs.oddswire.io/reference/terminalContext

GET /v1/terminal/context
Terminal context: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Session-only Terminal product. Separate current Terminal grants and display/chart source-purpose/region reviews; API plans/keys and REST credits are not used. Private, no-store, bounded polling and native recorded history only.

`GET /v1/terminal/context`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Terminal preferences
Source: https://docs.oddswire.io/reference/terminalPreferences

PUT /v1/terminal/preferences
Terminal preferences: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Session-only Terminal product. Separate current Terminal grants and display/chart source-purpose/region reviews; API plans/keys and REST credits are not used. Private, no-store, bounded polling and native recorded history only.

`PUT /v1/terminal/preferences`

## Authentication

`AccountSession`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `X-Oddswire-Account` | header | No | UUID of an account where the signed-in user is a member; defaults to their oldest account. |

## Request body

```json theme={null}
{
  "$ref": "#/components/schemas/TerminalPreferencesInput"
}
```

## Responses

| Status | Meaning |
| - | - |
| 200 | Account ledger response; no-store. Key secrets appear only once on creation/rotation. Lists contain at most 100 recent entries, active keys first. |
| 400 | Structured problem; see [error handling](/errors). |
| 401 | Structured problem; see [error handling](/errors). |
| 403 | Structured problem; see [error handling](/errors). |
| 404 | Structured problem; see [error handling](/errors). |
| 405 | Structured problem; see [error handling](/errors). |
| 409 | Structured problem; see [error handling](/errors). |
| 422 | Structured problem; see [error handling](/errors). |
| 429 | Structured problem; see [error handling](/errors). |
| 500 | Structured problem; see [error handling](/errors). |
| 503 | Structured problem; see [error handling](/errors). |
| 504 | Structured problem; see [error handling](/errors). |

Full request and response schemas: [OpenAPI](/openapi.json). [Authentication](/authentication) · [Prices and coverage](/data) · [Errors and credits](/errors).


# Private Terminal board
Source: https://docs.oddswire.io/terminal

Separate product permissions, native quotes, freshness and fixture charts.

The private Terminal is a locally verified odds-board slice. Customer rollout,
source display/chart/fair rights, real login and production readiness remain
pending. Public marketing does not expose private Terminal data or grant access.

A session uses the **Terminal** product grant under the shared account. API keys,
API plans and beta enrollment do not unlock it. Terminal views consume no REST
credits, including at zero quota; normal abuse limits still apply. Country/state
and my-books preferences do not prove location or grant source rights.

Choose country/state, data workspace, your granted source/region books, sport,
competition, market/line and phase. Saves are per member; conflicting revisions
require reloading settings. Real working collectors remain pre-match-only; live
needs a separate product grant and validated source support. Read [in-play scope](/inplay).

Each native price retains its source, region, offer, outcome, side and depth.
Source-local rows and different settlements stay separate. Best gross labels
compare matching sportsbook scopes with exact decimal prices. Prediction-market
probabilities remain explicitly labeled and separate. Fair references require
reviewed grouping, current eligible inputs, Terminal fair access and independent
source-purpose approval; insufficient or unavailable references stay explicit.

Quote ages use successful confirmation time. Prices disappear when stale,
suspended or unavailable; pausing does not freeze their ages. A visible tab polls
at ten-second intervals, clearing errors and access changes. Source status and
missing reasons distinguish blocked rights, unsupported coverage and outages.

A fixture drawer reads one exact native quote from verified retained history,
with 1/6/24-hour windows and a 500-point bound. Charts preserve A→B→A, recorded
suspensions and freshness gaps. Exact points, ingest IDs and coverage metadata
remain available; no missing history is replaced with demo prices. See [history semantics](/history).

Session-only routes are [context](/reference/terminalContext),
[preferences](/reference/terminalPreferences), [board](/reference/terminalBoard)
and [chart](/reference/terminalChart). They are separate from API-key data routes.
The board is bounded to ten fixtures and 500 native cells per page; pagination
reads current snapshots. Larger virtualized streaming, opportunities, stakes,
alerts, tracking and subscriptions remain later Terminal tasks.


# WebSocket protocol
Source: https://docs.oddswire.io/websocket

Server-client connection, snapshot/delta ordering and safe recovery.

The REST clients ship the generated `WSCommand` and `WSFrame` types. WebSocket networking is a separate integration: use a server-side WebSocket library that sets headers. The existing gateway accepts `ws://127.0.0.1:9113/v1/ws`, one `X-API-Key` header, and subprotocol `oddswire.v1`. Use WSS for any future remote deployment. Require explicit API `odds` and `websocket` grants; REST/Terminal access alone is insufficient. Messages cost no REST credits.

Native browser WebSocket constructors cannot supply the required header. Origin-bearing upgrades are rejected; a reviewed short-lived ticket bridge remains open. Never put a key in the URL or subprotocol.

After `hello`, send this **illustrative** subscription, replacing IDs with discovered, entitled ones:

```json theme={null}
{
  "type": "subscribe",
  "id": "first",
  "params": { "namespace": "oddswire_kambi", "fixture": "100", "books": "5,7" }
}
```

Filters are strings. Namespace plus fixture(s) or competition(s) is required. One active subscription is supported per connection. No REST page `limit` or `cursor` inside `params`. For resume, put the last fully applied opaque cursor at the command's top level.

## State application

1. Treat `delivery_seq` and namespace positions as exact decimal strings; never convert them to JavaScript numbers. Delivery sequence resets per connection.
2. A `snapshot`, `resumed` or `state` frame with `replace: true` replaces the **entire** view, including an empty array. Retain `missing[]`.
3. Apply each `delta` frame's ordered changes atomically, keyed by native `quote_key`. Preserve event IDs and A → B → A changes; filtered positions may jump.
4. Persist the cursor only after the whole frame is applied. Heartbeat/pong may renew it at the same position. Resume is bounded to five minutes and retained journal capacity.
5. `resnapshot_required` clears view and cursor. Subscribe again without a cursor. Disconnect marks retained quotes unconfirmed/non-executable. Never treat a heartbeat or `sent_ts` as a new source confirmation.
6. Keep a continuous reader active to answer protocol pings, including between price updates. Respect bounded input/backlog/write/pong behavior. Slow clients are disconnected; reconnect deliberately with the last fully applied cursor, or take a fresh snapshot.

Metadata, mapping, lineage, entitlement or journal gaps can require a resnapshot. Current source/rights/freshness checks still apply during recovery. The [AsyncAPI](/asyncapi.json), [wire schema](/websocket.schema.json) and local `make ws-test` define/test the transport. This docs task does not claim a hosted stream or browser ticket bridge.

## Local launch checks

`make ws-launch-test` exercises 16 local clients, saved-source persistence, gateway-instance shutdown/resume, explicit capacity rejection and synthetic signed billing events against connected streams. `make ws-benchmark` writes a private workload/timing report under `.cache/ws-validation`. The harness uses race detection and full client wire validation; archive/drain-to-consumer timings are not production or provider latency.

Current limits remain 16 connections/process, two/account and one subscription/connection. The gateway instances share one test process/host/PG domain. Independent production failover, larger/multi-subscription capacity, real provider login/billing and source-use rights remain open.