Quickstart

Time to first call: ~5 min

This guide takes you from an installed package to a live sportsbook call. Follow the steps in order — each one builds on the session opened in step two.

Show samples as

React

Flutter

Vanilla JS

Install the package

Installation guide

The SDK is published to the private BetChain registry (sdk.betconstruct.com/npm), so configure registry access before installing.

.sh

npm install @softconstruct/betchain-core-client

Registry access firstWithout an authenticated .npmrc the install fails with a 401. Set the @softconstruct scope and your BetChain license key before running the command.

Open the session

initSwarmSession method

Open the session once, when your application starts — it establishes the Swarm socket and configures the content + casino clients. Every other call reuses it.

.ts
1import { useInitSDK } from '@softconstruct/betchain-core-client/hooks';2 3const useBetchainSession = () => {4  useInitSDK({5    version: 2,6    source: 42,7    platform: 'desktop',8    siteId: 18749451,9    language: 'eng',10    releaseDate: '2024-01-01',11    apiUrl: 'https://cms-api.your-host.com',12    socketUrl: 'wss://eu-swarm-newm.betcoswarm.com',13    onSessionSuccess: (response) => {14      console.log('Session ready', response.data);15    },16    onSessionError: ({ message }) => {17      console.error('Session failed', message);18    }19  });20};

Call it onceuseInitSDK is a hook, so call it from a component or a custom hook mounted once at the app root — never per feature component. The session is global, and a second initialization replaces the first.

Parameters

Name	Type	Required	Description
`source`	`number`	Yes	Platform source identifier, provided by your account manager.
`siteId`	`number`	Yes	Your operator site identifier.
`language`	`string`	Yes	Session language code, for example eng.
`releaseDate`	`string`	Yes	Client release date, sent with the session handshake.
`socketUrl`	`string`	Yes	WebSocket endpoint for your region.
`onSessionSuccess`	`(data: RequestSessionMessage) => void`	Yes	Called once the session is established. Carries the session payload.
`onSessionError`	`({ message }) => void`	Yes	Called when the handshake fails.
`onReconnectSuccess`	`() => void`	No	Called after a dropped connection is restored.
`reCaptchaPlatform`	`'ios' \| 'android'`	No	Set in native apps, so captcha is verified with the Enterprise mobile SDK.

Read data once

Pass the method reference to useSwarmGetOnce and the hook infers the response type for you.

.ts
1import { getCompetitions } from '@softconstruct/betchain-core-client/swarm';2import { useSwarmGetOnce } from '@softconstruct/betchain-core-client/hooks';3 4const useCompetitions = () => {5  const { data, isLoading, hasError, errorMessage } = useSwarmGetOnce(6    getCompetitions, {7      params: {8        isLive: true,9        language: 'eng',10        sportAlias: 'Soccer',11        competitionLimit: 1012      },13      dependencies: []14    });15 16  return { data, isLoading, hasError, errorMessage };17};

Response

{
  code: 0,
  hasError: false,
  data: {
    data: {
      competition: {
        '538': {
          id: 538,
          name: 'Premier League',
          order: 1,
          sport: {
            alias: 'Soccer'
          },
          region: {
            alias: 'England'
          }
        }
      }
    }
  }
}

Subscribe to live updates

useSwarmSubscription keeps a WebSocket subscription open and replaces data in place as the platform pushes updates.

.ts
1import { subscribeToLiveEventsWithSport } from '@softconstruct/betchain-core-client/swarm';2import { useSwarmSubscription } from '@softconstruct/betchain-core-client/hooks';3 4const useLiveSoccerEvents = () => {5  const { data, isLoading, hasError } = useSwarmSubscription(6    subscribeToLiveEventsWithSport, {7      params: {8        sportAlias: 'Soccer',9        marketDisplayKeys: ['FIRST GOAL']10      },11      dependencies: []12    }13  );14 15  return { data, isLoading, hasError };16};

Latest pushstreaming

{
  sport: {
    '42': {
      alias: 'WaterPolo',
      region: {
        '20042': {
          name: 'Europe'
        }
      }
    }
  }
}

UnsubscribingBoth SDKs clean up automatically on unmount — the React hook, and Flutter’s SwarmFeedBuilder (betchain_core_flutter). Subscribing directly: in web keep the rid from the listener payload and call unsubscribeByRid; in Flutter call feed.cancel() — it stops delivery and sends unsubscribe_bulk.

Handle errors

Requests resolve with hasError and message instead of throwing, so check them before using data.

.ts
1import { useEffect } from 'react';2import { getCompetitions } from '@softconstruct/betchain-core-client/swarm';3import { useSwarmGetOnce } from '@softconstruct/betchain-core-client/hooks';4 5const useCompetitions = () => {6  const { data, hasError, errorMessage, isLoading } = useSwarmGetOnce(7    getCompetitions, {8      params: { sportAlias: 'Soccer', language: 'eng' },9      dependencies: []10    });11 12  useEffect(() => {13    if (hasError) {14      console.error('Swarm request failed:', errorMessage);15    }16  }, [hasError, errorMessage]);17 18  return { data, isLoading, hasError };19};

Common error codes

Code	Message	What to check

`1`	Bad request	Check the parameter names and types you sent.
`5`	Session not found	The session was not initialized, or it expired. Re-run the handshake.
`12`	Invalid credentials	Login failed or the stored auth token is no longer valid.
`20`	Insufficient balance	The player cannot cover the stake. Surface this to the user.
`22`	Limit reached	A responsible-gaming or partner limit blocked the operation.

Full error code reference

What next

FAQsCommon integration questions and answers.reCAPTCHA & TurnstileBot protection for login and registration flows.Migration guideBreaking changes between v1 and v2.

Was this page helpful?

PreviousOverview Next FAQs