Dictionary

• FbtServer - integration on the side of NodeArt, working name
• Provider - platform/API with which FbtServer will integrate
• User - user of Provider's platform
• Event - one of the outcomes of the match on which odds User places a bet(e.g. home team wins, match ends in a draw, away team wins 2-1, etc.)
• Slip - a list of events on which User makes a bet

Assumptions

Provider already has internal structure and formats which it already uses internally(e.g. ids, data structures, etc.) and in order to ease integration, FbtServer will adapt to already existing formats as much as possible. However, all new developments are subject to change.

Overview

We can split API into 2 distinct flows:

1. Starting user session & making bets. General flow can be explained by the following diagram:

Relevant sections:

• Session Initialization
• Making a Bet

2. FbtServer retrieving data updated from the Provider

This API is implemented on the side of Provider and allows FbtServer to retrieve information about business entities

Relevant Sections:

• Data Syncing

API

Request and response messages are sent in JSON format using HTTP POST protocol.

Auth

All requests will require basic authorization. This requires supplying Authorization header with content Basic followed by the base64-encoded user:password string. Additionally, request/response body can be encrypted or contain its own hash if requested by the Provider.

Error handling

In case request can not be successfully processed, endpoint must return response containing details of an error. Error response must have 4xx/5xx HTTP status code and contain errorCode to indicate type of an error. It may also include any other details that may help with resolving an issue from the requester's side.

Potential error codes(to be discussed):

interface {
  error: {
    errorCode: string;
    [s: string]: unknown;
  }
}

Examples:

{
  "error": {
    "errorCode": "INTERNAL_SERVER_ERROR"
  }
}
{
  "error": {
    "errorCode": "BET_MIN_LIMIT",
    "limit": 500
  }
}
{
  "error": {
    "errorCode": "BET_INSUFFICIENT_FUNDS",
    "walletAmount": 1570,
    "denomination": 2,
    "currency": "EUR"
  }
}
{
  "error": {
    "errorCode": "BAD_REQUEST",
    "message": "Could not parse request body",
  }
}
{
  "error": {
    "errorCode": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": [
      {
        "path": "userId",
        "message": "Value is missing"
      },
      {
        "path": "amount",
        "value": -12.76,
        "message": "Value must be positive"
      }
    ]
  }
}

Session Initialization

Create a new session with which user can make bets.

Method: POST Endpoint: /api/v1/session/init

Request

interface {
  userId: string;
  currency: string;
  locale: string;
}

Example:

{
  "userId": "cdaae822-6747-401b-b268-e3547ee0fdbe",
  "currency": "EUR",
  "locale": "de"
}

Response

interface {
  redirectUrl: string;
  sessionId: string;
}

Example:

{
  "redirectUrl": "https://some.domain.name/path/to/iframe?some=internal&session=paramaters",
  "sessionId": "9f3ce342-17c8-416c-a51a-a8145285bb51"
}

Making a Bet

Place a bet for a user. User can make multiple bets within a single session.

Method: POST Endpoint: /api/v1/bet

Request

interface {
  userId: string;
  sessionId: string;
  idempotencyId: string;
  timestamp: integer;
  currency: string;
  denomination: integer;
  amount: integer;
  slip: {
    eventId: string;
    stake: integer;
    event?: {
      matchId: string;
      type: string;
      odds: integer;
    }
  }[];
}

Example:

{
  "userId": "cdaae822-6747-401b-b268-e3547ee0fdbe",
  "sessionId": "9f3ce342-17c8-416c-a51a-a8145285bb51",
  "idempotencyId": "57a743c3-8269-4b43-bfd0-1d65973fcb1d",
  "timestamp": 1771854042536,
  "currency": "USD",
  "denomination": 2,
  "amount": 1275,
  "slip":[
    {
      "eventId": "23492342",
      "stake": 3,
      "event": {
        "id": "23492342",
        "matchId": "523543",
        "type": "0-0",
        "odds": 3.74,
        "active": true,
        "updatedAt": 1772014764187
      }
    },
    {
      "eventId": "4564362",
      "stake": 4,
      "event": {
        "id": "4564362",
        "matchId": "523205",
        "eventType": "1",
        "odds": 5.12,
        "active": true,
        "updatedAt": 1772014764187
      }
    },
    {
      "eventId": "4564094",
      "stake": 2,
      "event": {
        "id": "4564094",
        "matchId": "523863",
        "eventType": "X/X",
        "odds": 2.28,
        "active": true,
        "updatedAt": 1772014764187
      }
    }
  ],
}

Response

interface {
  betId: string;
}

Example:

{
  "betId": "7b513ad7-1d6d-4c5f-a0e8-ba4091357099"
}

Data Syncing

In order for FbtServer to show relevant information to the user, it needs to retrieve a list of business entities such as:

• competitions(e.g. Premier League, Bundesliga, La Liga, etc.)
• teams(e.g. Arsenal, Brighton, Chelsea, etc.)
• matches(e.g. Arsenal vs Brighton at 2026.01.01 12:30 in Premier League)
• events(e.g. match with id 5269 ends in a draw with odds of 2.56)

It is critical that FbtServer operates with up-to-date entities in order to avoid situations where for example, odds for an event shown to the user differ from the ones Provider has.

One of the ways to achieve that is for FbtServer to make repeated API calls providing timestamp of the last time one of the business entities was updated in which case Provider will return a list of entities that were updated after that point of time. Additionally, to handle use-case where id for a non-synced entity is returned in the response of another entity, API will provide a way to retrieve a list of entities by specifying their ids in the request. In case such implementation will cause significant strain on Provider's API, other options can be discussed.

API for all entities work identically, so when using competition in the following examples, same logic can be applied to other entities.

Request

Method: GET Endpoint: /api/v1/competitions

Query Parameters:

Examples:

1. GET https://domain.com/api/v1/competitions?from=1772014764187&limit=100&page=1
2. GET https://domain.com/api/v1/competitions?ids=32,134,52,17&limit=50&page=2

Response

interface {
  data: {
    id: string;
    name: string;
    logo: string;
    updatedAt: integer;
  }[];
  paging: {
    page: integer;
    limit: integer;
    total: integer;
  };
}

Competition

Example:

{
  "id": "134",
  "name": "Premier League",
  "logo": "https://some.domain.name/path/to/logo/image",
  "updatedAt": 1762018623661
}

Team

Example:

{
  "id": "37142",
  "name": "Arsenal",
  "logo": "https://some.domain.name/path/to/logo/image",
  "updatedAt": 1771018674776
}

Match

Example:

{
  "id": "523543",
  "homeTeamId": "37142",
  "awayTeamId": "18356",
  "date": 1774456200000,
  "updatedAt": 1771718730433
}

Event

Example:

{
  "id": "23492342",
  "matchId": "523543",
  "type": "0-0",
  "odds": 3.74,
  "active": true,
  "updatedAt": 1772014764187
}