Quickstart

1. Get Your API Key

RapidAPI (recommended)
Direct API Key

Visit FieldFunded on RapidAPI
Subscribe to a plan (Free tier = 10,000 req/mo)
Copy your X-RapidAPI-Key from the dashboard

X-RapidAPI-Key: YOUR_API_KEY
X-RapidAPI-Host: fieldfunded-sports-api.p.rapidapi.com

Contact support@fieldfunded.com for a direct key.

X-API-Key: YOUR_API_KEY

Mode	Base URL
RapidAPI	`https://fieldfunded-sports-api.p.rapidapi.com/v1`
Direct	`https://api.fieldfunded.com/v1`

Header names are case-insensitive (x-rapidapi-key works), but we recommend the canonical casing above.

2. Your First Request

curl -s "https://api.fieldfunded.com/v1/sports" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Response Format

All responses are JSON. Successful responses return the data directly:

{
    "events": [...],
    "total": 142,
    "limit": 50,
    "offset": 0
}

Error responses use a consistent schema:

{
    "error": "error_code",
    "message": "Human-readable explanation"
}

3. Official TypeScript SDK

The fastest way to integrate. Handles authentication, retries, and provides full type safety for all 1,000+ markets.

npm install @fieldfunded/sdk

import { FieldFundedSDK } from '@fieldfunded/sdk';

// RapidAPI mode (default)
const client = new FieldFundedSDK({
  apiKey: 'YOUR_RAPIDAPI_KEY',
});

// Direct API mode
const client = new FieldFundedSDK({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.fieldfunded.com/v1',
});

// Get all live games
const live = await client.getLive();
console.log(`${live.total} live games`);

// Get full event details (1,000+ markets)
const event = await client.getEvent(live.events[0].id);
console.log(`${event.home_team} vs ${event.away_team}`);
console.log(`Markets: ${event.markets.length}`);

Full SDK Documentation →

25 typed methods, error classes, configuration options, and all usage examples.

4. Common Patterns

Poll Live Scores (lightweight)

# Small payload — poll every 5-10 seconds
curl -s "https://api.fieldfunded.com/v1/scores?sport=soccer" \
  -H "X-API-Key: YOUR_API_KEY"

Search by Team Name

curl -s "https://api.fieldfunded.com/v1/search?q=Arsenal" \
  -H "X-API-Key: YOUR_API_KEY"

Batch Fetch Multiple Events

curl -s -X POST "https://api.fieldfunded.com/v1/events/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["EVENT_ID_1", "EVENT_ID_2", "EVENT_ID_3"]}'

Auto-Settle Bets

# Poll every 60 seconds via setInterval or a scheduled task
curl -s "https://api.fieldfunded.com/v1/settlements" \
  -H "X-API-Key: YOUR_API_KEY"

5. Integration Flow

Simple Integration

GET /v1/sports          → Discover available sports
GET /v1/events          → List events (filter by sport, status, league)
GET /v1/events/{id}     → Get full market depth for a specific event
GET /v1/scores          → Poll live scores (lightweight, every 5-10s)
GET /v1/settlements     → Auto-settle bets (poll every 60s)

White-Label Sportsbook

GET /v1/events?status=prematch   → Populate your event listing
GET /v1/live                     → Discover live events
GET /v1/events/{id}              → Full odds for user's selected event
POST /v1/bets/check              → Resolve individual bets
POST /v1/bets/check-parlay       → Resolve multi-leg parlays
GET /v1/settlements              → Batch-settle all ended events (every 60s)

6. How to Integrate Bets — Complete Flow

This is the most important section for sportsbook integrators.

Step 1 — Show odds to your user

Your frontend calls GET /v1/events/{id} and displays markets + odds.

Step 2 — User places a bet

When your user clicks “Place Bet”, save to your database:

Field	Source	Priority
`event_id`	From the event	Required
`market_id`	From `markets` array	Primary — 100% accuracy
`selection_id`	From `outcomes` array	Primary — 100% accuracy
`market`	e.g. `"Match Winner"`	Secondary — display only
`outcome`	e.g. `"Home"`	Secondary — display only
`odds`	Decimal odds at placement time	Required
`stake`	User’s wager amount	Your business logic

Always store the odds at placement time. Odds change constantly — the API does not track what odds a user saw.

market_id is the primary identification method. It is consistent across all fixtures within the same sport — e.g. market_id: 36 always means “1X2 (Match Winner)” in every soccer match. You can hard-code market ID mappings per sport for reliable settlement logic.

Step 3 — Check the result

After the game ends, call POST /v1/bets/check with the data you stored:

curl -X POST "https://api.fieldfunded.com/v1/bets/check" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selections": [{
      "event_id": "12345",
      "market": "Match Winner",
      "outcome": "Home",
      "odds": 1.85,
      "stake": 10,
      "market_id": 340168,
      "selection_id": 1824650
    }]
  }'

Response

{
  "results": [{
    "event_id": "12345",
    "result": "won",
    "payout_multiplier": 1.85,
    "stake": 10,
    "payout": 18.50
  }]
}

Step 4 — Credit the user

Result	Action	Payout
`won`	Credit `payout` to user’s balance	`stake × odds`
`lost`	No action (stake already deducted)	`0`
`refund`	Return original stake to user	`stake × 1.0`
`pending`	Game not finished yet — check again later	—

For parlays, use POST /v1/bets/check-parlay with stake and legs[]. The API calculates combined_odds and payout automatically.

Currency-agnostic: The stake and payout fields work with any currency. Send a numeric amount in whatever unit your platform uses (USD, EUR, BTC, points, etc.). No currency conversion is applied.

For production, use GET /v1/settlements (polled every 60s) as your primary settlement engine and /bets/check for on-demand verification.

Cross-Sport Market ID Consistency

market_id values are consistent across all fixtures within the same sport:

Market	`market_id`	Selections	Consistency
1X2 (Match Winner)	`36`	Home / Draw / Away	Fixed across all soccer
Total (Over/Under)	`24`	Over 0.5, 1.5, 2.5…	Fixed; specifier varies
Asian Handicap	`128`	Home (-0.5), Away (+0.5)…	Fixed; specifier varies
Both Teams to Score	`121`	Yes / No	Fixed across all soccer
Correct Score	`147`	0:0, 1:0, 2:1…	Fixed across all soccer

Example: market_id: 36 maps to 1X2 in every soccer match — whether it’s Hamburger SV vs. FC Union Berlin (2. Bundesliga) or Corinthians vs. CA Peñarol (Copa Sudamericana).

7. Settlement Feed Notes

Poll regularly after the game ends to capture all market resolutions as they arrive gradually. Always process settlements promptly.

An event appears in /v1/settlements as soon as the first market resolves, not only when all markets are done
resolved_markets_count grows over time; pending_markets_count reaches 0 when all markets are finalized
Core markets settle within seconds; niche markets resolve gradually over minutes
Coverage includes standard markets, player-prop markets, and dynamic live markets

Payload Modes

/v1/bets/check supports:

Batch: { "selections": [...] }
Single: { "selection": {...} }
Shortcut: { "event_id": "...", "market": "...", "outcome": "...", "odds": 1.85 }

/v1/bets/check-parlay supports:

Single: { "legs": [...], "stake": 10 }
Batch: { "parlays": [{ "parlay_id": "p1", "legs": [...], "stake": 10 }] }

Recommended Polling Pattern

Poll /v1/settlements every 60s
For each game:
  if settlement_status == "settled" → process resolved_markets
  Check pending_markets_count — when it reaches 0, all markets are settled (or compare resolved_markets_count == total_markets_count)

For individual events:
  GET /v1/events/{id}/result
  if status == "ended" → event finalised (fetch outcomes from /settlements)

8. Error Handling

Status	Error Code	Meaning	Action
400	`bad_request`	Invalid parameters	Fix your request
401	`unauthorized`	Missing/invalid API key	Check your key
404	`not_found`	Event doesn’t exist	Use `/v1/events` to find valid IDs
429	`rate_limited`	Too many requests	Wait `Retry-After` seconds
503	`service_unavailable`	Backend temporarily down	Wait `Retry-After` seconds

When a backend service is temporarily unavailable, the response includes which component is affected:

{
    "error": "service_unavailable",
    "message": "Data store temporarily unavailable",
    "component": "redis"
}

Component	Affects	Typical Recovery
`redis`	Live odds, scores, event data	10-60 seconds
`supabase`	Settlements, historical data	30-120 seconds

9. Odds Formats

All endpoints that return odds support ?odds_format=:

# European format — 2.50
curl "https://api.fieldfunded.com/v1/events?odds_format=decimal" \
  -H "X-API-Key: YOUR_API_KEY"

Supported on: /events, /live, /featured, /search, /events/{id}, /events/{id}/odds, /events/batch, /outrights/{id}.

10. Rate Limit Headers

Every response includes:

Header	Description
`X-RateLimit-Limit`	Your monthly quota
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	Unix timestamp when quota resets
`X-RateLimit-Warning`	⚠️ Appears at 50%, 80%, 95% usage

Monitoring endpoints (/ping, /health, /status) do not count against your monthly quota. They have their own fixed rate limits: 2 req/s and 120 req/h, equal for all plans.

Next Steps

Browse Sports

See all 30+ available sports

Live Events

Get real-time live data

Settlement

Automatic bet settlement

SDK Reference

Full TypeScript SDK docs

Getting Started

Reference Tables

1. Get Your API Key

2. Your First Request

Response Format

3. Official TypeScript SDK

Full SDK Documentation →

4. Common Patterns

Poll Live Scores (lightweight)

Search by Team Name

Batch Fetch Multiple Events

Auto-Settle Bets

5. Integration Flow

Simple Integration

White-Label Sportsbook

6. How to Integrate Bets — Complete Flow

Step 1 — Show odds to your user

Step 2 — User places a bet

Step 3 — Check the result

Step 4 — Credit the user

Cross-Sport Market ID Consistency

7. Settlement Feed Notes

Payload Modes

Recommended Polling Pattern

8. Error Handling

9. Odds Formats

10. Rate Limit Headers

Next Steps

Browse Sports

Live Events

Settlement

SDK Reference

Getting Started

Reference Tables

Documentation Index

​1. Get Your API Key

​2. Your First Request

​Response Format

​3. Official TypeScript SDK

Full SDK Documentation →

​4. Common Patterns

​Poll Live Scores (lightweight)

​Search by Team Name

​Batch Fetch Multiple Events

​Auto-Settle Bets

​5. Integration Flow

​Simple Integration

​White-Label Sportsbook

​6. How to Integrate Bets — Complete Flow

​Step 1 — Show odds to your user

​Step 2 — User places a bet

​Step 3 — Check the result

​Step 4 — Credit the user

​Cross-Sport Market ID Consistency

​7. Settlement Feed Notes

​Payload Modes

​Recommended Polling Pattern

​8. Error Handling

​9. Odds Formats

​10. Rate Limit Headers

​Next Steps

Browse Sports

Live Events

Settlement

SDK Reference

1. Get Your API Key

2. Your First Request

Response Format

3. Official TypeScript SDK

4. Common Patterns

Poll Live Scores (lightweight)

Search by Team Name

Batch Fetch Multiple Events

Auto-Settle Bets

5. Integration Flow

Simple Integration

White-Label Sportsbook

6. How to Integrate Bets — Complete Flow

Step 1 — Show odds to your user

Step 2 — User places a bet

Step 3 — Check the result

Step 4 — Credit the user

Cross-Sport Market ID Consistency

7. Settlement Feed Notes

Payload Modes

Recommended Polling Pattern

8. Error Handling

9. Odds Formats

10. Rate Limit Headers

Next Steps