Getting Started

What is @betswirl/sdk-core?

The @betswirl/sdk-core is a VanillaJS library that provides direct access to the BetSwirl protocol. It’s designed to be flexible and can be used in various ways depending on your project needs:

With Wagmi clients (Wagmi) for Node.js multi-chain applications
With native Viem client for Node.js applications
Without a client for Node.js applications
Using function data for AI agents and frontends (React, Vue, etc)

Why would you need @betswirl/sdk-core?

As a dApp/Mini App

Fetching bets history - Get user betting activity and results
Fetching freebets - Retrieve available freebets for users
Fetching leaderboards - Display competitive rankings and tournaments
Utilities - Helper functions for formatting, etc
Chains & data - Access to supported networks and protocol data

Note: For betting processes, consider using the @betswirl/ui-react SDK as an additional package. It provides a full React-based solution that would save you a lot of time, but you’ll still need the core SDK as a dependency.

As an agent

Function data - Get encoded transaction data
Placing bets - Execute betting transactions programmatically
Utilities - Helper functions for bet validation, requirements checking, etc
Chains & data - Access to supported networks and protocol data

Installation


npm i @betswirl/sdk-core viem @apollo/client

Usage

1. With an external BetSwirl client

Using the SDK with an external BetSwirl client helps you reduce your codebase and use your favorite compatible viem wallet.

Available external clients:

Wagmi (@betswirl/wagmi-provider)

The example below uses the BetSwirl Wagmi client:


import { createConfig } from "@wagmi/core";
import { initWagmiBetSwirlClient} from "@betswirl/wagmi-provider";
 
/* Create the Wagmi config */
const wagmiConfig = createConfig(...)
 
/* Init Wagmi BetSwirl client */
const wagmiBetSwirlClient = initWagmiBetSwirlClient(wagmiConfig, {
  affiliate: "0x...",
  gasPriceType: GAS_PRICE_TYPE.FAST,
  ...
});
 
/* Use the client */
const casinoGames = await wagmiBetSwirlClient.getCasinoGames(false, 137);
...
wagmiBetSwirlClient.playDice(77, ...)
...

2. With the native BetSwirl client (Viem)

Using the SDK with the native BetSwirl Viem client helps you reduce your codebase. The walletClient is optional if you only need to read data.


import { http, createWalletClient, createPublicClient } from "viem";
import { initViemBetSwirlClient } from "@betswirl/sdk-core";
 
/* Create the Viem clients */
const account = privateKeyToAccount("0x...");
const transport = http("https://...")
 
const publicClient = createPublicClient({
  chain: casinoChain.viemChain,
  transport,
});
 
const walletClient = createWalletClient({
  chain: casinoChain.viemChain,
  transport,
  account,
})
 
/* Create the native BetSwirl client */
const viemBetSwirlClient = initViemBetSwirlClient(publicClient, walletClient, {
  chainId: 137,
  affiliate: "0x...",
  gasPriceType: GAS_PRICE_TYPE.FAST,
  ...
})
 
/* Use the native BetSwirl client */
const casinoGames = await viemBetSwirlClient.getCasinoGames(false);
...
viemBetSwirlClient.playDice(77, ...)
...

3. Without a client (only a wallet)

Using the SDK without a client doesn’t let you centralize all your options in one place. It’s more appropriate for projects using only one or two SDK functions. The example below uses the BetSwirl viem wallet, which is native to the SDK. The walletClient is optional if you only need to read data.


import { http, createWalletClient, createPublicClient } from "viem";
import { initViemBetSwirlClient } from "@betswirl/sdk-core";
 
/* Create the Viem clients */
const account = privateKeyToAccount("0x...");
const transport = http("https://...")
 
const publicClient = createPublicClient({
  chain: casinoChain.viemChain,
  transport,
});
 
const walletClient = createWalletClient({
  chain: casinoChain.viemChain,
  transport,
  account,
})
 
/* Create the native BetSwirl wallet */
const viemBetSwirlWallet = new ViemBetSwirlWallet(publicClient, walletClient)
 
/* Use functionalities with the wallet*/
const casinoGames = await getCasinoGames(viemBetSwirlWallet, false);
...
placeDiceBet(viemBetSwirlWallet, 77, ...)
...

4. Using function data

Getting function data doesn’t require you to use a client or a wallet. It’s particularly useful for frontend projects (React, Vue, etc) or AI agents plugins (Goat, AgentKit, Moxie, etc). The example below shows the placeBet function used in the Moxie BetSwirl plugin to place a bet.


import { MoxieWalletClient } from "@moxie-protocol/moxie-lib/src/wallet";
import {
    CASINO_GAME_TYPE,
    type CasinoChainId,
    GameEncodedInput,
    getPlaceBetFunctionData,
} from "@betswirl/sdk-core";
 
export async function placeBet(
    moxieWalletClient: MoxieWalletClient,
    game: CASINO_GAME_TYPE,
    gameEncodedInput: GameEncodedInput,
    gameMultiplier: number,
    casinoGameParams: {
        betAmount: bigint;
        betToken: Hex;
        betCount: number;
        receiver: Hex;
        stopGain: bigint;
        stopLoss: bigint;
    }
) {
    const chainId = Number(
        (await moxieWalletClient.wallet.provider.getNetwork()).chainId
    ) as CasinoChainId;
    
    // getBetRequirements is a custom function built in the BetSwirl plugin
    const betRequirements = await getBetRequirements(
        moxieWalletClient,
        game,
        casinoGameParams.betToken,
        gameMultiplier
    );
 
    if (!betRequirements.isAllowed) {
        throw new Error(`The token isn't allowed for betting`);
    }
 
    if (casinoGameParams.betAmount > betRequirements.maxBetAmount) {
        throw new Error(
            `Bet amount should be less than ${betRequirements.maxBetAmount}`
        );
    }
    if (casinoGameParams.betCount > betRequirements.maxBetCount) {
        throw new Error(
            `Bet count should be less than ${betRequirements.maxBetCount}`
        );
    }
 
    const functionData = getPlaceBetFunctionData(
        {
            betAmount: casinoGameParams.betAmount,
            game,
            gameEncodedInput: gameEncodedInput,
            receiver: casinoGameParams.receiver,
            betCount: casinoGameParams.betCount,
            tokenAddress: casinoGameParams.betToken,
            stopGain: casinoGameParams.stopGain,
            stopLoss: casinoGameParams.stopLoss,
        },
        chainId
    );
 
    try {
        const gasPrice =
            ((await moxieWalletClient.wallet.provider.getFeeData()).gasPrice *
                120n) /
            100n;
 
        // getChainlinkVrfCost is a custom function built in the BetSwirl plugin
        const vrfCost =
            (await getChainlinkVrfCost(
                moxieWalletClient,
                game,
                casinoGameParams.betToken,
                casinoGameParams.betCount,
                gasPrice
            ))
            
        const { hash: betHash } = await moxieWalletClient.sendTransaction(
            chainId.toString(),
            {
                toAddress: functionData.data.to,
                data: functionData.encodedData,
                value: functionData.extraData.getValue(vrfCost)
                gasPrice: Number(gasPrice),
            }
        );
 
        return betHash as Hex;
    } catch (error) {
        throw new Error(
            `An error occured while placing the bet: ${error.shortMessage || error.message}`
        );
    }
}