Default

Initialize a new game tier

post

Creates a new GlobalState PDA for the given tier_id with the provided game configuration. Can only be called once per tier. The admin becomes the tier authority.

Accounts:

Name	Type	Description
global_state	PDA (init)	["global_state", tier_id]
admin	Signer (mut)	Pays rent, becomes admin
protocol_treasury	AccountInfo	Treasury for protocol fees
system_program	Program	System program

Body

application/json

tier_idinteger · uint8Required

Unique tier identifier (0–255)

Responses

200

Transaction succeeded

No content

post

/solana/initialize

HTTPcURLJavaScriptPython

POST /functions/v1/solana/initialize HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 261

{
  "tier_id": 1,
  "config": {
    "min_players": 1,
    "countdown_duration": 1,
    "game_duration": 1,
    "free_switch_window": 1,
    "free_switches": 1,
    "entry_fee": 1,
    "withdrawal_fee": 1,
    "base_switch_fee": 1,
    "protocol_fee_bps": 1,
    "closer_reward": 1,
    "starter_reward": 1,
    "max_payout_multiple_bps": 1
  }
}

200

Transaction succeeded

No content

Initialize a new round

post

Creates a new RoundState PDA for round current_round + 1. Admin only.

Accounts:

Name	Type	Description
global_state	PDA (mut)	Tier global state
round_state	PDA (init)	["round", tier_id, round_number]
admin	Signer (mut)	Must match global_state.admin
system_program	Program	System program

Responses

200

Transaction succeeded

No content

post

/solana/init-round

HTTPcURLJavaScriptPython

POST /functions/v1/solana/init-round HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Join the current round

post

Player joins the active round. Entry fee is deducted from user_vault. Team is assigned round-robin (total_players % 3). If total_players >= min_players, countdown starts automatically.

Allowed when status is Waiting or during Countdown (before countdown expires).

Accounts:

Name	Type	Description
round_state	PDA (mut)	Current round
global_state	PDA	Tier config
user_vault	PDA (mut)	["vault", authority] — pays entry fee
player_state	PDA (init)	["player", tier_id, round, authority]
signer	Signer (mut)	Authority or delegate
authority	AccountInfo	Vault owner
system_program	Program	System program

Responses

200

Transaction succeeded

No content

post

/solana/join-game

HTTPcURLJavaScriptPython

POST /functions/v1/solana/join-game HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Switch to a different team

post

Switches the player to new_team (0, 1, or 2). Only allowed during Active status and before game_end_at.

Fee logic:

• Free if within free_switch_window seconds of game start AND switches_used < free_switches

• Otherwise: base_switch_fee * paid_switches (escalating cost)

Accounts:

Name	Type	Description
round_state	PDA (mut)	Current round
global_state	PDA	Tier config
user_vault	PDA (mut)	Pays switch fee
player_state	PDA (mut)	Player's round state
signer	Signer (mut)	Authority or delegate
authority	AccountInfo	Vault owner
system_program	Program	System program

Body

application/json

new_teaminteger · enumRequired

Target team index

Possible values:

Responses

200

Transaction succeeded

No content

post

/solana/switch-team

HTTPcURLJavaScriptPython

POST /functions/v1/solana/switch-team HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "new_team": 0
}

200

Transaction succeeded

No content

Transition from Countdown to Active

post

Starts the game after countdown expires. Awards starter_reward to the caller's vault. Sets game_start_at and game_end_at.

Accounts:

Name	Type	Description
round_state	PDA (mut)	Must be in Countdown
global_state	PDA	Tier config
user_vault	PDA (mut)	Receives starter reward
authority	AccountInfo	Vault owner
starter	Signer (mut)	Authority or delegate

Responses

200

Transaction succeeded

No content

post

/solana/start-game

HTTPcURLJavaScriptPython

POST /functions/v1/solana/start-game HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

End the current round and initialize the next

post

Ends the game after game_end_at has passed. Determines winners by fewest players (ties broken by fewest defections; 3-way tie = no winners, full rollover).

Distributes: protocol fee to treasury, closer reward to caller's vault, reward per winner (capped at max_payout_multiple_bps), surplus rolls to next round.

Automatically initializes next_round_state.

Accounts:

Name	Type	Description
round_state	PDA (mut)	Current round
protocol_treasury	AccountInfo (mut)	Receives protocol fee
global_state	PDA (mut)	Updates current_round
user_vault	PDA (mut)	Receives closer reward
authority	AccountInfo	Vault owner
next_round_state	PDA (init)	Next round
closer	Signer (mut)	Authority or delegate
system_program	Program	System program

Responses

200

Transaction succeeded

No content

post

/solana/end-game

HTTPcURLJavaScriptPython

POST /functions/v1/solana/end-game HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Claim winnings from an ended round

post

Claims reward_per_winner from the round pot into the player's vault. Uses bitmask verification: winning_team_mask & (1 << current_team) != 0.

Accounts:

Name	Type	Description
round_state	PDA (mut)	Must be Ended
global_state	PDA	Tier config
player_state	PDA (mut)	Must not have claimed
user_vault	PDA (mut)	Receives reward
authority	AccountInfo	Player's authority
signer	Signer (mut)	Authority or delegate

Responses

200

Transaction succeeded

No content

post

/solana/claim-prize

HTTPcURLJavaScriptPython

POST /functions/v1/solana/claim-prize HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Deposit SOL into user vault

post

Deposits amount lamports from the authority's wallet into their vault PDA. Creates the vault if it doesn't exist (init_if_needed).

Accounts:

Name	Type	Description
user_vault	PDA (init_if_needed, mut)	["vault", authority]
authority	Signer (mut)	Depositor
system_program	Program	System program

Body

application/json

amountinteger · uint64Required

Lamports to deposit

Responses

200

Transaction succeeded

No content

post

/solana/deposit

HTTPcURLJavaScriptPython

POST /functions/v1/solana/deposit HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 12

{
  "amount": 1
}

200

Transaction succeeded

No content

Withdraw all available SOL from vault

post

Withdraws all lamports above rent-exempt minimum from the vault to the authority wallet. Authority only (no delegate).

Accounts:

Name	Type	Description
user_vault	PDA (mut)	["vault", authority]
authority	Signer (mut)	Must be vault owner
system_program	Program	System program

Responses

200

Transaction succeeded

No content

post

/solana/withdraw-vault

HTTPcURLJavaScriptPython

POST /functions/v1/solana/withdraw-vault HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Withdraw from a round during Waiting phase

post

Allows a player to leave a round that hasn't started yet. Refunds entry_fee - withdrawal_fee. The player_state account is closed (rent returned to vault).

Accounts:

Name	Type	Description
player_state	PDA (mut, close)	Closed after withdrawal
round_state	PDA (mut)	Must be Waiting
global_state	PDA	Tier config
user_vault	PDA (mut)	Receives refund
authority	AccountInfo	Vault owner
signer	Signer (mut)	Authority or delegate
protocol_treasury	AccountInfo	Required by context
system_program	Program	System program

Responses

200

Transaction succeeded

No content

post

/solana/withdraw-game

HTTPcURLJavaScriptPython

POST /functions/v1/solana/withdraw-game HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Accept: */*

200

Transaction succeeded

No content

Approve a delegate (session key) for the vault

post

Sets a delegate public key and nonce on the vault. The delegate can then act on behalf of the authority for game actions (join, switch, start, end, claim).

Accounts:

Name	Type	Description
user_vault	PDA (mut)	["vault", authority]
authority	Signer	Must be vault owner

Body

application/json

delegatestringRequired

Base58 public key of the delegate

nonceinteger · uint64Required

Monotonically increasing nonce to prevent replay

Responses

200

Transaction succeeded

No content

post

/solana/approve-delegate

HTTPcURLJavaScriptPython

POST /functions/v1/solana/approve-delegate HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "delegate": "text",
  "nonce": 1
}

200

Transaction succeeded

No content

Fund the delegate wallet from vault

post

Transfers lamports from the vault PDA to the delegate wallet to cover transaction fees. Only tops up if delegate balance is below target_lamports. Authority only.

Accounts:

Name	Type	Description
user_vault	PDA (mut)	Source of funds
delegate	AccountInfo (mut)	Must match vault.delegate
authority	Signer	Must be vault owner

Body

application/json

target_lamportsinteger · uint64Required

Desired delegate balance in lamports

Responses

200

Transaction succeeded

No content

post

/solana/fund-delegate

HTTPcURLJavaScriptPython

POST /functions/v1/solana/fund-delegate HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "target_lamports": 1
}

200

Transaction succeeded

No content

Update tier game configuration (admin only)

post

Updates selected fields of the GameConfig for a tier. All fields are optional; only provided values are changed.

Accounts:

Name	Type	Description
global_state	PDA (mut)	Tier to update
admin	Signer	Must match global_state.admin

Body

application/json

min_playersinteger · uint32 · nullableOptional

game_durationinteger · int64 · nullableOptional

Seconds

countdown_durationinteger · int64 · nullableOptional

Seconds

entry_feeinteger · uint64 · nullableOptional

Lamports

Responses

200

Transaction succeeded

No content

post

/solana/update-game-config

HTTPcURLJavaScriptPython

POST /functions/v1/solana/update-game-config HTTP/1.1
Host: bfzwyektprcrecwugify.supabase.co
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "min_players": 1,
  "game_duration": 1,
  "countdown_duration": 1,
  "entry_fee": 1
}

200

Transaction succeeded

No content