Developer DocumentationPlaykit Integration
Player balance, deposits, withdrawals, transactions, and vault funding.
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.
Burns are wallet-side, not Game Balance
Burns are wallet-side on-chain transfers and never appear in Game Balance — they live on the Burns page.
Import { forest } from @forest/runtime for the frontend calls below. Legacy HTML uploads use the same method names through the callForest bridge.
The hosted backend can read the verified player's balance and history directly:
const balance = await ctx.forest.game.getBalance();
const history = await ctx.forest.game.getTransactions({ page: 1, perPage: 20 });
const vault = await ctx.forest.game.getVaultCapacity();
// balance.balance and vault.capacity are display strings.Deposits and withdrawals remain frontend wallet actions.
forest.game.balanceReads the current player's Game Balance for this game.
await 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 with forest.game.burns() or the hosted backend's ctx.forest.game.getBurnSummary(). Legacy HTML also has a forest.game.burns.summary RPC.
forest.game.depositAsks 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.
await forest.game.deposit({
amount: "5",
});Prop
Type
Successful responses return:
{
txHash: "0x...",
balance: {
balance: "15",
totalDeposited: "15",
totalWithdrawn: "0",
totalWagered: "2.5",
totalWon: "1.25"
}
}forest.game.withdrawAsks Forest to withdraw player Game Balance back to the connected wallet. The Game Vault must cover the amount; an underfunded vault blocks withdrawals. 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.
await forest.game.withdraw({
amount: "2.5",
});Prop
Type
Successful responses return the same shape as forest.game.deposit.
Deposits and withdrawals are Forest-owned wallet flows
Do not self-credit deposits or sign withdrawals from your game server. After either call
succeeds, render result.balance or request forest.game.balance again.
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:
forest.game.transactions — each claim row carries id, status, requestId, and txHash.forest.game.withdraw again with the same amount — Forest reuses the existing pending claim and re-prompts the wallet.No cancel — claims are finalize-only
If a player abandons a pending claim, Forest releases the reservation automatically once it is confirmed unspent on-chain, so the player's balance returns with no client action. Do not build a "cancel claim" control.
forest.game.transactionsReads the current player's paginated Game Balance / Vault activity for this game — deposits, funding, and withdrawal claims (each claim row is a withdrawal request).
await forest.game.transactions({
page: 1,
perPage: 20,
});Prop
Type
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:
Prop
Type
The meta object carries total, perPage, currentPage, and lastPage.
Player-scoped history
Both the frontend SDK and ctx.forest.game.getTransactions return the verified player's
history. They are not a creator/admin listing of every player's withdrawal requests.
Burns are a separate domain
Burns are not in this feed — use forest.game.burns for the player's recorded burns. See
Burns.
A Harness game with a positive reward-pool allocation gets a Game Vault during launch. Legacy HTML games can also use a vault.
The Game Vault is the project's payout capacity. It is separate from a player's Game Balance:
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.
Funding is not an iframe RPC method
Do not ask uploaded HTML to transfer funds or record vault funding. The frontend has no
vault-funding RPC. A hosted backend can read capacity with ctx.forest.game.getVaultCapacity().
Keep creator funding controls in Forest project tools or another trusted creator/admin surface.
Call forest.game.balance only when you need the current player's playable balance.
A creator-side flow should:
Transfer Project Tokens to the project's Game Vault address.
Wait for the on-chain transfer to be mined and capture its transaction hash.
Record the funding transaction through the authenticated Forest API:
POST/playables/{projectId}/{gameEntity}/fundPOST /playables/{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.