Overview

What Forest Playkit is, how it's structured, and the core concepts for developers.

Forest Playkit is your toolkit for building HTML games and apps that live natively inside Forest Protocol.

Your app runs inside an iframe on the token page and communicates with Forest through browser postMessage calls. With Playkit you can read the connected wallet, request swap quotes, submit swaps through the user's wallet, and tap into player-scoped game APIs. No package to install. No build step required.

New here? Start with the Quickstart — you'll have a working bridge and your first call running in minutes. This page covers the mental model behind it.

Building with an AI agent?

Install the Forest AI skill so Claude Code, Cursor, Codex, and other agents write correct Playkit code — npx skills add Forest-Protocol/forest-skills.

Code examples

Throughout these docs:

Client snippets are JavaScript and are valid TypeScript as-is.
Backend snippets are Node.js.
HTTP endpoints are shown as a raw request, plus a cURL example where useful.
Amounts in client (iframe) calls are display decimals; signed backend bodies use base-unit integer strings.

The two surfaces

Every integration is split across two trust boundaries. Keep them straight and the rest of the SDK follows.

The iframe (client). Your uploaded HTML. It calls Forest RPC methods to read state and to ask Forest to open the user's wallet. It is untrusted — anything it reports can be forged by the player in their own browser.
Your trusted backend (server). Holds the Settlement Signing Secret and is the only place allowed to produce credit (settlements), execute swap sessions, redeem identity, and record burns. The browser can request these, but only your server can authorize them.

Forest sits between the two: it mediates wallet actions for the iframe and verifies your backend's signed requests.

Core balances

Three different pools of value — do not conflate them:

Concept	What it is
Wallet-held Project Token	Tokens in the player's own wallet. Buying gives them these; it does not add Game Balance.
Game Balance	A per-player internal ledger Forest debits/credits through walletless Game Actions.
Game Vault	The project's payout capacity. Separate from any player; funds winnings. Creator-funded.

How value moves between them:

A player deposit moves wallet tokens into their Game Balance.
Funding the Game Vault does not credit any player.
A player deposit does not add payout capacity.

Amounts: display vs base units

This trips people up, so it is the single rule to remember:

You send display amounts. In HTML SDK params, use normal token display strings like "1", "0.25", or "1000.5". No wei/base-unit values, commas, token symbols, or unit suffixes.
Signed backend bodies and session/settlement responses use base units. Forest converts display request amounts to base-unit integer strings inside the Forest-owned web bridge before it calls the API or opens the wallet. Auto-swap session response budgets and trusted backend settlement/execution/burn amount fields are base-unit integer strings.

Both sides must be the same economic value

When a backend signs an amount that the iframe also passed, the two must represent the same economic value: display units in the SDK call, base-unit integer in the signed body.

Identity is not the wallet address

Never use the iframe wallet address for identity

Forest sends the connected wallet address to the iframe for display only. Once it reaches your HTML it is a plain string the player can rewrite, so:

Never use it for backend identity or accounting.
When your backend needs to know which Forest player is in the session, run the Player Identity handshake instead.

Persistent game data

Game Balance and Game Actions cover Forest's economic ledger — debits, credits, and settlement. They do not cover everything else your game needs to remember: match history, player stats, inventories, cosmetics, or a leaderboard. For that, you need your own live database.

Keep it on your trusted backend, not in the iframe

Your HTML game already talks to a trusted backend to sign settlements (see Game Actions). That same backend should hold your database connection string. The iframe is untrusted — never put credentials or queries in it.

A typical leaderboard flow:

TXT

HTML game
  -> forest.game.action.authorize({ actionId, debitLimitAmount })
  -> your backend validates the gameplay result
  -> your backend signs and submits the settlement to Forest
  -> your backend writes the result to your own database (score, playerId, timestamp)
  -> HTML game reads the leaderboard from your backend's API

Key the data by the verified Player Identity, never the display-only wallet address.

If you don't already run a database:

Provider	Good for
Railway	One-click Postgres/MySQL/Redis/MongoDB next to your backend service; usage-based billing, fast to set up
Render	Managed Postgres + Redis with flat, predictable monthly pricing; similar git-push workflow to Railway
Supabase	Hosted Postgres with a realtime layer and auto-generated REST/GraphQL API — a leaderboard that updates live without polling

Building with an AI agent? The Forest AI skill can scaffold the schema, migrations, and backend handler for you.

What you can use

Swaps

Quote, buy, and sell Project Token through the connected wallet.

Swap Sessions

User-approved auto-swap sessions and trusted execution.

Game Balance

Read, deposit to, and withdraw the player's playable balance.

Burns

Burn wallet-held Project Token on-chain for in-game sinks.

Game Actions

One-use authorizations for trusted backend settlement.

Player Identity

Wallet events and the verified-player handshake.

For the request/response envelope and the full method list, see the RPC Reference.

Forest Playkit is your toolkit for building HTML games and apps that live natively inside Forest Protocol.

New here? Start with the Quickstart — you'll have a working bridge and your first call running in minutes. This page covers the mental model behind it.

Building with an AI agent?

Install the Forest AI skill so Claude Code, Cursor, Codex, and other agents write correct Playkit code — npx skills add Forest-Protocol/forest-skills.

Code examples

Throughout these docs:

Client snippets are JavaScript and are valid TypeScript as-is.
Backend snippets are Node.js.
HTTP endpoints are shown as a raw request, plus a cURL example where useful.
Amounts in client (iframe) calls are display decimals; signed backend bodies use base-unit integer strings.

The two surfaces

Every integration is split across two trust boundaries. Keep them straight and the rest of the SDK follows.

The iframe (client). Your uploaded HTML. It calls Forest RPC methods to read state and to ask Forest to open the user's wallet. It is untrusted — anything it reports can be forged by the player in their own browser.
Your trusted backend (server). Holds the Settlement Signing Secret and is the only place allowed to produce credit (settlements), execute swap sessions, redeem identity, and record burns. The browser can request these, but only your server can authorize them.

Forest sits between the two: it mediates wallet actions for the iframe and verifies your backend's signed requests.

Core balances

Three different pools of value — do not conflate them:

Concept	What it is
Wallet-held Project Token	Tokens in the player's own wallet. Buying gives them these; it does not add Game Balance.
Game Balance	A per-player internal ledger Forest debits/credits through walletless Game Actions.
Game Vault	The project's payout capacity. Separate from any player; funds winnings. Creator-funded.

How value moves between them:

A player deposit moves wallet tokens into their Game Balance.
Funding the Game Vault does not credit any player.
A player deposit does not add payout capacity.

Amounts: display vs base units

This trips people up, so it is the single rule to remember:

You send display amounts. In HTML SDK params, use normal token display strings like "1", "0.25", or "1000.5". No wei/base-unit values, commas, token symbols, or unit suffixes.
Signed backend bodies and session/settlement responses use base units. Forest converts display request amounts to base-unit integer strings inside the Forest-owned web bridge before it calls the API or opens the wallet. Auto-swap session response budgets and trusted backend settlement/execution/burn amount fields are base-unit integer strings.

Both sides must be the same economic value

When a backend signs an amount that the iframe also passed, the two must represent the same economic value: display units in the SDK call, base-unit integer in the signed body.

Identity is not the wallet address

Never use the iframe wallet address for identity

Forest sends the connected wallet address to the iframe for display only. Once it reaches your HTML it is a plain string the player can rewrite, so:

Never use it for backend identity or accounting.
When your backend needs to know which Forest player is in the session, run the Player Identity handshake instead.

Persistent game data

Keep it on your trusted backend, not in the iframe

A typical leaderboard flow:

TXT

HTML game
  -> forest.game.action.authorize({ actionId, debitLimitAmount })
  -> your backend validates the gameplay result
  -> your backend signs and submits the settlement to Forest
  -> your backend writes the result to your own database (score, playerId, timestamp)
  -> HTML game reads the leaderboard from your backend's API

Key the data by the verified Player Identity, never the display-only wallet address.

If you don't already run a database:

Provider	Good for
Railway	One-click Postgres/MySQL/Redis/MongoDB next to your backend service; usage-based billing, fast to set up
Render	Managed Postgres + Redis with flat, predictable monthly pricing; similar git-push workflow to Railway
Supabase	Hosted Postgres with a realtime layer and auto-generated REST/GraphQL API — a leaderboard that updates live without polling

Building with an AI agent? The Forest AI skill can scaffold the schema, migrations, and backend handler for you.

Overview

Core balances

Amounts: display vs base units

Identity is not the wallet address

Persistent game data

What you can use

Swaps

Swap Sessions

Game Balance

Burns

Game Actions

Player Identity

On this page

Overview

Core balances

Amounts: display vs base units

Identity is not the wallet address

Persistent game data

What you can use

Swaps

Swap Sessions

Game Balance

Burns

Game Actions

Player Identity

On this page