Match data.
Clear integration.

Read scoped match snapshots and odds, subscribe to live updates, and embed a Matchflow tracker with a short-lived token.

Authentication and scope

Keep your customer API key on your server and send it in x-api-key. Match REST and token issuance use x-api-key. Tracker snapshot/SSE requests use Authorization: Bearer with a widget token; stream tokens go in Socket.IO auth. Tokens are audience-bound and cannot be substituted across these services. Send exactly one credential header. Browser integrations use a short-lived token issued by your backend. Never put the long-lived API key in browser code, iframe URLs, query strings or logs. Each credential restricts endpoints, sports, bookmakers and matches and has request, daily, connection and subscription limits.

curl 'https://api.matchflow.oraunku.com/v1/matches?sport=soccer&date=2026-10-27&timezone=Asia%2FSeoul&limit=50' \
  -H 'x-api-key: YOUR_SERVER_SIDE_KEY'

REST reference

List limit defaults to 200 and is capped at 500. History limit defaults to 500 and is capped at 2,000. Send finite positive integers. oddsLimit defaults to 100 and is capped at 500 per pre-match bookmaker; values below 1 become 1. Each bookmaker reports totalPrices, returnedCount and truncated. A list response has an aggregate 5,000-price budget. Inspect match oddsTruncated and oddsReturnReason (response_budget, response_limit or a source limit); fetch match detail for omitted prices rather than treating omission as market absence. Sport defaults to soccer on all match endpoints; specify it for other sports. These are bounded result sets: there is no cursor, offset, next-page field or guarantee that one date response includes every match. Narrow by date and sport; arrange additional coverage with support if the cap is reached. Match identifiers are canonical UUIDs. Use mainOnly=true or 1 for main lines. A missing match or current-odds match returns 404; a present match may have empty odds. History enforces the same match, sport and bookmaker scope as current odds; optional bookmaker filters narrow those entitlements. A missing or wrong-sport history match returns 404. History is pre-match price-event history; it is not the in-play archive.

Detail/current-odds responses may include a separate entitled inplay object with currentOdds and archivedOdds. Its archive reconstructs only bounded recent frames, not complete historical coverage. Reconstruction reads at most 100 frames and 8 MiB, with 5,000 quotes per frame and 10,000 retained quotes. Oversized or incomplete input returns unavailable coverage with an explicit incompleteReason, rather than a partial board presented as complete. Check boardCoverage, archivedCoverage and truncated. mainOnly cannot filter the live board and is reported as mainOnlyUnavailable when requested.

Realtime: Socket.IO 4

Use a compatible Socket.IO 4 client against the stream host with transport path /socket.io/. This service is not a native WebSocket JSON endpoint. Your backend obtains a token using POST /v1/stream-tokens and its x-api-key header. Optional JSON {sports,bookmakers,matches} arrays narrow scope; omitted fields inherit key scope. The response is {token,expiresIn:120}; key expiry can shorten validity. Connect with auth:{token} in the Socket.IO auth payload and subscribe only to entitled match topics. Send subscribe with {matchIds:["MATCH_UUID"]} (1–100 IDs per request); its acknowledgement is {ok:true,matchIds:[...],resyncRequired:true} or {ok:false}. Send unsubscribe with {matchId:"MATCH_UUID"}. Arbitrary room names and wildcard/admin topics are denied. Acknowledgements confirm subscription state; they do not establish data freshness.

Fetch a REST snapshot before rendering. On every reconnect, obtain a fresh token when needed, restore subscriptions and refetch current snapshots. Listen for a resync event and refetch every subscribed match snapshot when it arrives, including after stream overload. Events are transient change notifications: there is no customer durable replay cursor, guaranteed delivery or reconnect backlog. Deduplicate using an event identifier when supplied and avoid replacing newer snapshot state with an older event.

Tracker, iframe and SDK

Your backend issues a scoped token through POST /v1/widget-tokens with JSON {widgetId,matchId,sport,origin}. The origin must exactly match an origin registered for the widget. The response contains token and expiresAt; validity is at most 120 seconds and may be shorter when the key expires. That token permits the configured tracker match only. Use only the fixed SDK release referenced by the CDN manifest; verify its published SHA-256 before deployment. Do not use an unpinned “latest” URL in production. Create the tracker frame without a credential in its URL. Wait for the frame-ready message, verify its exact origin and source window, then deliver the short-lived token using postMessage with the exact tracker origin. Treat token expiry and snapshot/stream failures as visible states. The SDK must enforce the same checks for messages from the frame.

Read https://cdn.matchflow.oraunku.com/matchflow/manifest.json for the immutable SDK path. The iframe path is /tracker/{widgetId}. A frame announces {type:"matchflow:ready",widgetId}; reply with {type:"matchflow:token",widgetId,token}. On matchflow:token-needed, request a replacement from your backend and repeat delivery. Tracker snapshots poll every 15 seconds. The frame also opens a bearer-authenticated SSE fetch at /v1/tracker/{widgetId}/updates; a resync event triggers a fresh snapshot. There is no SSE replay, cursor or full source payload. The polling interval is not a source-latency guarantee. Do not substitute a long-lived API key for a browser token. The existing operations dashboard is at dashboard.matchflow.oraunku.com. The admin.matchflow.oraunku.com alias redirects to the same authenticated dashboard while preserving the path.

Freshness is part of the data

updatedAt describes a stored snapshot update; history eventTime describes a recorded price event. Pre-match quotes expose freshness.state="unknown", providerAt=null and receivedAt=null; lastChangedAt is a last recorded change, not a fresh upstream observation. In-play receipt time, where available, is reported separately. Neither alone measures original bookmaker latency. A live match flag, an open socket and an unsuspended price are separate facts. Render missing/null values as unavailable, suspended prices as suspended, and old observations as stale according to your product policy. Repeated unchanged data does not prove a fresh upstream observation.

Coverage varies by sport, bookmaker, market and match. An empty in-play snapshot does not establish that the sport is unsupported. Historical retention and production latency targets require an agreed contract and measured evidence. The operator confirmed redistribution, white-label and image permissions on 2026-10-27. Contract originals were not inspected for this documentation; permitted scope follows that agreement. No provider marketing guarantee is represented here.

Errors and retry behavior

Error responses contain an error field. Do not expose credentials in diagnostic reports. Your account limits determine quota; this documentation does not promise a universal rate or SLA.

Changelog

2026-10-27 · Initial v1 integration documentation. Scoped REST access, Socket.IO integration rules, tracker token guidance and standalone public OpenAPI. Deployment verification is an operations task; publication alone does not establish production readiness.