> ## 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.

# Quickstart

> Get live odds, scores, and settlements running in under 5 minutes

## 1. Get Your API Key

<Tabs>
  <Tab title="RapidAPI (recommended)">
    1. Visit [FieldFunded on RapidAPI](https://rapidapi.com/fieldfunded/api/fieldfunded-sports-api)
    2. Subscribe to a plan (Free tier = 10,000 req/mo)
    3. Copy your `X-RapidAPI-Key` from the dashboard

    ```http theme={null}
    X-RapidAPI-Key: YOUR_API_KEY
    X-RapidAPI-Host: fieldfunded-sports-api.p.rapidapi.com
    ```
  </Tab>

  <Tab title="Direct API Key">
    Contact [support@fieldfunded.com](mailto:support@fieldfunded.com) for a direct key.

    ```http theme={null}
    X-API-Key: YOUR_API_KEY
    ```
  </Tab>
</Tabs>

| 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

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.fieldfunded.com/v1/sports" \
    -H "X-API-Key: YOUR_API_KEY" | jq
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.fieldfunded.com/v1/sports', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(`${data.total} sports available`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.fieldfunded.com/v1/sports',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  data = response.json()
  for sport in data["sports"]:
      print(f"{sport['name']}: {sport['active_events']} events ({sport['live_events']} live)")
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {
  	url := "https://api.fieldfunded.com/v1/sports"
  	req, _ := http.NewRequest("GET", url, nil)
  	req.Header.Set("X-API-Key", "YOUR_API_KEY")

  	client := &http.Client{}
  	resp, _ := client.Do(req)
  	defer resp.Body.Close()

  	body, _ := ioutil.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

### Response Format

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

```json theme={null}
{
    "events": [...],
    "total": 142,
    "limit": 50,
    "offset": 0
}
```

Error responses use a consistent schema:

```json theme={null}
{
    "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.

```bash theme={null}
npm install @fieldfunded/sdk
```

```typescript theme={null}
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}`);
```

<Card title="Full SDK Documentation →" icon="npm" href="/sdk">
  25 typed methods, error classes, configuration options, and all usage examples.
</Card>

***

## 4. Common Patterns

### Poll Live Scores (lightweight)

```bash theme={null}
# 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

```bash theme={null}
curl -s "https://api.fieldfunded.com/v1/search?q=Arsenal" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Batch Fetch Multiple Events

```bash theme={null}
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

```bash theme={null}
# 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

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

### White-Label Sportsbook

```
1. GET /v1/events?status=prematch   → Populate your event listing
2. GET /v1/live                     → Discover live events
3. GET /v1/events/{id}              → Full odds for user's selected event
4. POST /v1/bets/check              → Resolve individual bets
5. POST /v1/bets/check-parlay       → Resolve multi-leg parlays
6. 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         |

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

<Tip>
  **`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.
</Tip>

### Step 3 — Check the result

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

```bash theme={null}
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
    }]
  }'
```

```json Response theme={null}
{
  "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.

<Note>
  **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.
</Note>

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

### Cross-Sport Market ID Consistency

`market_id` values are **consistent across all fixtures within the same sport**. For example, `market_id: 36` maps to 1X2 in *every* soccer match — whether it's Hamburger SV vs. FC Union Berlin or Corinthians vs. CA Peñarol.

<Card title="View Market ID Tables →" icon="table" href="/reference/market-types#cross-sport-market-id-consistency">
  See the full reference tables for consistent market IDs across major sports.
</Card>

***

## 7. Settlement Feed Notes

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

* 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:

```json theme={null}
{
    "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=`:

<CodeGroup>
  ```bash Decimal (default) theme={null}
  # European format — 2.50
  curl "https://api.fieldfunded.com/v1/events?odds_format=decimal" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```bash American theme={null}
  # US format — +150 or -118
  curl "https://api.fieldfunded.com/v1/events?odds_format=american" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```bash Fractional theme={null}
  # UK format — 3/2
  curl "https://api.fieldfunded.com/v1/events?odds_format=fractional" \
    -H "X-API-Key: YOUR_API_KEY"
  ```
</CodeGroup>

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 |

<Note>
  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.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Browse Sports" icon="futbol" href="/api-reference/sports/get-sports">
    See all 30+ available sports
  </Card>

  <Card title="Live Events" icon="bolt" href="/api-reference/live/get-live-events">
    Get real-time live data
  </Card>

  <Card title="Settlement" icon="check" href="/api-reference/settlement/check-bets">
    Automatic bet settlement
  </Card>

  <Card title="SDK Reference" icon="npm" href="/sdk">
    Full TypeScript SDK docs
  </Card>
</CardGroup>