> ## Documentation Index > Fetch the complete documentation index at: https://docs.fieldfunded.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Settlements > Fully automatic — markets resolve without developer intervention as soon as a game ends. Retrieves a real-time feed of recently settled match results and market resolutions. Optimized for automated betting systems to process payouts as soon as results are finalized. An event appears in this feed as soon as **at least one** market is resolved (`resolved_markets_count >= 1`); additional markets are appended gradually until `pending_markets_count` reaches `0`. This includes standard markets, player-prop markets, and dynamic live markets as each one is officially resolved. Team names, logos, and final scores are included with each settlement entry. ⚠️ Poll regularly after the game ends to capture all market resolutions as they arrive gradually. Poll every ~60s to capture all market resolutions before they expire. This endpoint can return larger responses than lightweight endpoints (e.g. `/v1/scores`) because each item may include multiple resolved markets and outcomes. We recommend keeping `limit` small (20-50). Results are returned newest first (`ended_at` descending), with `event_id` as a tie-breaker. Use `cursor` pagination for efficient incremental processing. For permanent score data, use `/v1/events/{eventId}/result`. ## OpenAPI ````yaml GET /v1/settlements openapi: 3.0.3 info: title: FieldFunded Sports API description: > Real-time sports data API covering **30+ sports & esports** and **1,000+ betting markets** per event. Built for low-latency live odds, settlement, and quantitative analysis. ## Official SDK The fastest way to integrate is using our official [TypeScript SDK](/sdk). It handles authentication, retries, and provides full type safety for all 1,000+ markets. ## Features - **Sub-second latency** — Data refreshed every 300ms from live feeds - **30+ sports & esports** — Soccer, Basketball, Tennis, Ice Hockey, Baseball, American Football, Rugby, Cricket, MMA, Handball, Volleyball, and more - **Full Esports Coverage** — Counter-Strike, Dota 2, LoL, Valorant, Rainbow Six, King of Glory, Call of Duty, Mobile Legends - **1,000+ Markets per game** — Match Winner, Over/Under, BTTS, Handicaps, Corners, Cards, Player Props, Map Winner, Round Winner, and more (major leagues like NBA, NFL, Premier League) - **Live Scores** — Real-time scoreboards with period scores, serving indicators, and match clocks - **Outrights/Futures** — Long-term futures and season-level markets (e.g., League Winner, Top Goalscorer, Most Assists, Tournament MVP) - **Settlement Results** (Automatic) — Per-market settlement outcomes (won/lost/refund) for ended events, with gradual market-by-market resolution. No developer action required — markets begin resolving within seconds after game end. Send `stake` to get instant `payout` calculation (currency-agnostic). Poll regularly after the game ends to capture all market resolutions as they arrive. - **Parlay Resolution** (Exclusive) — Submit multi-leg parlays (singles, combos) and get combined result + payout calculation with optional `stake`. Refund legs are treated as odds 1.00 in the combined calculation. - **Featured Games** — Curated top matches from priority leagues (Premier League, La Liga, Champions League, Europa League, Bundesliga, Serie A, Ligue 1, NBA, NFL, MLB, NHL), live-first sorted. - **Rich Visual Assets** — PNG team logos (~85% coverage), PNG & SVG team logos for featured leagues, SVG league logos, 182 SVG country flags and custom SVG sport icons. - **Global Coverage** — Premier League, La Liga, NBA, NFL, NHL, MLB, Champions League, and thousands of worldwide leagues including 3rd divisions, regional cups, ITF tournaments, and youth/female leagues, etc. ## Pricing Free tier with 10,000 requests/month. Paid plans from $29/mo. All features included at every tier. See [full pricing comparison](/compare/pricing). ## Learn More - [Quick Start Guide](/quickstart) — First API call in 5 minutes - [Authentication](/authentication) — API key setup - [Rate Limits](/rate-limits) — Per-plan limits and quota monitoring - [Supported Sports](/reference/supported-sports) — Full sport key reference - [Market Types](/reference/market-types) — 1,000+ market catalogue - [Event Statuses](/reference/event-statuses) — Lifecycle and 48-hour rule - [Visual Assets](/reference/visual-assets) — Logos, flags, and icons - [SDK Reference](/sdk) — TypeScript SDK installation and usage ## Sport-Specific Live Data Detail endpoints include a `sport_data` object with sport-specific fields: - **Tennis/Volleyball**: `home_serving`, `away_serving` (who is serving), `home_game_score`/`away_game_score` (values: `0`, `15`, `30`, `40`, `AD`), `is_tiebreak` - **Ice Hockey**: `home_suspend`/`away_suspend` (players in penalty box = power play indicator) - **All sports**: Period-by-period scoreboards via `scoreboard` object The `scoreboard` object contains: - `headers`: Column labels (e.g. `["", "1st", "2nd", "T", "Corner", "YC", "RC"]`) - `home`/`away`: Stats arrays matching the headers **Sport-specific scoreboard detail:** | Sport | Scoreboard Columns | Extra Fields | |-------|-------------------|--------------| | **Football (Soccer)** | 1st Half, 2nd Half, Total, Corners, Yellow Cards (YC), Red Cards (RC) | `period` (1H, 2H, HT, ET, PEN) | | **Tennis** | Set 1, Set 2, Set 3, Set 4, Set 5, Total | `home_game_score`/`away_game_score` (0, 15, 30, 40, AD), `is_tiebreak`, `home_serving`/`away_serving` | | **Basketball (NBA)** | Q1, Q2, Q3, Q4, OT, Total | `period` (Q1-Q4, OT1-OT3) | | **Ice Hockey (NHL)** | P1, P2, P3, OT, Total | `home_suspend`/`away_suspend` (power play) | | **American Football (NFL)** | Q1, Q2, Q3, Q4, OT, Total | `period`, `down_and_distance` | | **Baseball (MLB)** | Inn 1-9+, Total, Hits, Errors | `period` (Top/Bot 1-9+), `bases`, `outs` | | **Volleyball** | Set 1-5, Points, Total | `home_serving`/`away_serving` | | **Table Tennis** | Set 1-7, Total | `home_serving`/`away_serving` | | **CS2 / Valorant** | Map 1, Map 2, Map 3, Rounds | `current_map`, `map_score`, `round_score` | | **Dota 2 / LoL** | Game 1, Game 2, Game 3, Total | `current_game`, `game_duration` | | **Cricket** | Innings 1, Innings 2, Overs, Wickets | `run_rate`, `target` | | **Handball** | 1st Half, 2nd Half, Total | `period` | | **Rugby** | 1st Half, 2nd Half, Total | `period`, `try_count` | | **Darts** | Set/Leg scores | `current_set`, `current_leg` | | **Snooker** | Frame scores, Total | `current_frame`, `frame_score` | | **MMA / Boxing** | Round 1-12, Total | `current_round` | ## Prematch Odds - Prematch events include full market odds (up to 1,000+ markets per event on major leagues) - Odds are refreshed via incremental cursor — 10 prematch games per 300ms cycle (~10-30s full pass depending on total game count) - Detail data (markets, scoreboards) polled every ~16-20s per event - All odds formats supported: `decimal`, `american`, `fractional` ### Fixture Horizon Prematch fixture depth is **league-dependent** — major leagues (e.g. Premier League, NBA) typically appear further ahead than niche or regional events. There is no fixed global limit; it reflects when the data provider publishes upcoming matches. Use `GET /v1/events?starts_within=2h` or `starts_within=1d` to filter by time window. Every event includes a `commence_time` (ISO 8601) field for precise scheduling. ## Market Suspension & Locked Odds Individual selections or entire markets can become temporarily **locked** (`is_locked: true`). This happens during: - **Goal/score events** — markets lock for 30-60 seconds while odds are recalculated - **Dangerous moments** — e.g. penalty kicks, red cards, break points in tennis - **End of game** — as a match approaches final minutes, the provider progressively locks markets - **Half-time / period breaks** — some markets lock between periods When `is_locked: true`, the odds value is still present (last known value) but the selection **cannot be bet on**. Your UI should grey out or disable these selections. ### Empty Markets (End of Game) Near the end of a live match, the `markets` array may become **empty** (`[]`) or return with **all outcomes locked**. This is normal — the provider stops accepting bets in the final minutes. The `markets_count` field will reflect `0` in this case. After the game finishes (`status: "ended"`), markets are no longer returned. Use `/v1/events/{eventId}/result` or `/v1/settlements` for final settlement data. ### ended Game Snapshot (Endgame Data) When a game finishes (or is cancelled/postponed), the API archives the final score permanently and provides settlement data in a rolling window. This applies to **all sports & esports** (Soccer, NBA, CS2, LoL, Tennis, etc.). **Two tiers of post-game data:** | Endpoint | Data | Retention | |----------|------|-----------| | `/v1/events/{eventId}/result` | Final score, status | **Permanent** — archived indefinitely | | `/v1/settlements` | Market resolutions (won/lost/refund), team names, scores, logos | **Recent** — poll regularly after game end to capture all market resolutions as they arrive gradually | | `/v1/bets/check` | Bet resolution against settlement data | **Recent** (same as settlements) | > **Important**: Process settlements promptly by polling every 60 seconds. Final scores remain permanently available via `/v1/events/{eventId}/result`. ## Team Side Identification Market outcomes include an optional `team_side` field: - `"home"` — this selection refers to the home team - `"away"` — this selection refers to the away team - `null` or absent — neutral selection (Draw, Over/Under totals, etc.) This is useful for mapping selections to team names without parsing the `label` string. Available on 1X2, Handicap, Double Chance, and similar two-sided markets. ### Prematch → Live Transition Detected automatically. When a game kicks off, its status changes from `prematch` to `live` and it appears in `/v1/live`. No action needed from the developer. All IDs, scores, and timestamps in endpoint examples are **synthetic**. Use /v1/events to discover real event IDs. version: 1.0.0 termsOfService: https://docs.fieldfunded.com/terms contact: name: FieldFunded API Support url: https://docs.fieldfunded.com email: support@fieldfunded.com servers: - url: https://api.fieldfunded.com description: Production security: - ApiKeyAuth: [] tags: - name: Sports description: Discover available sports and leagues - name: Events description: Browse and search sports events - name: Live description: Real-time live event data and scores - name: Odds description: Current betting odds - name: Results description: Automatic match settlement and outcomes - name: Settlement description: > Fully automatic bet settlement — markets resolve on their own as soon as a game ends. No developer action required. Also includes bet-check endpoints: submit your users' selections to verify outcomes against automatic results. Supports single bets and multi-leg parlays/combos. The 48-hour rule applies: postponed/suspended games that don't resume within 48h are auto-refunded. #### Accurate Settlement Using IDs Every market and selection has a unique ID (`market_id` and `selection_id`). Use these IDs for bet placement and settlement to guarantee 100% accuracy. Market names and labels are also available for display purposes. - name: Outrights description: | Season-level winner markets (e.g., League Winner). Updated every 3 hours. - name: System description: API health and status - name: Usage Monitoring description: >- Track your API usage, quota status, and active warnings. Data available via the Developer Portal at `/portal`. paths: /v1/settlements: get: tags: - Settlement summary: Settlement Feed — Auto-resolved market outcomes (won/lost/refund) description: > Fully automatic — markets resolve without developer intervention as soon as a game ends. Retrieves a real-time feed of recently settled match results and market resolutions. Optimized for automated betting systems to process payouts as soon as results are finalized. An event appears in this feed as soon as **at least one** market is resolved (`resolved_markets_count >= 1`); additional markets are appended gradually until `pending_markets_count` reaches `0`. This includes standard markets, player-prop markets, and dynamic live markets as each one is officially resolved. Team names, logos, and final scores are included with each settlement entry. ⚠️ Poll regularly after the game ends to capture all market resolutions as they arrive gradually. Poll every ~60s to capture all market resolutions before they expire. This endpoint can return larger responses than lightweight endpoints (e.g. `/v1/scores`) because each item may include multiple resolved markets and outcomes. We recommend keeping `limit` small (20-50). Results are returned newest first (`ended_at` descending), with `event_id` as a tie-breaker. Use `cursor` pagination for efficient incremental processing. For permanent score data, use `/v1/events/{eventId}/result`. operationId: getSettlements parameters: - name: limit in: query description: >- Maximum number of settlements to return (default: 100, max: 200). Recommended 20-50 for recurring polling. schema: type: integer minimum: 1 maximum: 200 default: 100 - name: offset in: query description: >- Number of settlements to skip for pagination (default: 0). For recurring polling, keep offset=0. schema: type: integer minimum: 0 default: 0 - name: cursor in: query description: >- Cursor-based pagination token (base64url encoded `{ended_at,event_id}` from `next_cursor`). Do not combine with offset. schema: type: string - name: event_id in: query description: Filter settlements by a single event id. schema: type: string - name: event_ids in: query description: Filter settlements by multiple event ids (CSV). Maximum 50 ids. schema: type: string responses: '200': description: >- A feed of recently ended events and their finalized market outcomes (won, lost, refund). content: application/json: schema: type: object properties: settlements: type: array items: type: object properties: event_id: type: string home_team: type: string away_team: type: string home_logo: type: string format: uri description: >- PNG team logo URL. Most major teams have logos; returns a default placeholder when unavailable. away_logo: type: string format: uri description: >- PNG team logo URL. Most major teams have logos; returns a default placeholder when unavailable. final_score: $ref: '#/components/schemas/Score' sport: type: string nullable: true description: >- Sport name (e.g. 'Soccer', 'Baseball'). May be null for older settled events where Redis data has expired. league: type: string nullable: true country: type: string nullable: true start_time: type: string format: date-time nullable: true ended_at: type: string format: date-time status: type: string enum: - settled description: >- Event settlement status (always 'settled' in this feed) settlement_status: type: string enum: - settled description: '''settled'' = per-market results available.' resolved_markets: type: array items: type: object properties: key: type: string name: type: string market_id: type: integer nullable: true description: >- Unique market identifier for accurate settlement outcomes: type: array items: type: object properties: label: type: string result: type: string enum: - won - lost - refund selection_id: type: integer nullable: true description: >- Unique selection identifier for accurate settlement resolved_markets_count: type: integer description: >- Number of markets with at least one resolved outcome. During gradual settlement, this number increases over time. total_markets_count: type: integer nullable: true description: >- Total number of markets for this event (resolved + pending). Null for legacy entries. Compare with resolved_markets_count to track settlement progress. pending_markets_count: type: integer nullable: true description: >- Number of markets still pending resolution. 0 when fully settled. Null for legacy entries. total: type: integer fully_settled: type: integer score_only: type: integer limit: type: integer offset: type: integer has_more: type: boolean next_cursor: type: string nullable: true description: >- Cursor for next page when using cursor-based incremental polling applied_filters: type: object properties: event_ids_count: type: integer using_cursor: type: boolean example: settlements: - event_id: '87654321' home_team: Arsenal away_team: Chelsea home_logo: https://api.fieldfunded.com/api/logo/t-38 away_logo: https://api.fieldfunded.com/api/logo/t-42 final_score: home: 2 away: 1 sport: soccer league: Premier League country: England start_time: '2026-04-12T15:00:00Z' status: settled settlement_status: settled ended_at: '2026-04-12T16:55:00Z' resolved_markets: - key: match_winner name: Match Winner market_id: 340159 outcomes: - label: Home result: won selection_id: 1824561 - label: Draw result: lost selection_id: 1824562 - label: Away result: lost selection_id: 1824563 - key: over_under_2_5 name: Over/Under 2.5 market_id: 340160 outcomes: - label: Over 2.5 result: won selection_id: 1824570 - label: Under 2.5 result: lost selection_id: 1824571 - key: double_chance name: Double Chance market_id: 340161 outcomes: - label: Home/Draw result: won selection_id: 1824580 - label: Home/Away result: lost selection_id: 1824581 - label: Draw/Away result: lost selection_id: 1824582 - key: both_teams_to_score name: Both Teams To Score market_id: 340162 outcomes: - label: 'Yes' result: won selection_id: 1824590 - label: 'No' result: lost selection_id: 1824591 - key: half_time_result name: Half-time Result market_id: 340163 outcomes: - label: Home result: lost selection_id: 1824600 - label: Draw result: won selection_id: 1824601 - label: Away result: lost selection_id: 1824602 - key: correct_score name: Correct Score market_id: 340164 outcomes: - label: 2-1 result: won selection_id: 1824610 - label: 1-1 result: lost selection_id: 1824611 - label: 2-0 result: lost selection_id: 1824612 - key: asian_handicap_minus_1 name: Asian Handicap -1.0 market_id: 340165 outcomes: - label: Home (-1.0) result: won selection_id: 1824620 - label: Away (+1.0) result: lost selection_id: 1824621 - key: total_corners_over_9_5 name: Total Corners Over 9.5 market_id: 340166 outcomes: - label: Over 9.5 result: won selection_id: 1824630 - label: Under 9.5 result: lost selection_id: 1824631 - key: first_goalscorer name: First Goalscorer market_id: 340167 outcomes: - label: Harry Kane result: won selection_id: 1824640 - label: Bukayo Saka result: lost selection_id: 1824641 - key: total_cards_over_3_5 name: Total Cards Over 3.5 market_id: 340168 outcomes: - label: Over 3.5 result: won selection_id: 1824650 - label: Under 3.5 result: lost selection_id: 1824651 resolved_markets_count: 1118 total_markets_count: 1118 pending_markets_count: 0 total: 842 fully_settled: 10 score_only: 0 limit: 50 offset: 0 has_more: true next_cursor: BASE64URL_CURSOR_TOKEN_FROM_PREVIOUS_RESPONSE applied_filters: event_ids_count: 0 using_cursor: false '400': description: Invalid settlements filters or pagination parameters content: application/json: schema: $ref: '#/components/schemas/Error' examples: too_many_event_ids: summary: event_ids exceeds max 50 value: error: bad_request message: Maximum 50 event ids are allowed for settlements filters cursor_offset_conflict: summary: cursor and offset were sent together value: error: bad_request message: Use either 'cursor' or 'offset', not both. invalid_cursor: summary: malformed cursor token value: error: bad_request message: >- Invalid 'cursor'. Expected base64url encoded { ended_at, event_id }. '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: Score: type: object description: >- Home/away goals or points. A value of `0` is a valid score (for example, 0-0) and is returned as numeric zero. properties: home: type: integer example: 2 away: type: integer example: 1 Error: type: object properties: error: type: string description: Error type message: type: string description: Human-readable error message example: error: not_found message: Event not found. For historical results, use /v1/settlements. responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Invalid or missing API key. Visit docs.fieldfunded.com for access. RateLimited: description: Rate limit exceeded headers: Retry-After: description: Seconds until rate limit resets schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited message: Rate limit exceeded. Upgrade your plan for higher limits. InternalServerError: description: | Internal server error. Something went wrong on our end. Usually transient — please retry after a short delay. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: server_error message: Internal server error ServiceUnavailable: description: > Backend data store temporarily unavailable. The `Retry-After` header indicates how many seconds to wait before retrying. The `component` field identifies which service is degraded (`realtime_data` for live odds/scores, `historical_data` for settlements). headers: Retry-After: description: Recommended wait time in seconds before retrying schema: type: integer example: 30 content: application/json: schema: type: object properties: error: type: string example: service_unavailable message: type: string example: Data store temporarily unavailable component: type: string enum: - realtime_data - historical_data description: Which service is temporarily degraded example: realtime_data example: error: service_unavailable message: Data store temporarily unavailable component: realtime_data securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Your FieldFunded API Key ````