SDK & Integration Guide

npm install @fieldfunded/sdk

const client = new FieldFundedSDK({
    apiKey: 'YOUR_KEY',         // Required
    host: 'custom-host.com',    // RapidAPI host (optional)
    baseUrl: 'https://...',     // Direct API URL (overrides host)
    timeout: 20000,             // Request timeout in ms (default: 20000)
    retries: 2,                 // Retries on 429/500 (default: 1)
});

const sports = await client.getSports();
console.log(sports.sports);
// [{ key: 'soccer', name: 'Soccer', active_events: 142, is_esport: false }, ...]

const leagues = await client.getLeagues({ sport: 'soccer' });
console.log(leagues.leagues);
// [{ slug: 'premier-league', name: 'Premier League', country: 'England', active_events: 10, live_events: 3 }, ...]

// All live soccer in England
const events = await client.getEvents({
    sport: 'soccer',
    country: 'england',
    status: 'live',
});

// Games starting in the next 2 hours
const upcoming = await client.getEvents({
    starts_within: '2h',
    sport: 'basketball',
});

// Events on a specific date
const tomorrow = await client.getEvents({
    date: '2026-04-16',
    league: 'premier-league',
});

// American odds format
const american = await client.getEvents({
    sport: 'soccer',
    odds_format: 'american',
});

const detail = await client.getEvent('12345678');
console.log(detail.markets);     // Full markets array (1,000+ on major events)
console.log(detail.scoreboard);  // Period/set/map scores
console.log(detail.sport_data);  // Serving indicators, power play, etc.

// Optimized endpoint — use for frequent polling (every 5-10s)
const scores = await client.getScores({ sport: 'soccer' });
for (const game of scores.scores) {
    console.log(`${game.home_team} ${game.score.home}-${game.score.away} ${game.away_team}`);
}

const results = await client.search('Barcelona', { limit: 5 });
console.log(results.events); // All upcoming/live Barcelona games

const batch = await client.getEventsBatch(['123', '456', '789']);
console.log(batch.events);     // Record<id, EventDetail>
console.log(batch.found);      // Number of events found (e.g. 2)
console.log(batch.requested);  // Number of IDs you sent (e.g. 3)

const result = await client.checkBet({
    selections: [{
        event_id: '123',
        market: 'Match Winner',
        outcome: 'Home',
        odds: 1.85,
        stake: 10,              // currency-agnostic — any numeric amount
        market_id: 340168,      // primary — recommended for 100% accuracy
        selection_id: 1824650,  // primary — recommended for 100% accuracy
    }],
});
console.log(result.results[0].result);  // 'won' | 'lost' | 'refund' | 'pending'
console.log(result.results[0].payout);  // 18.50 (when won, = stake × odds)

const parlay = await client.checkParlay({
    legs: [
        { event_id: '123', market: 'Match Winner', outcome: 'Home', odds: 1.85, market_id: 340168, selection_id: 1824650 },
        { event_id: '456', market: 'Over/Under 2.5', outcome: 'Over', odds: 1.92 },
    ],
    stake: 10,
});
console.log(parlay.payout.combined_odds);
console.log(parlay.payout.payout);

// Check settlements every 60 seconds
const settlements = await client.getSettlements({ limit: 10 });
for (const s of settlements.settlements) {
    console.log(`${s.event_id}: ${s.settlement_status} — ${s.resolved_markets_count}/${s.total_markets_count ?? '?'} markets (${s.pending_markets_count ?? '?'} pending)`);
}

// Get official result for a specific event (score-only)
const result = await client.getEventResult('12345678');
console.log(`Status: ${result.status}`); // 'ended', 'walkover', 'retired', etc.
if (result.score) {
    console.log(`Final Score: ${result.score.home}-${result.score.away}`);
}

// For market-level resolutions, use getSettlements()
const eventSettlements = await client.getSettlements({ event_id: '12345678' });

// Outright/futures settlements (also automatic)
const outrightSettlements = await client.getOutrightSettlements({ sport: 'soccer' });

// List tournaments with outright markets
const outrights = await client.getOutrights({ sport_id: '124' });

// Get selections and odds (supports odds_format)
const detail = await client.getOutright('12345', { odds_format: 'american' });
console.log(detail.events[0].markets[0].selections[0].odds);

const usage = await client.getUsage();
console.log(`${usage.current.this_month} / ${usage.limits.per_month} requests used`);
console.log(`${usage.current.month_remaining} remaining`);

// Per-endpoint breakdown
const endpoints = await client.getUsageEndpoints();
console.log(endpoints.endpoints);
// [{ path: '/events', count: 142 }, { path: '/live', count: 58 }, ...]

// Active warnings
const warnings = await client.getUsageWarnings();
if (warnings.warnings.length > 0) {
    console.warn('[!]', warnings.warnings[0].message);
}

const ping = await client.ping();       // { pong: true, timestamp: 1234567890 }
const health = await client.health();   // System health, data freshness
const status = await client.status();   // Live/prematch counts

import {
    FieldFundedSDK,
    RateLimitError,
    AuthenticationError,
    NotFoundError,
    BadRequestError,
    ServiceUnavailableError,
} from '@fieldfunded/sdk';

try {
    const events = await client.getEvents();
} catch (err) {
    if (err instanceof RateLimitError) {
        console.log(`Rate limited. Retry in ${err.retryAfter}s`);
    } else if (err instanceof ServiceUnavailableError) {
        console.log(`Service degraded (${err.component}). Retry in ${err.retryAfter}s`);
    } else if (err instanceof AuthenticationError) {
        console.log('Invalid API key');
    } else if (err instanceof NotFoundError) {
        console.log('Event not found');
    } else if (err instanceof BadRequestError) {
        console.log(`Invalid request: ${err.message}`);
    }
}

import requests

def get_live_scores(api_key):
    url = "https://api.fieldfunded.com/v1/live"
    headers = { "X-API-Key": api_key }
    response = requests.get(url, headers=headers)
    return response.json()

# Settlement polling
def poll_settlements(api_key, limit=20):
    url = f"https://api.fieldfunded.com/v1/settlements?limit={limit}"
    headers = { "X-API-Key": api_key }
    response = requests.get(url, headers=headers)
    data = response.json()
    for s in data.get("settlements", []):
        print(f"{s['event_id']}: {s['settlement_status']} — {s['resolved_markets_count']}/{s.get('total_markets_count', '?')} markets ({s.get('pending_markets_count', '?')} pending)")
    return data

package main

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

func main() {
    apiKey := "YOUR_API_KEY"
    url := "https://api.fieldfunded.com/v1/live"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("X-API-Key", apiKey)

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

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}