Game Balance

Buying Project Token gives the player wallet-held tokens. It does not increase Game Balance. Game Balance is the deposited amount that can be debited or credited by walletless Game Actions. For the relationship between wallet, Game Balance, and Game Vault, see Core balances. Amounts are display decimal strings.

forest.game.balance

Reads the current player's Game Balance for this HTML project.

callForest("forest.game.balance");

Successful responses return:

{
  balance: "10",
  totalDeposited: "10",
  totalWithdrawn: "0",
  totalWagered: "2.5",
  totalWon: "1.25"
}

forest.game.balance is the player's Game Balance (internal ledger) state only. Burns do not appear here — read them from forest.game.burns / forest.game.burns.summary.

forest.game.deposit

Asks Forest to deposit wallet-held Project Token into the player's Game Balance. Forest opens the connected wallet, submits the on-chain deposit transaction, verifies the transaction through the API, then returns the updated Game Balance.

callForest("forest.game.deposit", {
	amount: "5",
});

Successful responses return:

{
  txHash: "0x...",
  balance: {
    balance: "15",
    totalDeposited: "15",
    totalWithdrawn: "0",
    totalWagered: "2.5",
    totalWon: "1.25"
  }
}

forest.game.withdraw

Asks Forest to withdraw player Game Balance back to the connected wallet. Forest requests the withdrawal signature from the API, opens the connected wallet, submits the on-chain withdrawal, confirms it through the API, then returns the updated Game Balance.

callForest("forest.game.withdraw", {
	amount: "2.5",
});

Successful responses return the same shape as forest.game.deposit.

Claim lifecycle

A withdrawal is a claim that is meant to reach completed. Each claim is pending (reserved, awaiting the wallet), completed (paid on-chain), or failed (reverted, balance restored). Your game owns surfacing claim state; Forest owns reverting it:

• Track a claim with forest.game.transactions — each claim row carries id, status, requestId, and txHash.
• Retry by calling forest.game.withdraw again with the same amount — Forest reuses the existing pending claim and re-prompts the wallet.

forest.game.transactions

Reads the current player's paginated Game Balance / Vault activity for this HTML project — deposits, funding, and withdrawal claims (each claim row is a withdrawal request).

callForest("forest.game.transactions", {
	page: 1,
	perPage: 20,
});

Successful responses return:

{
  data: [
    {
      id: "transaction-id",
      type: "deposit",
      amount: "5",
      status: "confirmed",
      txHash: "0x…",
      createdAt: "2026-06-01T12:00:00.000Z"
    }
  ],
  meta: {
    total: 1,
    perPage: 20,
    currentPage: 1,
    lastPage: 1
  }
}

Each data entry has the following shape:

The meta object carries total, perPage, currentPage, and lastPage.

Game Vault Funding

HTML projects use a Game Vault.

The Game Vault is the project's payout capacity. It is separate from a player's Game Balance:

• Game Vault funding lets the project pay player winnings.
• Player Game Balance is the deposited, playable balance for one player.
• Funding the Game Vault does not credit any player.
• A player deposit does not add project payout capacity.

If the Game Vault runs out, credit-producing settlements can fail even when the player's action was authorized. The creator must top up the Game Vault with Project Tokens, then Forest must record that funding transaction.

A creator-side flow should:

POST /campaigns/{projectId}/html/fund
Content-Type: application/json

{
	"txHash": "0x..."
}

Forest verifies the transaction on-chain before increasing recorded Game Vault capacity. The transfer token must be the project's token, and the recipient must be the project's Game Vault.

Creators can fund the Game Vault and inspect recent vault funding records from the Forest project edit page. That owner-only history is separate from player transaction history.