Bet Events

Every bet placed or settled by a user with an active challenge or funded account must be sent to FAST. FAST provides two endpoints: synchronous validation and asynchronous ingestion.

Synchronous Validation

Use POST /v1/bets/validate when you need an immediate accept/reject decision before confirming the bet in your sportsbook.

curl -X POST https://api.fundedfast.eu/v1/bets/validate \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-001",
    "externalBetId": "BET-12345",
    "stakeAmount": 5.00,
    "odds": 2.10,
    "betTypeIdentifier": "single",
    "status": "placed",
    "isCashOut": false
  }'

Accepted Response

{
  "validationResult": {
    "status": "accepted",
    "reasonCodes": []
  },
  "correlationId": "uuid"
}

Rejected Response

{
  "validationResult": {
    "status": "rejected",
    "reasonCodes": ["max_stake_exceeded", "odds_limit_exceeded"]
  },
  "correlationId": "uuid"
}

The reasonCodes array can contain multiple codes when a bet violates more than one rule. See Rejection Codes for the full list.

Bet Ingestion

Use POST /v1/bets to send bet events for ledger tracking. This endpoint handles both placement and settlement events.

In async mode, the endpoint returns 202 Accepted immediately and processes the event in the background via the BullMQ queue. In sync mode, it processes the event and returns the validation result.

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-12345",
    "stakeAmount": 5.00,
    "odds": 2.10,
    "betTypeIdentifier": "single",
    "status": "placed",
    "isCashOut": false
  }'

Won Settlement

Include settlementAmount - the total return to the user (stake + profit).

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-12345",
    "stakeAmount": 5.00,
    "odds": 2.10,
    "status": "settled-won",
    "settlementAmount": 10.50,
    "isCashOut": false
  }'

Lost 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-12346",
    "stakeAmount": 5.00,
    "odds": 1.80,
    "status": "settled-lost",
    "isCashOut": false
  }'

Voided Bet

A settlement only moves a balance for a bet FAST accepted. Settle every bet you took anyway: one FAST rejected, or one placed before the user bought a challenge, is recorded with no_accepted_placement and changes nothing. A void of such a bet changes nothing either and is answered accepted, as any void is.

A challenge passes the moment its target, bets and active days are met, even with bets still open, and the player can move on to the funded account straight away. A bet still open at that point settles later with program_closed: it is recorded under the challenge that accepted it and moves neither that challenge nor the funded account.

A void of an unsettled bet is recorded but ignored by the rules engine: no balance change, no counter increment. A void that arrives after the bet was settled reverses that settlement's balance effect (a win's credit is taken back, a loss is restored and removed from that day's loss total). If the settlement had already ended the account (for example a drawdown failure), the account stays in its terminal state and FAST raises a reconciliation flag for you to review.

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-12347",
    "stakeAmount": 5.00,
    "odds": 2.00,
    "status": "voided"
  }'

Bet Statuses

Status	Description	Balance Effect
placed	Bet accepted, not yet settled	Stake deducted (reserved)
settled-won	Bet settled as a win	Settlement amount credited
settled-lost	Bet settled as a loss	No additional change (stake already deducted)
voided	Bet cancelled	None if unsettled; reverses the settlement if already settled

Duplicates and Conflicting Settlements

Events are keyed on externalBetId + status. Resending an event FAST already has (same externalBetId, same status) is a no-op that returns success, so retries are safe.

A settlement that contradicts an earlier one (won after lost, lost after won, or any settlement after a void) does not touch the balance. It is stored with status flagged and reason conflicting_settlement, and opens a reconciliation flag for you to resolve.

A settlement must also match the placement FAST accepted: the same stakeAmount and odds, and a settlementAmount no larger than stake x odds. One that does not is stored as flagged with reason settlement_mismatch, leaves the balance unchanged and opens a reconciliation flag.

Rate Limit

POST /v1/bets accepts at most 30 events per user per minute. Placements and settlements both count against it, and so does each item in POST /v1/bets/batch (an over-limit item fails individually). Over the limit, FAST answers 429 with "error": "rate_limited" and no Retry-After header; back off and resend once the 60-second window has passed.

The settlementAmount Field

For settled-won events, settlementAmount is the total return including the original stake. FAST uses this to calculate the profit and update the shadow ledger balance.

Example: a 5.00 EUR stake at 2.10 odds returns 10.50 EUR. The settlementAmount is 10.50, and the net profit is 5.50.

For settled-lost events, settlementAmount is not required (the stake was already deducted on placement).

Integration Modes

The integration mode is configured per tenant:

• Sync: Call /v1/bets/validate before accepting a bet, then /v1/bets for settlement. FAST returns accept/reject immediately.
• Async: Send all events to /v1/bets. FAST returns 202 Accepted and processes in the background. Rejected bets are silently ignored.

Toggle the mode via PUT /v1/admin/integration-mode in the operator backoffice.