Reconciliation

Reconciliation is how you verify that FAST's shadow ledger matches your sportsbook's records. Think of it as a daily health check - making sure every bet your system processed also exists in FAST, and vice versa.

Why Reconcile?

Network failures, timeouts, or bugs can cause bets to be recorded in your system but not in FAST (or the other way around). Reconciliation catches these gaps before they become problems.

How It Works

1. Pull FAST's Records

curl -H "X-API-Key: your-api-key" \
  "https://api.fundedfast.eu/v1/reconciliation/user-001?from=2026-01-01&to=2026-01-31"

This returns every bet event FAST has for that user in the date range, including your externalBetId for cross-referencing.

2. Compare with Your Records

For each bet in your system, check if FAST has a matching externalBetId. For each bet in FAST, check if your system has a matching record.

// Simple reconciliation example
async function reconcile(userId, date) {
  // Get FAST's records
  const fastRes = await fetch(
    `${API_URL}/reconciliation/${userId}?from=${date}&to=${date}`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  const fastData = await fastRes.json();

  // Get your records
  const yourBets = await db.getBetsForUser(userId, date);

  // Find mismatches
  const fastIds = new Set(fastData.betEvents.map(b => b.externalBetId));
  const yourIds = new Set(yourBets.map(b => b.ticketId));

  const missingInFast = [...yourIds].filter(id => !fastIds.has(id));
  const missingInYours = [...fastIds].filter(id => !yourIds.has(id));

  if (missingInFast.length > 0) {
    console.log('Bets in your system but not in FAST:', missingInFast);
    // These need to be re-sent to FAST
  }
}

3. Fix Gaps

If bets are missing from FAST, re-send them through the normal POST /v1/bets endpoint. FAST uses externalBetId for deduplication - sending the same bet twice is safe.

Backfilling Missing Transactions

Yes, operators can backfill missing bets. Just send them through the normal API:

# Re-send a missing placed bet
curl -X POST https://api.fundedfast.eu/v1/bets \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-001",
    "externalBetId": "BET-MISSING-001",
    "stakeAmount": 5.00,
    "odds": 2.10,
    "status": "placed",
    "isCashOut": false,
    "eventTimestamp": "2026-01-15T14:30:00Z"
  }'

# Then send the settlement
curl -X POST https://api.fundedfast.eu/v1/bets \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-001",
    "externalBetId": "BET-MISSING-001",
    "stakeAmount": 5.00,
    "odds": 2.10,
    "status": "settled-won",
    "settlementAmount": 10.50,
    "isCashOut": false,
    "eventTimestamp": "2026-01-15T15:00:00Z"
  }'

Include the original eventTimestamp so FAST records the bet at the correct time, not the current time.

Manual Bet Settlement

If a bet was sent to FAST as placed but the settlement was lost, the operator can settle it manually from the backoffice. To find such bets, list the ones still open: GET /v1/admin/bet-events?status=placed returns only placements that have no settlement or void row yet (the ledger is append-only, so a settled bet keeps its placed row; the filter leaves those out). Add userId to narrow it to one player.

# Settle a specific bet as won or lost
curl -X POST https://api.fundedfast.eu/v1/admin/bet-events/BET_EVENT_ID/settle \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "won"}'

Or settle multiple bets at once:

curl -X POST https://api.fundedfast.eu/v1/admin/bet-events/bulk-settle \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "settlements": [
      {"betEventId": "uuid-1", "outcome": "won"},
      {"betEventId": "uuid-2", "outcome": "lost"}
    ]
  }'

Reconciliation Flags

When FAST or the operator detects a discrepancy, it creates a reconciliation flag. Flags are visible in the operator backoffice under "Reconciliation" and via the API.

What Creates a Flag?

• FAST detects a bet event that doesn't match expected patterns
• A settlement contradicts an earlier one for the same externalBetId (won after lost, lost after won, or a settlement after a void). FAST stores it as flagged with reason conflicting_settlement and leaves the balance unchanged
• A settlement does not match the accepted placement: a different stake or odds, or a payout above stake x odds. FAST stores it as flagged with reason settlement_mismatch and leaves the balance unchanged
• A void reverses a settlement that had already ended the challenge or funded account; the money moves back but the account stays closed until you review it
• An operator manually flags a suspicious transaction
• Automated reconciliation scripts detect mismatches

Viewing Flags

# List open flags
curl -H "Authorization: Bearer YOUR_JWT" \
  "https://api.fundedfast.eu/v1/admin/reconciliation/flags?status=open"

Each flag includes:

• The user ID and bet event ID
• A description of the discrepancy
• Status: open or resolved
• Who flagged it and when

Resolving Flags

After investigating and fixing the discrepancy (by backfilling the missing bet or correcting the settlement), mark the flag as resolved in the backoffice.

Recommended Schedule

Frequency	What to Check
Daily	Compare bet counts for all active users
Weekly	Full reconciliation of all bet IDs and settlement amounts
Monthly	Verify challenge completion and funded account balances match

Tips

• Always include eventTimestamp when backfilling so the bet is recorded at the correct time
• Use the staging environment to test your reconciliation script before running it against production
• Log the correlationId from every FAST response - you'll need it when investigating discrepancies
• Set up alerts for when your reconciliation script finds mismatches