Skip to Content
Futures TradingAPI Reference

API Reference

Complete reference for the Futures exports from @maktubbet/sdk/futures.

Exports

// Main component
import { FuturesGameSDK } from '@maktubbet/sdk/futures'
 
// Types
import type {
  FuturesGameSDKProps,
  GameCurrency,
  GameUser,
  ToastData,
  GameTheme,
  Instrument,
  Position,
  Timeframe,
} from '@maktubbet/sdk/futures'

Also available from the root package:

import { FuturesGameSDK } from '@maktubbet/sdk'

FuturesGameSDK

The main component. Renders the full trading interface.

<FuturesGameSDK
  accessToken="Bearer ..."
  user={{ betCount: 0, isAuthenticated: true }}
  updateBalance={(balance) => setBalance(balance)}
  onAuthRequired={() => router.push('/login')}
  currency={{ code: 'USD', prefix: '$', rate: 1 }}
  language="en"
  logo={<img src="/logo.svg" />}
  symbol="BTC"
  theme={{
    backgroundDark: '#0D1117',
    backgroundDarkLight: '#161B22',
    buttonColor: '#10b981',
    borderRadius: '8px',
  }}
/>

FuturesGameSDKProps

PropTypeRequiredDefaultDescription
accessTokenstring | null✅—JWT token for authenticated API requests
userGameUser✅—{ betCount, isAuthenticated }
updateBalance(balance: number) => void✅—Callback invoked with the new balance whenever it changes
onAuthRequired() => void✅—Called when an unauthenticated user attempts an action that requires auth
currencyGameCurrency—{ code: 'USD', prefix: '$', rate: 1 }Currency display configuration
languagestring—'en'UI language
logoReactNode——Brand logo
onToast(toast: ToastData) => void——Called to surface a toast notification
themeGameTheme——Theme customization — same shared theme used by every SDK game
userNamestring——Display name for the user
showBalanceboolean——Show balance in the game UI
showRulesboolean——Show a game rules / how-to-play button
hideProvablyFairboolean——Hide the provably-fair UI
showWinboolean——Show a toast with the win amount after each winning bet
isDemoboolean—falseRun entirely client-side with no backend session (demo mode)
symbolstring—'BTC'Initial trading symbol
initialBalanceUsdnumber | null——Advanced/SSR: balance (USD) fetched server-side, shown on first paint before the client fetch resolves

GameTheme

The same theme type used by every SDK game (Dice, Mines, Crash, …) — not Futures-specific.

type GameTheme = {
  backgroundDark?: string
  backgroundDarkLight?: string
  lightBackground?: string
  inputBackground?: string
  buttonColor?: string
  modeSelectBackground?: string
  modeSelectActiveColor?: string
  actionButtonColor?: string
  borderRadius?: string
}

See Theming for detailed usage and examples.

GameUser

type GameUser = {
  betCount: number
  isAuthenticated: boolean
}

ToastData

type ToastData = {
  title: string
  description?: string
  type?: 'info' | 'error' | 'success' | 'loading'
}

GameCurrency

type GameCurrency = {
  code: string
  prefix: string
  /** Exchange rate relative to USD (e.g. 5.7 for BRL). */
  rate: number
}
FieldTypeDescription
codestringISO currency code or crypto symbol (e.g. 'USD', 'BRL')
prefixstringDisplay prefix shown before amounts (e.g. '$', 'R$')
ratenumberConversion rate relative to USD

Amounts are handled internally in USD; rate converts to the display currency.

// US Dollar (default — no conversion)
currency={{ code: 'USD', prefix: '$', rate: 1 }}
 
// Brazilian Real (1 USD = 5.50 BRL)
currency={{ code: 'BRL', prefix: 'R$', rate: 5.5 }}
 
// Euro (1 USD = 0.92 EUR)
currency={{ code: 'EUR', prefix: '€', rate: 0.92 }}

Position

Represents a trading position (open or closed).

interface Position {
  id: string
  positionAmount: number   // Wager amount in USD
  multiplier: number       // Leverage multiplier
  bustPrice: number        // Liquidation price
  initialPrice: number     // Entry price at time of opening
  asset: string            // Trading symbol (e.g. 'BTC')
  isUp: boolean            // true = long, false = short
  isOpen: boolean          // true = still open
  plUsd: number            // Profit/loss in USD
  exitPrice?: number       // Price at close (undefined if still open)
  createdAt: string        // ISO timestamp
}

Instrument

Represents a tradable asset and its configuration.

type Instrument = {
  baseRate: number
  bufferMultiplier: number
  bustBuffer: number
  image: string              // URL to asset icon
  maxMultiplier: number      // Maximum allowed leverage
  name: string               // Display name (e.g. 'Bitcoin')
  positionMultiplier: number
  precision: number          // Decimal places for price display
  rateExponent: number
  rateMultiplier: number
  roiThreshold?: number
  symbol: string             // Ticker symbol (e.g. 'BTC')
}

Timeframe

type Timeframe = '1s' | '1m' | '5m'

Used internally for fetching historical price data at different resolutions.

Internals (not part of the integration surface)

FuturesGameSDK manages all data fetching and the live price feed automatically — you never call these directly. They’re documented here only for context:

MethodEndpointDescription
GET/futures/instrumentsFetch available trading instruments
GET/futures/stats/:assetFetch market stats for an asset
GET/futures/positions/openFetch the user’s open positions
GET/futures/positions/closedFetch the user’s closed positions
POST/futures/position/openOpen a new position
POST/futures/position/closeClose (cash out) a position
GET/futures/trading-history/:assetFetch historical price data

Live prices are streamed automatically over a shared price-feed connection; there’s no event API to configure.

Next Steps

Last updated on
Theming