Budokan SDK

npm install @provable-games/budokan-sdk
# or
bun add @provable-games/budokan-sdk

import { createBudokanClient } from "@provable-games/budokan-sdk";
 
const client = createBudokanClient({ chain: "mainnet" });
 
// Fetch tournaments
const { data: tournaments } = await client.getTournaments({ limit: 10 });
 
// Fetch a single tournament
const tournament = await client.getTournament("1");
 
// Fetch leaderboard
const leaderboard = await client.getTournamentLeaderboard("1");

import { BudokanClient } from "@provable-games/budokan-sdk";
 
const client = new BudokanClient({
  chain: "mainnet",          // or "sepolia" — sets defaults for all URLs and addresses
  // Override any defaults:
  apiBaseUrl: "https://budokan-api-production.up.railway.app",
  wsUrl: "wss://budokan-api-production.up.railway.app/ws",
  rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet/rpc/v0_10",
  rpcHeaders: { Authorization: "Bearer <token>" },  // optional RPC auth
  viewerAddress: "0x013c8239361fdbd7ec26db2c83f4ff270c5bba83a0bc105b4005b676ff57fdbe",
  primarySource: "api",      // "api" (default) or "rpc"
  timeout: 10000,
  retryAttempts: 3,
  retryDelay: 1000,
});

// List tournaments with filtering
const { data, total } = await client.getTournaments({
  gameAddress: "0x...",
  phase: "live",
  creator: "0x...",
  limit: 20,
  offset: 0,
  sort: "created_at",
  includePrizeSummary: true,
});
 
// Single tournament (returns null if not found)
const tournament = await client.getTournament("42");
 
// Leaderboard
const entries = await client.getTournamentLeaderboard("42");
// entries: [{ position: 1, tokenId: "0x..." }, ...]
 
// Registrations
const { data: registrations } = await client.getTournamentRegistrations("42");
 
// Prizes
const prizes = await client.getTournamentPrizes("42");
 
// Prize aggregation (totals by token)
const aggregation = await client.getTournamentPrizeAggregation("42");
 
// Reward claims
const { data: claims } = await client.getTournamentRewardClaims("42");
const summary = await client.getTournamentRewardClaimsSummary("42");
 
// Qualification entries
const { data: qualifications } = await client.getTournamentQualifications("42");
 
// Custom-distribution shares (only populated for Distribution::Custom tournaments)
const shares = await client.getTournamentDistributionShares("42");
// shares: number[] — basis points, summing to 10000

// Tournaments for a specific game
const { data } = await client.getGameTournaments("0x...", { phase: "live" });
 
// Game statistics
const gameStats = await client.getGameStats("0x...");

// Platform-wide stats
const platformStats = await client.getActivityStats();
// { totalTournaments, totalPrizes, totalRegistrations, totalSubmissions }
 
// Prize stats
const prizeStats = await client.getPrizeStats();

// Connect to WebSocket
client.connect();
 
// Subscribe to channels
const unsubscribe = client.subscribe(
  ["tournaments", "registrations", "leaderboards"],
  (message) => {
    console.log(message.channel, message.data);
  },
  ["42", "43"]  // optional: filter by tournament IDs
);
 
// Check connection status
console.log(client.wsConnected);
 
// Listen for connection changes
const off = client.onWsConnectionChange((connected) => {
  console.log("WebSocket connected:", connected);
});
 
// Cleanup
unsubscribe();
client.disconnect();

// Monitor connection status
const status = client.getConnectionStatus();
// { api: "connected" | "unavailable", rpc: "connected" | "unavailable", mode: "api" | "rpc" }
 
const off = client.onConnectionStatusChange((status) => {
  console.log("Data source mode:", status.mode);
});

import { BudokanProvider, useBudokanClient } from "@provable-games/budokan-sdk/react";

import { BudokanProvider } from "@provable-games/budokan-sdk/react";
 
function App() {
  return (
    <BudokanProvider config={{ chain: "mainnet" }}>
      <MyTournamentApp />
    </BudokanProvider>
  );
}

import {
  useTournaments,
  useTournament,
  useTournamentCount,
  useLeaderboard,
  useRegistrations,
  useTournamentsByOwner,
  useTournamentsByOwnerCount,
  useRegistrationsByOwner,
  usePlayerRewards,
  usePrizes,
  usePrizeStats,
  usePrizeAggregation,
  useRewardClaims,
  useRewardClaimsSummary,
  useQualifications,
  useActivityStats,
} from "@provable-games/budokan-sdk/react";
 
// Tournaments
const { data: tournaments, loading } = useTournaments({ phase: "live", limit: 10 });
const { data: tournament } = useTournament("42");
const { data: count } = useTournamentCount({ phase: "live" });
 
// Leaderboard & Registrations
const { data: leaderboard } = useLeaderboard("42");
const { data: registrations } = useRegistrations("42");
 
// Player-scoped views (resolved via current Budokan token ownership)
const { data: ownedTournaments } = useTournamentsByOwner("0x...", { phase: "live" });
const { data: ownedCount } = useTournamentsByOwnerCount("0x...");
const { data: ownedRegistrations } = useRegistrationsByOwner("42", "0x...");
 
// Aggregated placements/earnings across finalized tournaments the player holds
// tokens in. Requires a DenshokanProvider in the tree alongside BudokanProvider.
const { rewards } = usePlayerRewards("0x...");
 
// Prizes & Rewards
const { data: prizes } = usePrizes("42");
const { data: aggregation } = usePrizeAggregation("42");
const { data: claims } = useRewardClaims("42");
const { data: claimsSummary } = useRewardClaimsSummary("42");
 
// Qualifications & Activity
const { data: qualifications } = useQualifications("42");
const { data: activityStats } = useActivityStats();

import { useSubscription, useConnectionStatus } from "@provable-games/budokan-sdk/react";
 
// Subscribe to real-time updates
const { lastMessage } = useSubscription(
  ["tournaments", "registrations"],
  ["42"]  // optional tournament ID filter
);
 
// Monitor connection
const { connected } = useConnectionStatus();

import {
  BudokanError,
  BudokanApiError,
  BudokanTimeoutError,
  BudokanConnectionError,
  TournamentNotFoundError,
  RpcError,
  DataSourceError,
} from "@provable-games/budokan-sdk";
 
try {
  const tournament = await client.getTournament("999999");
} catch (error) {
  if (error instanceof TournamentNotFoundError) {
    console.log("Tournament not found");
  } else if (error instanceof BudokanApiError) {
    console.log("API error:", error.statusCode);
  }
}