### Install and Run Dev Server

Source: https://github.com/provable-games/docs/blob/main/README.md

Install project dependencies using Bun and start the local development server.

```bash
bun install
bun run dev
```

--------------------------------

### Install Budokan SDK

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Install the Budokan SDK using npm or bun.

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

--------------------------------

### Install Dependencies

Source: https://github.com/provable-games/docs/blob/main/CLAUDE.md

Installs project dependencies using Bun.

```bash
bun install        # Install dependencies
```

--------------------------------

### Start Game Integration Example (TypeScript)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/contracts.mdx

Example of how to initiate a new game using the game contract in TypeScript. It returns the adventurer's ID upon successful creation.

```typescript
// TypeScript/JavaScript
const startGame = async () => {
    const tx = await gameContract.start_game(
        rewardAddress,     // Address for rewards
        WeaponType.Blade,  // Starting weapon
        "Adventurer",      // Name
        0,                 // Golden token ID (0 if none)
        false              // Interface camel case
    );
    
    const receipt = await tx.wait();
    const adventurerId = receipt.events[0].adventurer_id;
    return adventurerId;
};
```

--------------------------------

### Install Denshokan SDK

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/index.mdx

Install the SDK using npm or pnpm. Peer dependencies like React and starknet may be required.

```bash
npm install @provable-games/denshokan-sdk
# or
pnpm add @provable-games/denshokan-sdk
```

--------------------------------

### Install Dependencies (npm)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Installs necessary Starknet and Dojo Engine packages using npm.

```bash
npm install starknet @dojoengine/core
```

--------------------------------

### Install Dependencies (pnpm)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Installs necessary Starknet and Dojo Engine packages using pnpm.

```bash
pnpm add starknet @dojoengine/core
```

--------------------------------

### Install Dependencies (yarn)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Installs necessary Starknet and Dojo Engine packages using yarn.

```bash
yarn add starknet @dojoengine/core
```

--------------------------------

### Start Game Function Signature

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/contracts.mdx

Initiates a new adventure, returning an adventurer ID. Requires payment and accepts various parameters for game setup.

```cairo
fn start_game(
    client_reward_address: ContractAddress,
    weapon_type: WeaponType,
    name: felt252,
    golden_token_id: u256,
    interface_camel: bool
) -> u256
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Installs the starknet-py library for Python integration.

```bash
pip install starknet-py
```

--------------------------------

### Upgrade After Level Up Integration Example (TypeScript)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/contracts.mdx

Example of upgrading an adventurer's stats and purchasing items after leveling up, using the game contract in TypeScript.

```typescript
const upgrade = async (adventurerId: bigint) => {
    const statUpgrades = {
        strength: 1,
        dexterity: 0,
        vitality: 0,
        intelligence: 0,
        wisdom: 0,
        charisma: 0,
        luck: 0,
    };
    
    const itemsToPurchase = [
        { item_id: 123, equip: true },
        { item_id: 456, equip: false },
    ];
    
    await gameContract.upgrade(
        adventurerId,
        statUpgrades,
        itemsToPurchase
    );
};
```

--------------------------------

### Quick Start: Create Client and Fetch Data

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Initialize the Budokan client and fetch tournaments and a single tournament.

```typescript
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");
```

--------------------------------

### GET /settings

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves global settings.

```APIDOC
## GET /settings

### Description
Global settings

### Method
GET

### Endpoint
`/settings`
```

--------------------------------

### Registry Hooks Pattern Example

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/building-a-platform/registry.mdx

Implement custom logic after a game is registered using the `after_register_game` hook. This example shows minting a creator NFT.

```cairo
fn after_register_game(game_id: u64, creator_address: ContractAddress) {
    // Denshokan mints a creator NFT here
    self.erc721.mint(creator_address, game_id.into());
}

```

--------------------------------

### React Hooks - Setup

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Set up the Budokan SDK in your React application by wrapping your app with the `BudokanProvider` component.

```APIDOC
## React Hooks - Setup

### Description
To use the Budokan SDK's React hooks, you must first wrap your application or relevantส่วน of it with the `BudokanProvider` component. This component provides the necessary context for other hooks to function.

### Usage
Import `BudokanProvider` and include it in your component tree, typically at the root level. Configure it with necessary settings like the blockchain `chain`.

### Example
```tsx
import { BudokanProvider } from "@provable-games/budokan-sdk/react";

function App() {
  return (
    <BudokanProvider config={{ chain: "mainnet" }}>
      <MyTournamentApp />
    </BudokanProvider>
  );
}
```
```

--------------------------------

### Score Batch Implementation Example

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/building-a-game/score-and-game-over.mdx

An example implementation of the `score_batch` function. It iterates through a span of token IDs and reads the score for each from storage, appending it to a results array.

```cairo
fn score_batch(self: @ContractState, token_ids: Span<felt252>) -> Array<u64> {
    let mut results = array![];
    for token_id in token_ids {
        results.append(self.scores.read(*token_id));
    };
    results
}
```

--------------------------------

### Batch Operations Example

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Illustrates how to process multiple actions within a single transaction for efficiency.

```cairo
// Multiple actions in single transaction
fn batch_actions(actions: Array<Action>) {
    // Process all actions together
}
```

--------------------------------

### Games SDK Methods

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Examples of using the DenshokanClient SDK to interact with game data.

```APIDOC
## Games SDK Methods

```typescript
// List games with pagination
const games = await client.getGames({ limit: 20, offset: 0 });
// Returns: PaginatedResult<Game>

// Get a single game (API with RPC fallback)
const game = await client.getGame("0x1234...");
// Returns: Game

// Get game statistics
const stats = await client.getGameStats("0x1234...");
// Returns: GameStats
```
```

--------------------------------

### Event Listening Example

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Shows how to listen for contract events like 'BeastSlain' and update the game state accordingly.

```typescript
contract.on("BeastSlain", (event) => {
  updateGameState(event);
});
```

--------------------------------

### Install game-components Packages

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/reference/index.mdx

Add the necessary game-components packages and their dependencies to your Scarb.toml file to integrate them into your Starknet project.

```toml
[dependencies]
starknet = "2.15.1"

# Core - Token, Minigame, Metagame, Registry
game_components_embeddable_game_standard = { git = "https://github.com/Provable-Games/game-components", tag = "v1.1.0" }

# Leaderboard, registration, entry gating, entry fees, prizes
game_components_metagame = { git = "https://github.com/Provable-Games/game-components", tag = "v1.1.0" }

# Tokenomics: buyback, stream token
game_components_economy = { git = "https://github.com/Provable-Games/game-components", tag = "v1.1.0" }

# Math, distribution, encoding, SVG rendering
game_components_utilities = { git = "https://github.com/Provable-Games/game-components", tag = "v1.1.0" }

# Ready-to-deploy contracts
game_components_presets = { git = "https://github.com/Provable-Games/game-components", tag = "v1.1.0" }

# OpenZeppelin (required)
openzeppelin_token = { git = "https://github.com/OpenZeppelin/cairo-contracts.git", tag = "v3.0.0" }
openzeppelin_introspection = { git = "https://github.com/OpenZeppelin/cairo-contracts.git", tag = "v3.0.0" }
openzeppelin_access = { git = "https://github.com/OpenZeppelin/cairo-contracts.git", tag = "v3.0.0" }

```

--------------------------------

### Lifecycle Implementation

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/building-a-game/lifecycle.mdx

Provides the logic for checking game expiration, start status, playability, and validating start/end times.

```cairo
impl LifecycleImpl of LifecycleTrait {
    fn has_expired(self: @Lifecycle, current_time: u64) -> bool {
        if *self.end == 0 { false } else { current_time >= *self.end }
    }

    fn can_start(self: @Lifecycle, current_time: u64) -> bool {
        if *self.start == 0 { true } else { current_time >= *self.start }
    }

    fn is_playable(self: @Lifecycle, current_time: u64) -> bool {
        self.can_start(current_time) && !self.has_expired(current_time)
    }

    fn validate(self: @Lifecycle) {
        if *self.end != 0 && *self.start > *self.end {
            panic!("Lifecycle: Start time cannot be greater than end time");
        }
    }
}

```

--------------------------------

### Build and Preview Production

Source: https://github.com/provable-games/docs/blob/main/README.md

Create a production build of the documentation site and preview it locally.

```bash
bun run build
bun run preview
```

--------------------------------

### Game Lifecycle Stages

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/architecture.mdx

Outlines the typical sequence of events in the lifecycle of an EGS game, from setup to completion.

```text
1. Setup      Game contract deploys and registers with the Registry
2. Mint       Platform or user calls mint() on MinigameToken
              → Creates packed token ID with game_id, settings, timing
3. Play       Player interacts with the Minigame contract
              → Game updates its internal state (score, progress)
4. Sync       Anyone calls update_game(token_id) on MinigameToken
              → Token reads score/game_over from Minigame via IMinigameTokenData
              → If minter supports IMetagameCallback, dispatches callbacks
5. Complete   Game marks game_over = true
              → Final sync writes permanent result to token
```

--------------------------------

### Run Development Server

Source: https://github.com/provable-games/docs/blob/main/CLAUDE.md

Starts the development server using Bun. The --host flag can be used to make it accessible on the network.

```bash
bun run dev        # Dev server (with --host)
```

--------------------------------

### Unit Test Game Integration in TypeScript

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Example of unit tests for game integration using Vitest. It demonstrates mocking dependencies and asserting expected outcomes for starting an adventure and handling combat.

```typescript
import { describe, it, expect } from 'vitest';

describe('Game Integration', () => {
    it('should start a new game', async () => {
        const adventurerId = await startAdventure(
            mockAccount,
            WeaponType.Blade,
            'Test Hero'
        );
        
        expect(adventurerId).toBeGreaterThan(0n);
    });
    
    it('should handle combat', async () => {
        const result = await attack(mockAccount, adventurerId);
        expect(result.status).toBe('ACCEPTED');
    });
});
```

--------------------------------

### Integration Test Full Game Cycle in TypeScript

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

An integration test simulating a complete game cycle, from starting an adventure to exploring, engaging in combat, and checking the adventurer's state. Assumes necessary setup and mock functions.

```typescript
describe('Full Game Flow', () => {
    it('should complete a full game cycle', async () => {
        // Start game
        const id = await startAdventure(account, 0, 'Hero');
        
        // Explore
        await explore(account, id, false);
        
        // Combat
        const beast = await getCurrentBeast(id);
        if (beast) {
            await attack(account, id, false);
        }
        
        // Check state
        const adventurer = await getAdventurer(id);
        expect(adventurer.experience).toBeGreaterThan(0);
    });
});
```

--------------------------------

### start_game

Source: https://github.com/provable-games/docs/blob/main/src/pages/darkshuffle/key-functions.mdx

Initializes a new game instance for a player, setting up the draft or auto-drafting cards, and emits a game creation event.

```APIDOC
## start_game

### Description
Initializes a new game instance for a player, setting up the draft or auto-drafting cards, and emits a game creation event.

### Parameters
- **game_id** (u64) - Required - The unique identifier for the game.
```

--------------------------------

### Preview Production Build

Source: https://github.com/provable-games/docs/blob/main/CLAUDE.md

Previews the production build locally using Bun.

```bash
bun run preview    # Preview production build
```

--------------------------------

### Setup DenshokanProvider

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/react-hooks.mdx

Wrap your application with DenshokanProvider to enable SDK hooks. Configure the client using 'config' or pass an existing 'client' instance.

```tsx
import { DenshokanProvider } from "@provable-games/denshokan-sdk/react";

function App() {
  return (
    <DenshokanProvider config={{ chain: "mainnet" }}>
      <MyApp />
    </DenshokanProvider>
  );
}
```

--------------------------------

### Initialize DenshokanClient with Configuration

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Instantiate the DenshokanClient with various configuration options including chain, URLs, contract addresses, and fetch/WebSocket/health settings.

```typescript
import { DenshokanClient } from "@provable-games/denshokan-sdk";

const client = new DenshokanClient({
  chain: "mainnet",           // "mainnet" | "sepolia"
  apiUrl: "https://...",      // Override API URL
  wsUrl: "wss://...",         // Override WebSocket URL
  rpcUrl: "https://...",      // Override RPC URL
  primarySource: "api",       // "api" | "rpc" (default: "api")
  viewerAddress: "0x...",     // Viewer contract for batch filter queries
  denshokanAddress: "0x...",  // Denshokan ERC721 contract address
  registryAddress: "0x...",   // Minigame registry contract address
  fetch: {
    timeout: 10000,           // Request timeout (ms)
    maxRetries: 3,            // Max retry attempts
    baseBackoff: 1000,        // Base backoff delay (ms)
    maxBackoff: 30000,        // Max backoff delay (ms)
    tokenUriConcurrency: 0,   // Max concurrent URI fetches (0 = unlimited)
  },
  ws: {
    maxReconnectAttempts: 10, // Max reconnect attempts
    reconnectBaseDelay: 1000, // Base reconnect delay (ms)
  },
  health: {
    initialCheckDelay: 1000,  // ms before first health check
    checkInterval: 30000,     // ms between health checks
    checkTimeout: 5000,       // ms timeout for health check
  },
});
```

--------------------------------

### Lifecycle Struct Definition

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/building-a-game/lifecycle.mdx

Defines the start and end Unix timestamps for game playability. Use 0 for immediate start or never expiring.

```cairo
#[derive(Copy, Drop, Serde)]
pub struct Lifecycle {
    pub start: u64,  // Unix timestamp when the game becomes playable (0 = immediately)
    pub end: u64,    // Unix timestamp when the game expires (0 = never)
}

```

--------------------------------

### Build for Production

Source: https://github.com/provable-games/docs/blob/main/CLAUDE.md

Creates a production build of the project using Bun.

```bash
bun run build      # Production build
```

--------------------------------

### SettingsComponent Implementation Pattern

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/building-a-game/settings-and-objectives.mdx

Shows how to implement IMinigameTokenSettings by parsing settings, storing metadata in SettingsComponent, and persisting parsed values in game-specific storage. Includes input validation.

```cairo
use game_components_embeddable_game_standard::minigame::settings::SettingsComponent;

component!(path: SettingsComponent, storage: settings, event: SettingsEvent);

#[abi(embed_v0)]
impl SettingsImpl of IMinigameTokenSettings<ContractState> {
    fn create_settings(
        ref self: ContractState,
        name: ByteArray,
        description: ByteArray,
        settings: Span<GameSetting>,
    ) -> u32 {
        // Parse the key-value pairs into your game's data
        let mut min: u32 = 1;
        let mut max: u32 = 100;
        let mut max_attempts: u32 = 0;

        for setting in settings {
            if *setting.name == "range_min" {
                min = parse_u32(*setting.value);
            } else if *setting.name == "range_max" {
                max = parse_u32(*setting.value);
            } else if *setting.name == "max_attempts" {
                max_attempts = parse_u32(*setting.value);
            }
        };

        assert!(max > min, "max must be greater than min");

        // Store in component (handles ID allocation and metadata)
        let settings_id = self.settings.create(name, description, settings);

        // Store parsed values in game-specific storage
        self.settings_data.write(settings_id, (min, max, max_attempts));

        settings_id
    }

    fn settings_exists(self: @ContractState, settings_id: u32) -> bool {
        self.settings.exists(settings_id)
    }

    fn settings_count(self: @ContractState) -> u32 {
        self.settings.count()
    }

    fn settings_details(self: @ContractState, settings_id: u32) -> GameSettingDetails {
        self.settings.details(settings_id)
    }

    fn settings_details_batch(
        self: @ContractState, settings_ids: Span<u32>,
    ) -> Array<GameSettingDetails> {
        self.settings.details_batch(settings_ids)
    }
}
```

--------------------------------

### Combat Loop Integration Example (TypeScript)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/contracts.mdx

Example of executing the combat loop for an adventurer using the game contract in TypeScript. It checks for adventurer survival after the fight.

```typescript
const combatLoop = async (adventurerId: bigint) => {
    // Attack until victory or death
    const tx = await gameContract.attack(
        adventurerId,
        true  // to_the_death
    );
    
    await tx.wait();
    
    // Check if adventurer survived
    const adventurer = await adventurerContract.get_adventurer(adventurerId);
    if (adventurer.health === 0) {
        console.log("Game Over!");
    }
};
```

--------------------------------

### Packed Storage Optimization Example

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Demonstrates efficient packing of multiple stats into a single storage slot using a struct.

```cairo
// Efficient packing of multiple values
struct PackedStats {
    // All stats in single felt252
    packed: felt252,
}
```

--------------------------------

### GET /minters

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Lists all minters.

```APIDOC
## GET /minters

### Description
List minters

### Method
GET

### Endpoint
`/minters`
```

--------------------------------

### GET /objectives

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves global objectives.

```APIDOC
## GET /objectives

### Description
Global objectives

### Method
GET

### Endpoint
`/objectives`
```

--------------------------------

### Deploying Contracts with Dojo CLI

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Deploy smart contracts to a network using the Dojo CLI. Build, deploy, and inspect your contracts through command-line operations.

```bash
# Build contracts
sozo build

# Deploy to network
sozo deploy --world 0xWORLD_ADDRESS

# Verify deployment
sozo inspect
```

--------------------------------

### GET /activity/stats

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves statistics for activity events.

```APIDOC
## GET /activity/stats

### Description
Activity statistics

### Method
GET

### Endpoint
`/activity/stats`
```

--------------------------------

### Initialize Game Instance

Source: https://github.com/provable-games/docs/blob/main/src/pages/darkshuffle/key-functions.mdx

Initializes a new game instance for a player. Use this to start a new game, setting up the draft or auto-drafting cards.

```cairo
fn start_game(ref self: T, game_id: u64);
```

--------------------------------

### GET /tokens

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Lists tokens with filtering capabilities.

```APIDOC
## GET /tokens

### Description
List tokens (filterable)

### Method
GET

### Endpoint
`/tokens`
```

--------------------------------

### Initialize Starknet Provider (Testnet)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Initializes a Starknet provider for connecting to the Sepolia testnet.

```typescript
import { Provider, constants } from 'starknet';

// Testnet (Sepolia)
const provider = new Provider({
    sequencer: {
        network: constants.NetworkName.SN_SEPOLIA,
    },
});
```

--------------------------------

### GET /games

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Lists games with pagination support.

```APIDOC
## GET /games

### Description
List games (paginated)

### Method
GET

### Endpoint
`/games`

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Maximum number of games to return.
- **offset** (number) - Optional - Number of games to skip before returning results.
```

--------------------------------

### Initialize Starknet Provider (Mainnet)

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Initializes a Starknet provider for connecting to the mainnet.

```typescript
import { Provider, constants } from 'starknet';

// Mainnet
const provider = new Provider({
    sequencer: {
        network: constants.NetworkName.SN_MAIN,
    },
});
```

--------------------------------

### GET /health

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Performs a health check on the API.

```APIDOC
## GET /health

### Description
Health check

### Method
GET

### Endpoint
`/health`
```

--------------------------------

### GET /activity

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves activity events with filtering capabilities.

```APIDOC
## GET /activity

### Description
Activity events (filterable)

### Method
GET

### Endpoint
`/activity`
```

--------------------------------

### Frontend Build and Deployment with PNPM

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Manage frontend dependencies and build processes using PNPM. Install, build for production, and deploy your frontend application.

```bash
# Install dependencies
pnpm install

# Build for production
pnpm build

# Deploy to CDN
pnpm deploy
```

--------------------------------

### GET /minters/{minterId}

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves a single minter by its ID.

```APIDOC
## GET /minters/{minterId}

### Description
Get a single minter

### Method
GET

### Endpoint
`/minters/{minterId}`

### Parameters
#### Path Parameters
- **minterId** (string) - Required - The ID of the minter.
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Configure the development environment using TOML. Set local RPC URLs, account addresses, and private keys for local testing.

```toml
[environment]
rpc_url = "http://localhost:5050"
account_address = "0xDEV"
private_key = "0xDEV_KEY"
```

--------------------------------

### GET /tokens/{tokenId}

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves a single token by its ID.

```APIDOC
## GET /tokens/{tokenId}

### Description
Get a single token

### Method
GET

### Endpoint
`/tokens/{tokenId}`

### Parameters
#### Path Parameters
- **tokenId** (string) - Required - The ID of the token.
```

--------------------------------

### React BudokanProvider Setup

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Wrap your application with BudokanProvider to enable the SDK's React hooks. Configure the chain to use.

```tsx
import { BudokanProvider } from "@provable-games/budokan-sdk/react";

function App() {
  return (
    <BudokanProvider config={{ chain: "mainnet" }}>
      <MyTournamentApp />
    </BudokanProvider>
  );
}
```

--------------------------------

### Get Activity Stats

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches platform-wide activity statistics.

```APIDOC
## Get Activity Stats

### Description
Retrieves overall platform statistics, including total tournaments created, total prizes awarded, total registrations, and total submissions across all games.

### Method
`getActivityStats()`

### Parameters
None

### Request Example
```typescript
const platformStats = await client.getActivityStats();
```

### Response
#### Success Response (200)
An object containing platform-wide activity statistics.

#### Response Example
```json
{
  "totalTournaments": 1000,
  "totalPrizes": "100000 USDC",
  "totalRegistrations": 50000,
  "totalSubmissions": 200000
}
```
```

--------------------------------

### Get Game Stats

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches statistics for a specific game.

```APIDOC
## Get Game Stats

### Description
Retrieves statistical data for a specific game, identified by its contract address. This can include metrics like number of tournaments, total prizes, etc.

### Method
`getGameStats(gameAddress: string)`

### Parameters
#### Path Parameters
- **gameAddress** (string) - Required - The contract address of the game.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const gameStats = await client.getGameStats("0x...");
```

### Response
#### Success Response (200)
An object containing various statistics for the game.

#### Response Example
```json
{
  "totalTournaments": 150,
  "totalPrizesAwarded": "10000 USDC",
  "totalRegistrations": 5000
}
```
```

--------------------------------

### Get Tournament

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches details for a specific tournament by its ID.

```APIDOC
## Get Tournament

### Description
Retrieves the details of a single tournament identified by its unique ID. Returns `null` if the tournament is not found.

### Method
`getTournament(id: string)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tournament.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const tournament = await client.getTournament("42");
```

### Response
#### Success Response (200)
A `Tournament` object containing the details of the specified tournament, or `null` if not found.

#### Response Example
```json
{
  "id": "42",
  "name": "Winter Championship",
  "gameAddress": "0x...",
  "phase": "upcoming",
  "createdAt": "2023-11-15T12:00:00Z"
}
```
```

--------------------------------

### MinigameComponent Initialization

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/reference/minigame.mdx

Illustrates the parameters required for initializing the MinigameComponent, covering game creator, metadata, contract addresses, and optional configurations like royalties and fees.

```cairo
self.minigame.initializer(
    game_creator,           // Address that receives creator NFT
    game_name,              // "Number Guess"
    game_description,       // "Guess the secret number"
    game_developer,         // "Provable Games"
    game_publisher,         // "Provable Games"
    game_genre,             // "Puzzle"
    game_image,             // Image URL
    game_color,             // Option<ByteArray> - hex color
    client_url,             // Option<ByteArray> - game client URL
    renderer_address,       // Option<ContractAddress> - custom renderer
    settings_address,       // Option<ContractAddress> - settings provider
    objectives_address,     // Option<ContractAddress> - objectives provider
    minigame_token_address, // MinigameToken contract address
    royalty_fraction,       // Option<u128> - basis points
    skills_address,         // Option<ContractAddress> - AI agent skills
    version,                // u64 - game version number
    license,                // Option<ByteArray> - game license text
    game_fee_bps,           // Option<u16> - fee in basis points (default 500 = 5%)
);
```

--------------------------------

### GET /games/{gameAddress}/objectives

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves objectives for a specific game.

```APIDOC
## GET /games/{gameAddress}/objectives

### Description
Game objectives

### Method
GET

### Endpoint
`/games/{gameAddress}/objectives`

### Parameters
#### Path Parameters
- **gameAddress** (string) - Required - The address of the game.
```

--------------------------------

### GET /games/{gameAddress}/settings

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves settings for a specific game.

```APIDOC
## GET /games/{gameAddress}/settings

### Description
Game settings

### Method
GET

### Endpoint
`/games/{gameAddress}/settings`

### Parameters
#### Path Parameters
- **gameAddress** (string) - Required - The address of the game.
```

--------------------------------

### GET /games/{gameAddress}/stats

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/frontend/sdk.mdx

Retrieves statistics for a specific game.

```APIDOC
## GET /games/{gameAddress}/stats

### Description
Game statistics

### Method
GET

### Endpoint
`/games/{gameAddress}/stats`

### Parameters
#### Path Parameters
- **gameAddress** (string) - Required - The address of the game.
```

--------------------------------

### Production Environment Configuration

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/architecture.mdx

Configure the production environment using TOML. Use mainnet RPC URLs and secure production account credentials.

```toml
[environment]
rpc_url = "https://starknet-mainnet.public.blastapi.io"
account_address = "0xPROD"
private_key = "$PROD_KEY"
```

--------------------------------

### Get Game Tournaments

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches tournaments associated with a specific game.

```APIDOC
## Get Game Tournaments

### Description
Retrieves a list of tournaments associated with a particular game, identified by its contract address. Filtering by phase is also supported.

### Method
`getGameTournaments(gameAddress: string, options?: { phase?: string })`

### Parameters
#### Path Parameters
- **gameAddress** (string) - Required - The contract address of the game.

#### Query Parameters
`options` (object) - Optional parameters.
- `phase` (string): Filter by tournament phase ('live', 'upcoming', 'finished').

#### Request Body
None

### Request Example
```typescript
const { data } = await client.getGameTournaments("0x...", { phase: "live" });
```

### Response
#### Success Response (200)
An object containing an array of tournament data for the specified game.

#### Response Example
```json
{
  "data": [
    { "id": "1", "name": "Game A Tournament 1" },
    { "id": "2", "name": "Game A Tournament 2" }
  ]
}
```
```

--------------------------------

### Get Tournament Qualifications

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches qualification entries for a specific tournament.

```APIDOC
## Get Tournament Qualifications

### Description
Retrieves the qualification entries for a specific tournament ID. These entries typically represent participants who have met certain criteria to qualify for the tournament or its prizes.

### Method
`getTournamentQualifications(id: string)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tournament.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const { data: qualifications } = await client.getTournamentQualifications("42");
```

### Response
#### Success Response (200)
An object containing an array of qualification data.

#### Response Example
```json
{
  "data": [
    { "participantAddress": "0x...", "qualificationScore": 100 },
    { "participantAddress": "0x...", "qualificationScore": 95 }
  ]
}
```
```

--------------------------------

### Create Starknet Contract Instances

Source: https://github.com/provable-games/docs/blob/main/src/pages/lootsurvivor/technical/integration.mdx

Creates contract instances for interacting with Game and Adventurer contracts.

```typescript
import { Contract } from 'starknet';
import GameABI from './abis/Game.json';
import AdventurerABI from './abis/Adventurer.json';

const GAME_ADDRESS = "0xbcb2386436161d8d3afea0a805a8610ab90af5cf5582d866b83e9cb779bef3";
const ADVENTURER_ADDRESS = "0x3befa9c969bf82bbfa0a96374da9f7aab172101298c0ff2611ec8c2fd02692";

const gameContract = new Contract(GameABI, GAME_ADDRESS, provider);
const adventurerContract = new Contract(AdventurerABI, ADVENTURER_ADDRESS, provider);
```

--------------------------------

### Get Tournament Prizes

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches the prize details for a specific tournament.

```APIDOC
## Get Tournament Prizes

### Description
Retrieves the prize details associated with a specific tournament ID.

### Method
`getTournamentPrizes(id: string)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tournament.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const prizes = await client.getTournamentPrizes("42");
```

### Response
#### Success Response (200)
An array of prize objects for the specified tournament.

#### Response Example
```json
[
  { "tokenId": "USDC", "amount": "500", "recipient": "0x..." },
  { "tokenId": "ETH", "amount": "0.1", "recipient": "0x..." }
]
```
```

--------------------------------

### Get Tournament Leaderboard

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches the leaderboard entries for a specific tournament.

```APIDOC
## Get Tournament Leaderboard

### Description
Retrieves the leaderboard entries for a given tournament ID. Each entry typically includes the player's position and token ID.

### Method
`getTournamentLeaderboard(id: string)`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tournament.

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const leaderboard = await client.getTournamentLeaderboard("42");
```

### Response
#### Success Response (200)
An array of leaderboard entries, where each entry contains `position` and `tokenId`.

#### Response Example
```json
[
  { "position": 1, "tokenId": "0xabc..." },
  { "position": 2, "tokenId": "0xdef..." }
]
```
```

--------------------------------

### Create Budokan Client

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Initializes the Budokan client with optional configuration for chain, URLs, and other settings.

```APIDOC
## Create Budokan Client

### Description
Initializes the Budokan client. You can specify the chain (e.g., 'mainnet', 'sepolia') to use default URLs and addresses, or provide custom URLs for the API, WebSocket, and RPC.

### Method
`createBudokanClient(config?: BudokanClientConfig)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`config` (BudokanClientConfig) - Optional configuration object.
- `chain` (string): 'mainnet' or 'sepolia'.
- `apiBaseUrl` (string): Custom API base URL.
- `wsUrl` (string): Custom WebSocket URL.
- `rpcUrl` (string): Custom RPC URL.
- `rpcHeaders` (object): Optional headers for RPC requests.
- `viewerAddress` (string): The address of the viewer.
- `primarySource` (string): 'api' or 'rpc'.
- `timeout` (number): Request timeout in milliseconds.
- `retryAttempts` (number): Number of retry attempts.
- `retryDelay` (number): Delay between retries in milliseconds.

### Request Example
```typescript
import { createBudokanClient } from "@provable-games/budokan-sdk";

const client = createBudokanClient({ chain: "mainnet" });
```

### Response
Returns an instance of `BudokanClient`.
```

--------------------------------

### Get Tournaments

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Fetches a list of tournaments with optional filtering and pagination.

```APIDOC
## Get Tournaments

### Description
Retrieves a list of tournaments, allowing filtering by game address, phase, creator, and sorting. It also supports pagination and including prize summary information.

### Method
`getTournaments(options?: GetTournamentsOptions)`

### Parameters
#### Path Parameters
None

#### Query Parameters
`options` (GetTournamentsOptions) - Optional parameters for filtering and pagination.
- `gameAddress` (string): Filter by game contract address.
- `phase` (string): Filter by tournament phase ('live', 'upcoming', 'finished').
- `creator` (string): Filter by creator's address.
- `limit` (number): Number of results to return per page.
- `offset` (number): Number of results to skip.
- `sort` (string): Field to sort by (e.g., 'created_at').
- `includePrizeSummary` (boolean): Whether to include a summary of prizes.

### Request Example
```typescript
const { data: tournaments, total } = await client.getTournaments({
  gameAddress: "0x...",
  phase: "live",
  limit: 20,
  offset: 0,
  includePrizeSummary: true,
});
```

### Response
#### Success Response (200)
An object containing:
- `data` (Array<Tournament>): An array of tournament objects.
- `total` (number): The total number of tournaments matching the query.

#### Response Example
```json
{
  "data": [
    {
      "id": "1",
      "name": "Summer Slam",
      "gameAddress": "0x...",
      "phase": "live",
      "createdAt": "2023-10-27T10:00:00Z",
      "prizeSummary": {
        "totalPrizeValue": "1000 USDC",
        "prizeToken": "USDC"
      }
    }
  ],
  "total": 50
}
```
```

--------------------------------

### Documentation Contribution Guidelines

Source: https://github.com/provable-games/docs/blob/main/CLAUDE.md

Outlines the process for adding or editing documentation pages, including file locations, sidebar configuration, image placement, and available custom components.

```bash
1. Pages are `.mdx` files in `src/pages/<product>/`
2. Sidebar navigation for each product section is configured in `vocs.config.ts` under the `sidebar` key
3. Images go in `src/public/docs/`
4. Custom components available: `ContractTable`, `ContractLink`, `GameCard`, `Homepage` in `src/components/`
```

--------------------------------

### Fetch Tournament Qualifications

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Get qualification entries for a specific tournament.

```typescript
// Qualification entries
const { data: qualifications } = await client.getTournamentQualifications("42");
```

--------------------------------

### Fetch Tournament Prizes

Source: https://github.com/provable-games/docs/blob/main/src/pages/budokan/sdk.mdx

Get the prize details for a specific tournament.

```typescript
// Prizes
const prizes = await client.getTournamentPrizes("42");
```

--------------------------------

### Optional Interface: IMinigameTokenSettings

Source: https://github.com/provable-games/docs/blob/main/src/pages/embeddable-game-standard/reference/minigame.mdx

Enables the configuration of different game modes and settings. Allows creation, checking existence, counting, and retrieving details of settings by ID, including batch retrieval.

```cairo
#[starknet::interface]
pub trait IMinigameTokenSettings<TState> {
    fn create_settings(
        ref self: TState,
        name: ByteArray,
        description: ByteArray,
        settings: Span<GameSetting>,
    ) -> u32;
    fn settings_exists(self: @TState, settings_id: u32) -> bool;
    fn settings_count(self: @TState) -> u32;
    fn settings_details(self: @TState, settings_id: u32) -> GameSettingDetails;
    fn settings_details_batch(
        self: @TState, settings_ids: Span<u32>,
    ) -> Array<GameSettingDetails>;
}
```