# Forest Docs

---



---

# Forest Docs

> Technical and creator documentation for Forest Protocol.

Source: https://forest.inc/docs

Forest Protocol is a modular creation protocol on BNB Chain where every token launches with configurable mechanics, built-in apps and games, native staking, and a protocol-wide economy. Creators configure the launch. Playkit provides the infrastructure. The $FOREST economy powers the liquidity. Builders, studios, and AI agents all operate on the same stack.

Choose the path that matches what you want to do.

## Getting Started

<Cards>
	<Card
		title="Creator Playbook"
		href="/docs/creator-playbook"
		description="Launch checklist and creator workflow for playable tokens."
	/>
	<Card
		title="Wallet and Gas"
		href="/docs/creator-playbook/wallet-and-gas"
		description="Prepare your wallet, BNB for gas, and project details."
	/>
	<Card
		title="Launch Flow"
		href="/docs/creator-playbook/launch-flow"
		description="Follow the six steps from project setup to an on-chain launch."
	/>
</Cards>

## Protocol and Economy

<Cards>
	<Card
		title="Core Concepts"
		href="/docs/whitepaper/core-concepts-overview"
		description="The mechanics behind every token launch on Forest."
	/>
	<Card
		title="Launch Tokenomics"
		href="/docs/whitepaper/launch-tokenomics"
		description="Supply, fees, curves, buybacks, and distribution."
	/>
	<Card
		title="How Forest Playkit Works"
		href="/docs/whitepaper/forest-playkit"
		description="The protocol infrastructure behind app and game economies."
	/>
	<Card
		title="Forest Builder"
		href="/docs/whitepaper/forest-builder"
		description="A prompt-native creation layer for Forest Protocol."
	/>
	<Card
		title="Forest Cloud"
		href="/docs/whitepaper/forest-cloud"
		description="The always-on autonomous infrastructure layer where AI agents run on Forest Protocol."
	/>
	<Card
		title="$FOREST & Seed Economy"
		href="/docs/whitepaper/forest-and-seed-economy"
		description="The economics behind Forest Protocol."
	/>
	<Card
		title="The Vision"
		href="/docs/whitepaper/the-vision"
		description="A glimpse into Forest Protocol’s future and trajectory."
	/>
</Cards>

## Technical Documentation

<Cards>
	<Card
		title="Playkit Integration"
		href="/docs/developers/forest-playkit"
		description="Build an HTML app or game on Forest's RPC and settlement infrastructure."
	/>
	<Card
		title="Playkit Quickstart"
		href="/docs/developers/forest-playkit/quickstart"
		description="Add the Forest bridge and make your first call."
	/>
	<Card
		title="AI Skill"
		href="/docs/developers/ai-skill"
		description="Give your coding agent Forest's integration knowledge."
	/>
</Cards>


---

# Overview

> Launch a playable token on Forest — upload your own game or build one from a prompt.

Source: https://forest.inc/docs/creator-playbook

Forest is designed so creators can launch a playable token in minutes. This playbook prepares your wallet, walks you through the launch flow, and covers the two ways to bring your own game.

<Cards>
	<Card
		title="Before you start"
		href="/docs/creator-playbook/wallet-and-gas"
		description="Wallet, gas, and project details you need."
	/>
	<Card
		title="The launch flow"
		href="/docs/creator-playbook/launch-flow"
		description="Six steps from project info to live on-chain."
	/>
	<Card
		title="Key links"
		href="/docs/creator-playbook/key-links"
		description="Website, docs, and community."
	/>
</Cards>

## Forest Playkit — Upload Your Own Game

Forest Playkit is the infrastructure layer that connects any HTML5 app or game to your token's economy and deploys it on chain. Upload your own game, attach it to your token, and Playkit handles wallets, in-game trading, game vaults, settlement, leaderboards, and reward pools. You do not need to write smart contracts or wire wallet libraries. Games that produce credits or use trusted actions still need a backend to validate results and sign settlement requests.

**What Playkit handles for you:**

- **Wallet connection** — players connect once; the game reads their wallet automatically
- **In-game trading** — buy and sell your token without leaving the game
- **Game Balance** — players deposit tokens to play, and withdraw earnings back to their wallet
- **Game Vault** — your token's payout reserve, funded at launch and enforced by Forest
- **Settlement** — your backend validates results; Playkit verifies and records signed settlements
- **Leaderboards and reward pools** — reward pools are built in; leaderboards are built in for Forest-hosted games, while self-hosted games store scores on their own backend

→ [Full Playkit integration documentation and code examples](/docs/developers/forest-playkit)

## Forest Builder — Build Your Own Game

Forest Builder is a prompt-native creation layer. Describe a game, app, or experience and Forest Builder assembles it on Playkit infrastructure, configures the token mechanics, and deploys it live on Forest Protocol. One conversation to a live token economy on BNB Chain.

<Steps>

<Step>

### Describe

Describe your game, app, or experience to Forest Builder.

</Step>

<Step>

### Assemble

Forest Builder assembles it on Playkit infrastructure — wallets, trading, vaults, settlement, and leaderboards all wired in automatically.

</Step>

<Step>

### Configure

Configure your token mechanics — supply, bonding curve, staking, and fees.

</Step>

<Step>

### Deploy

Review and deploy — your app is live with $FOREST-backed liquidity from the first trade.

</Step>

</Steps>


---

# Key Links

> Useful links for Forest creators.

Source: https://forest.inc/docs/creator-playbook/key-links

## Key Links

| Type         | Link                                                       |
| ------------ | ---------------------------------------------------------- |
| **Website**  | [https://forest.inc/](https://forest.inc/)                 |
| **Docs**     | [https://docs.forest.inc](https://docs.forest.inc)         |
| **Discord**  | [https://discord.gg/NnHk3hfTmZ](https://discord.gg/NnHk3hfTmZ) |
| **Telegram** | [https://t.me/ProtocolForest](https://t.me/ProtocolForest) |


---

# Launch Flow

> Step-by-step playable token launch flow.

Source: https://forest.inc/docs/creator-playbook/launch-flow

Forest is designed so creators can launch a playable token in minutes. The platform guides you step by step through the full creation and publish process.

<Steps>

<Step>

### Project Info

Enter your token name, ticker symbol, and description. Upload a project image. Optionally add social links. All tokens launch with a fixed supply of **1,000,000,000 tokens**.

</Step>

<Step>

### Choose a Template

Select a template. Templates define what your token does — **Multimedia/Meme**, **Staking**, **Coinflip**, **Lucky Reel**, or **HTML5 Game Upload** (your own game) with an in-built on-chain token economy. Each template has its own configuration options.

</Step>

<Step>

### Customise

Adjust colors, branding, and image uploads. Template-specific gameplay parameters (like odds, house edge, reveal speeds, or game speed) can also be adjusted here.

</Step>

<Step>

### Tokenomics

Allocate your 1B supply across:

- Liquidity
- Treasury
- Staking rewards
- Rewards / game vault

Percentages must total **100%**. Pick a graduation threshold — the amount of $FOREST the pool must collect before your token graduates to the open DEX. Set your buy and sell fees — fees can differ during the bonding curve phase and equalise automatically after graduation.

</Step>

<Step>

### Launch on-chain

Forest deploys your token in four on-chain steps:

1. Deploy token contract
2. Verify contract
3. Create liquidity pool
4. Finalise template configuration

Each step requires a wallet confirmation using **BNB** for gas.

</Step>

<Step>

### Live

Your token and game go live on **BNB Chain**. Share the link, run campaigns, and track activity in real time. You can save drafts or redeploy at any time.

**Redeploying starts a new bonding-curve phase.**

</Step>

</Steps>


---

# Wallet and Gas

> What you need before launching on Forest — wallet, gas, and project details.

Source: https://forest.inc/docs/creator-playbook/wallet-and-gas

## Before You Start

Forest runs entirely on **BNB Chain**. Connect your wallet at [forest.inc](https://forest.inc) to begin.

**You'll need:**

- A BNB Chain wallet (MetaMask, Binance Wallet — more wallets are being added soon)
- BNB for gas — required for token deployment and on-chain actions
- Your project details ready: name, ticker, image, description

## BNB Chain Network Details

| Field            | Value                                                            |
| ---------------- | ---------------------------------------------------------------- |
| **Network Name** | BNB Chain                                                        |
| **RPC URL**      | [https://bsc-rpc.publicnode.com](https://bsc-rpc.publicnode.com) |
| **Chain ID**     | 56                                                               |
| **Symbol**       | BNB                                                              |
| **Explorer**     | [https://bscscan.com](https://bscscan.com)                       |


---

# AI Skill

> Install Forest's AI skill so your coding agent builds integrations correctly — Claude Code, Cursor, Codex, and any SKILL.md-compatible agent.

Source: https://forest.inc/docs/developers/ai-skill

Building on Forest with an AI agent? Install the official **Forest skills** — our developer docs
packaged as [Agent Skills](https://agentskills.io/specification) your assistant loads on demand.
`html-playkit` teaches the agent the Playkit two-surface trust model, display-vs-base-unit
amounts, the verified-identity handshake, and the full RPC surface — so it writes correct code
instead of guessing. `portfolio` teaches it to read positions, PnL, and live prices across
Forest tokens through the REST API and plan rebalances or take-profit moves (read-and-plan
only — no trade execution). More Forest skills land in the same package over time.

Source: [github.com/Forest-Protocol/forest-skills](https://github.com/Forest-Protocol/forest-skills).

## Install

<Tabs items={['Any agent (CLI)', 'Claude Code plugin', 'Manual']}>

<Tab value="Any agent (CLI)">

Works with Claude Code, Cursor, Codex, Copilot, Gemini, and any agent the
[skills CLI](https://skills.sh) supports:

```bash
npx skills add Forest-Protocol/forest-skills
```

Start a new agent session afterwards so it picks up the skill.

</Tab>

<Tab value="Claude Code plugin">

Register the repo as a plugin marketplace, then install the `forest` plugin:

```
/plugin marketplace add Forest-Protocol/forest-skills
/plugin install forest@forest-skills
```

</Tab>

<Tab value="Manual">

Symlink the skill into your agent's skills directory:

```bash
git clone https://github.com/Forest-Protocol/forest-skills
ln -s "$(pwd)/forest-skills/skills/html-playkit" ~/.claude/skills/html-playkit
```

</Tab>

</Tabs>

## What it covers

Once installed, ask your agent to build against Forest and it will pull in the right knowledge:

- The iframe (client) vs trusted-backend trust boundary
- Swaps and user-approved swap sessions
- Game Balance, burns, and game-action settlement
- The verified Player Identity handshake
- The RPC request/response envelope and error codes
- Standing up a live database for stats, metrics, and game state on your backend
- Reading positions, cost basis, PnL, and live prices across Forest tokens via the REST API
- Planning rebalances and take-profit moves from that data (execution stays in the Forest UI)

<Callout type="info" title="These docs stay canonical">
	The skill mirrors this documentation. When the two ever differ, the docs here are the source of
	truth — re-install the skill to pull the latest.
</Callout>

## Persistent game data

Beyond the economic ledger, most games need somewhere to keep score. The skill teaches the agent how to stand up and maintain a live database for three kinds of data:

- **Stats** — per-player counters that only go up: games played, wins, kills, items collected.
- **Metrics** — aggregate or time-series data you query later: session length, daily active players, average score per match.
- **Live game state** — a mutable "save file" per player that the game reads and overwrites as they play: current level, inventory, board position, in-progress run.

The agent sets this up on your trusted backend — the same server that holds the Settlement Signing Secret (see [Game Actions](/docs/developers/forest-playkit/game-actions)) — never in the iframe.

<Callout type="warn" title="Never query a database from the iframe">
	Your uploaded HTML is untrusted. Database credentials, connection strings, and queries belong
	only on your trusted backend. The agent will scaffold a small API on that backend for the game to
	call instead.
</Callout>

### Schema shape

The skill defaults to three tables (or collections), keyed by the verified player identity from the [Player Identity](/docs/developers/forest-playkit/identity) handshake — never the display-only wallet address:

```sql
-- append-only, one row per event
CREATE TABLE stats (
  player_id  TEXT NOT NULL,
  stat_key   TEXT NOT NULL,
  value      BIGINT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- one row per player, overwritten in place
CREATE TABLE game_state (
  player_id  TEXT PRIMARY KEY,
  state      JSONB NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- aggregates, refreshed on a schedule or on write
CREATE TABLE metrics (
  metric_key TEXT NOT NULL,
  period     DATE NOT NULL,
  value      BIGINT NOT NULL,
  PRIMARY KEY (metric_key, period)
);
```

`stats` stays append-only so history isn't lost. `game_state` is the one table the agent updates in place — it's the "living" file the game reads on load and writes on every meaningful change. `metrics` is for rollups your dashboard or leaderboard reads, kept separate so heavy aggregate queries don't lock the live tables.

### Where writes happen

Stat and state writes follow the same shape as a settlement, but they are **not** settlements — writing to `game_state` does not move Game Balance:

```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 to stats / game_state / metrics
  -> HTML game reads state back from your backend's API
```

Ask the agent to wire database writes into the same backend handler that signs the settlement, so a confirmed match always updates both the ledger and your stats in one place.

### Provider shortlist

If you don't already run a database, the agent can scaffold against any of these:

| Provider                         | Good for                                                                                                            |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Railway](https://railway.com)   | One-click Postgres/MySQL/Redis/MongoDB next to your backend service; usage-based billing, fast to set up           |
| [Render](https://render.com)     | Managed Postgres + Redis with flat, predictable monthly pricing                                                    |
| [Supabase](https://supabase.com) | Hosted Postgres with a realtime layer and auto-generated REST API — a leaderboard that updates live without polling |

Tell the agent which one you're using (or let it default to Railway) and it will generate the connection setup, migrations, and the backend handler above.


---

# Overview

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

Source: https://forest.inc/docs/developers/forest-playkit

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](/docs/developers/forest-playkit/quickstart) — you'll have a working bridge and your first call running in minutes. This page covers the mental model behind it.

<Callout type="info" title="Building with an AI agent?">
	Install the [Forest AI skill](/docs/developers/ai-skill) so Claude Code,
	Cursor, Codex, and other agents write correct Playkit code — `npx skills add Forest-Protocol/forest-skills`.
</Callout>

<Callout type="info" title="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.

</Callout>

<Callout title="The two surfaces" type="info">

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.

</Callout>

## 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.

<Callout type="warn" title="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.
</Callout>

## Identity is not the wallet address

<Callout type="warn" title="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](/docs/developers/forest-playkit/identity) handshake instead.

</Callout>

## 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.

<Callout type="warn" title="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](/docs/developers/forest-playkit/game-actions)). That same backend should hold your
	database connection string. The iframe is untrusted — never put credentials or queries in it.
</Callout>

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](/docs/developers/forest-playkit/identity), never the display-only wallet address.

If you don't already run a database:

| Provider                            | Good for                                                                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [Railway](https://railway.com)      | One-click Postgres/MySQL/Redis/MongoDB next to your backend service; usage-based billing, fast to set up                       |
| [Render](https://render.com)        | Managed Postgres + Redis with flat, predictable monthly pricing; similar git-push workflow to Railway                          |
| [Supabase](https://supabase.com)    | 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](/docs/developers/ai-skill) can scaffold the schema, migrations, and backend handler for you.

## What you can use

<Cards>
	<Card
		title="Swaps"
		href="/docs/developers/forest-playkit/swaps"
		description="Quote, buy, and sell Project Token through the connected wallet."
	/>
	<Card
		title="Swap Sessions"
		href="/docs/developers/forest-playkit/swap-sessions"
		description="User-approved auto-swap sessions and trusted execution."
	/>
	<Card
		title="Game Balance"
		href="/docs/developers/forest-playkit/game-balance"
		description="Read, deposit to, and withdraw the player's playable balance."
	/>
	<Card
		title="Burns"
		href="/docs/developers/forest-playkit/burns"
		description="Burn wallet-held Project Token on-chain for in-game sinks."
	/>
	<Card
		title="Game Actions"
		href="/docs/developers/forest-playkit/game-actions"
		description="One-use authorizations for trusted backend settlement."
	/>
	<Card
		title="Player Identity"
		href="/docs/developers/forest-playkit/identity"
		description="Wallet events and the verified-player handshake."
	/>
</Cards>

For the request/response envelope and the full method list, see the [RPC Reference](/docs/developers/forest-playkit/rpc-reference).


---

# Burns

> On-chain wallet burns for in-game sinks, with signed backend settlement.

Source: https://forest.inc/docs/developers/forest-playkit/burns

A burn is an **on-chain action**: the player sends Project Tokens from their own
wallet to a signed sink address — the dead address (`0x…dead`) by default, but the
backend may sign any destination. Forest records the verified on-chain transfer
with its `reason`/`metadata` for tracking. A transfer to `0x…dead` is a real,
provable supply burn; any other sink is just the app-chosen destination, not a
supply reduction.

Use it for in-game sinks such as activation fees. Burns are wallet-side and never touch [Game Balance](/docs/developers/forest-playkit/game-balance).

<Callout type="warn" title="Authorize before you transfer">
	The burn settlement requires an *unused* action authorization, so authorize **first** —
	otherwise the player can burn tokens on-chain and then fail Forest authorization/settlement,
	stranding the burn. The transfer is irreversible; the authorization is not.
</Callout>

The **developer backend owns the burn intent** — it decides `actionId`, `amount`,
`burnAddress`, `reason`, and `metadata`. The client only executes that exact intent
on-chain and relays the resulting `txHash` back; it does not choose the destination
or purpose.

## The burn flow

<Steps>

<Step>

### Intent and authorize

Your backend defines the intent (`actionId`, `amount`, `burnAddress`, `reason`,
`metadata`). The iframe calls
[`forest.game.action.authorize`](/docs/developers/forest-playkit/game-actions#forestgameactionauthorize)
with that `actionId` and a display-amount debit limit — which is also the
player-authorized **max burn amount**. Do **not** use `0`.

</Step>

<Step>

### Burn (client)

```js
callForest("forest.game.burn", {
	amount: "10", // display units
	burnAddress, // optional; defaults to 0x…dead
});
// response arrives via the message listener: { txHash, burnAddress }
```

Forest performs the on-chain transfer and returns `{ txHash, burnAddress }`
**after receipt confirmation** — it does not call any API, and never surfaces a
pending tx hash. Relay `txHash` and `burnAddress` to your backend.

</Step>

<Step>

### Settle (backend)

Your backend HMAC-signs and submits `POST /playables/{projectId}/html/burns` with
the **same** `actionId`, the **base-unit** `amount`, `txHash`, `burnAddress`,
`reason`, `metadata`, and `timestamp`. Forest verifies on-chain that exactly
`amount` Project Tokens moved from a linked wallet to `burnAddress`, then records
the burn. Game Balance is never touched.

</Step>

</Steps>

## Signed burn settlement

The signed amount is the **same economic amount** as the client burn — **display
units** in `forest.game.burn` (e.g. `"10"`), **base-unit integer** string in the
signed body (e.g. `"10000000000000000000"`).

<APILink method="POST" path="/playables/{projectId}/html/burns" />

```http
POST /playables/{projectId}/html/burns
Content-Type: application/json
X-Forest-Settlement-Signature: v1=<hex-hmac>
```

```js
await fetch(`${FOREST_API}/playables/${projectId}/html/burns`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-Forest-Settlement-Signature": `v1=${hmac}`,
	},
	body: JSON.stringify({
		actionId: "same-action-id",
		amount: "10000000000000000000", // base-unit integer string
		txHash: "0x…",
		burnAddress: "0x000000000000000000000000000000000000dead",
		timestamp: Math.floor(Date.now() / 1000),
		reason: "activation_fee",
		metadata: { item: "gold_miner_rig", level: 3 },
	}),
});
```

Request fields:

<TypeTable
	type={{
		actionId: {
			type: "string (UUID v4)",
			description: "Same UUID v4 used for forest.game.action.authorize.",
			required: true,
		},
		amount: {
			type: "string (base-unit integer)",
			description:
				"Positive Project Token base-unit integer (the display amount times 10^decimals). Must equal the on-chain transferred value exactly and not exceed the authorized debit limit.",
			required: true,
		},
		txHash: {
			type: "string (0x hash)",
			description:
				"Hash of the on-chain transfer from forest.game.burn. Verified against chain: sender is a linked wallet, recipient is burnAddress, token is the project token, value equals amount.",
			required: true,
		},
		burnAddress: {
			type: "string (0x address)",
			description:
				"Destination the tokens were burned to (the value returned by forest.game.burn, e.g. the dead address). Signed as part of the body.",
			required: true,
		},
		timestamp: {
			type: "number (Unix seconds)",
			description: "Current Unix timestamp in seconds. Generate it when sending the request.",
			required: true,
		},
		reason: {
			type: "string (slug)",
			description:
				"Optional stable lowercase slug (a-z, 0-9, _, e.g. activation_fee) that Forest groups and aggregates burns by. Signed, so it cannot be client-forged.",
		},
		metadata: {
			type: "object",
			description:
				"Optional free-form object for your own context. Signed, stored, and echoed back as-is (not Forest-interpreted). Capped at 4 KB serialized.",
		},
	}}
/>

Sign the exact request body with your Settlement Signing Secret, identical to the
[settlement flow](/docs/developers/forest-playkit/game-actions#trusted-settlement). Successful responses return:

```js
{
  burnId: "burn-id",
  actionId: "same-action-id",
  amount: "10",
  reason: "activation_fee",
  metadata: { item: "gold_miner_rig", level: 3 },
  txHash: "0x…",
  burnAddress: "0x000000000000000000000000000000000000dead",
  replayed: false
}
```

<Callout type="info" title="Retrying a burn settlement">
Burns are idempotent by `actionId`. A safe retry MUST replay the **same
`actionId`, the exact same JSON body, and the same signature**, and arrive
**within the request-freshness window (~5 min)**. An exact replay returns
`replayed: true`. After the window, do **not** retry — confirm the burn settled by
looking up its `burnId` in `forest.game.burns`.

Idempotency is keyed on `actionId`, not `txHash`: a `txHash` backs exactly one
burn, and a `txHash` already recorded as a deposit is a conflict.

</Callout>

Burns do **not** change Game Balance (the tokens are burned straight from the
wallet) and are **not** part of `forest.game.transactions`.

Replay and validation failures return the shared settlement error codes —
`SETTLEMENT_TIMESTAMP_STALE`, `ACTION_ID_REUSED`, `BURN_TX_HASH_REUSED`,
`DEBIT_LIMIT_EXCEEDED`, `INVALID_SETTLEMENT_AMOUNT`, and signature errors. See
[Errors and Security](/docs/developers/forest-playkit/errors-security#settlement-errors)
for each code's cause and resolution.

## Reading burns

`forest.game.burns` returns the current player's recorded burns (paginated,
newest first); `forest.game.burns.summary` returns the player's totals grouped by
`reason`. Both are player-scoped iframe reads (like `forest.game.balance`).

```js
callForest("forest.game.burns", { page: 1, perPage: 20 });
// response: { data, meta } — data[]: { id, amount, reason, metadata, txHash, burnAddress, createdAt }

callForest("forest.game.burns.summary");
// response: { totalBurned, byReason: [{ reason, amount, count }] }
```

`totalBurned` here is "verified burn/sink settlements" — not necessarily supply
reduced (only dead/zero destinations reduce supply). Burns sent without a `reason`
are grouped under `reason: null`. Amounts are display token amount strings.

Token-level burn history is separate from Game Balance history. The token Burns
tab is populated from synced on-chain token transfers to the burn address or zero
address, alongside backend buyback burns.


---

# Errors and Security

> Error-code reference and security rules for HTML template integrations.

Source: https://forest.inc/docs/developers/forest-playkit/errors-security

## Error Handling

Handle `error` responses as first-class UI states. The user may reject a wallet request, the quote may fail, or the token may not support swaps.

```js
if (data.status === "error") {
	showError(data.error.code, data.error.message);
}
```

This page is the reference for Forest HTML SDK error codes. Domain pages link here instead of repeating codes inline.

REST endpoints can also return normal HTTP validation errors without an app-specific `code` field, for example when a project or session is not found, auto-swaps are disabled, a route `sessionId` does not match the signed body, or a transaction fails chain validation. Treat those as terminal request failures and read the returned `message`.

## Wallet and RPC errors

Returned to the iframe over the RPC interface.

| Code                               | Cause                                                                                                  | Resolution                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `WALLET_NOT_CONNECTED`             | The action needs a connected wallet and none is connected.                                             | Prompt the user to connect a wallet first.                                                    |
| `USER_REJECTED`                    | The user rejected a wallet request.                                                                    | Leave state unchanged and let the user retry explicitly.                                      |
| `TRANSACTION_FAILED`               | A submitted wallet transaction failed, reverted, or was replaced/underpriced.                          | Show the failure and let the user retry after checking wallet state.                          |
| `UNKNOWN_ERROR`                    | Forest could not map the failure to a more specific SDK code, or the RPC request envelope was invalid. | Log the message, verify the request shape, and show a generic retry state.                    |
| `INVALID_PARAMS`                   | The RPC params are missing or have the wrong shape.                                                    | Fix the params for the method (use `{}` when there are none).                                 |
| `GAME_BALANCE_FAILED`              | Forest could not load the player Game Balance.                                                         | Surface a transient error state and retry.                                                    |
| `GAME_TRANSACTIONS_FAILED`         | Forest could not load the player's Game Balance transaction feed.                                      | Surface a transient error state and retry.                                                    |
| `GAME_BURN_FAILED`                 | Forest could not complete the wallet-side burn transfer.                                               | Show the error, do not settle the burn, and let the user retry with a fresh intent if needed. |
| `GAME_WALLET_ACTION_IN_PROGRESS`   | A wallet-side game action is already in progress.                                                      | Wait for the in-flight action to finish before starting another.                              |
| `GAME_WALLET_UNAVAILABLE`          | Deposit or withdrawal is not configured for this game.                                                 | Hide wallet controls — the project has no wallet flow.                                        |
| `GAME_ACTION_AUTHORIZATION_FAILED` | Forest could not create an Action Authorization.                                                       | Retry with a fresh UUID v4 `actionId`.                                                        |

## Swap and session errors

| Code                    | Cause                                                                | Resolution                                                      |
| ----------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------- |
| `INVALID_AMOUNT`        | The swap amount is missing, zero, negative, or not a finite decimal. | Ask the user for a positive display amount.                     |
| `QUOTE_FAILED`          | Forest could not quote the requested amount.                         | Retry, or adjust the amount.                                    |
| `SWAP_UNAVAILABLE`      | This token cannot be swapped through the current route.              | Disable swap UI for this token.                                 |
| `SWAP_IN_PROGRESS`      | A swap or session wallet flow is already in progress.                | Wait for the in-flight flow to finish before starting another.  |
| `CONFIG_TIMEOUT`        | Direction or slippage did not apply in time.                         | Re-apply the config and retry.                                  |
| `SWAP_SESSION_DISABLED` | Auto-swaps are disabled for this project.                            | Do not render session controls — `autoSwapsEnabled` is `false`. |
| `SWAP_SESSION_FAILED`   | Forest could not create or load the swap session.                    | Retry, or have the user recreate the session.                   |

## Settlement errors

Returned by the signed backend APIs for settlement and burns, and by the shared HMAC/timestamp checks used by identity redeem and swap-session execution. Swap-session execution can also return uncoded HTTP errors for session state or route validation.

| Code                                       | Cause                                                                                            | Resolution                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `GAME_SETTLEMENT_SIGNING_SECRET_MISSING`   | The project has no active Settlement Signing Secret.                                             | Create a secret in the project editor's HTML Settlement card.                                 |
| `RAW_BODY_UNAVAILABLE`                     | Forest could not access the exact raw request body needed for HMAC verification.                 | Ensure the request is sent as a normal JSON body and contact Forest support if this persists. |
| `SETTLEMENT_SIGNATURE_MISSING`             | The `X-Forest-Settlement-Signature` header is missing.                                           | Send the signature header on every signed request.                                            |
| `SETTLEMENT_SIGNATURE_VERSION_UNSUPPORTED` | The header does not use the `v1=` format.                                                        | Prefix the hex HMAC with `v1=`.                                                               |
| `SETTLEMENT_SIGNATURE_MALFORMED`           | The signature is not a 64-character hex HMAC.                                                    | Hex-encode the full HMAC-SHA256 digest.                                                       |
| `INVALID_SETTLEMENT_SIGNATURE`             | The request body does not match the signature.                                                   | Sign the exact bytes you send — do not reserialize the body after signing.                    |
| `ACTION_AUTHORIZATION_UNAVAILABLE`         | The action was not authorized, was already used, or expired.                                     | Re-authorize with a fresh `actionId`, created close to the action.                            |
| `SETTLEMENT_TIMESTAMP_STALE`               | The signed `timestamp` is outside the request-freshness window (~5 min).                         | On retry, replay the **original** signed body — never re-sign with a new timestamp.           |
| `ACTION_ID_REUSED`                         | The same `actionId` was reused with a different request body.                                    | Resend the byte-identical body, or use a new `actionId` for a new action.                     |
| `INVALID_SETTLEMENT_AMOUNT`                | The amounts are invalid (e.g. negative, or both `0` for a settlement).                           | Send non-negative base-unit integer strings; at least one of debit/credit `> 0`.              |
| `INVALID_SETTLEMENT_METADATA`              | Burn `metadata` exceeds the serialized size limit.                                               | Keep signed metadata under 4 KB.                                                              |
| `DEBIT_LIMIT_EXCEEDED`                     | The amount exceeds the authorized debit limit.                                                   | Authorize a debit limit at least the amount (never `0` for a burn).                           |
| `BURN_TXHASH_REQUIRED`                     | A burn settlement omitted the required on-chain `txHash`.                                        | Submit burns only after `forest.game.burn` returns a confirmed transaction hash.              |
| `BURN_TX_HASH_REUSED`                      | The `txHash` is already recorded under a different `actionId`, or already recorded as a deposit. | Do not replay an old burn — each `txHash` backs exactly one burn.                             |

<Callout type="info" title="Two authorization codes, not one">
	`GAME_ACTION_AUTHORIZATION_FAILED` (RPC) means the *authorize* step could not create an
	authorization. `ACTION_AUTHORIZATION_UNAVAILABLE` (settlement) means the authorization was
	missing, already used, or expired at *settle* time. They are distinct stages — do not treat them
	as the same error.
</Callout>

## Identity errors

| Code                     | Cause                                                               | Resolution                                                                |
| ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `IDENTITY_CODE_FAILED`   | Forest could not issue an identity code through the iframe RPC.     | Ensure the player is connected and retry with a fresh nonce.              |
| `IDENTITY_NO_WALLET`     | The current Forest session has no wallet bound when issuing a code. | Ask the player to reconnect their wallet, then restart the identity flow. |
| `IDENTITY_CODE_INVALID`  | The backend tried to redeem an unknown identity code.               | Restart the identity flow and redeem the fresh code server-to-server.     |
| `IDENTITY_CODE_CONSUMED` | The identity code was already redeemed (codes are single-use).      | Do not retry redeem — issue a fresh code by restarting at login.          |
| `IDENTITY_CODE_EXPIRED`  | The identity code expired before redemption.                        | Issue a fresh code and redeem it immediately.                             |

## Security Notes

<Callout type="warn" title="Treat the iframe boundary as untrusted">

- Verify the `type` and shape of every incoming message before acting on it.
- Keep request ids unique.
- Do not assume your iframe can access parent-page storage, wallet providers, cookies, or settlement secrets.
- Forest-owned browser actions go through this message interface; credit-producing settlement must go through a trusted backend.

</Callout>

The `FOREST_WALLET_CONNECTED` address is display-only and forgeable by the player. Never use it for backend identity, anti-abuse, or accounting — resolve the player through the [Player Identity](/docs/developers/forest-playkit/identity) flow instead. Credit always lands on the Forest player who authorized the action; your backend cannot redirect it to an arbitrary recipient.


---

# Game Actions

> Action authorization and trusted backend settlement for game actions.

Source: https://forest.inc/docs/developers/forest-playkit/game-actions

Game Actions are walletless in-game actions. A player first creates a short-lived Action Authorization, then your trusted backend validates the gameplay and submits the settlement to Forest. This is the credit-producing path — only your server holds the Settlement Signing Secret.

Forest web uses the player's active Forest session behind the iframe boundary to authorize player-scoped game requests. Your iframe does not receive auth tokens directly; use the RPC methods below. Authorization amounts are display strings, settlement amounts are base units — see [Amounts](/docs/developers/forest-playkit#amounts-display-vs-base-units).

### `forest.game.action.authorize`

Creates a one-use Action Authorization for a developer-provided `actionId`.

```js
const actionId = crypto.randomUUID();

callForest("forest.game.action.authorize", {
	actionId,
	debitLimitAmount: "1",
});
```

<TypeTable
	type={{
		actionId: {
			type: "string (UUID v4)",
			description: "UUID v4 for this one game action. Use crypto.randomUUID() if possible.",
			required: true,
		},
		debitLimitAmount: {
			type: "string (display amount)",
			description:
				"Maximum player-authorized amount for this action — the cap for both a settlement's Game Balance debit and a burn's amount. For a burn, set this to at least the burn amount (do not use 0 — the burn will fail DEBIT_LIMIT_EXCEEDED). Use 0 only for actions that neither debit balance nor burn.",
			required: true,
		},
	}}
/>

Successful responses return:

```js
{
  id: "authorization-id",
  actionId: "same-action-id",
  debitLimitAmount: "1",
  expiresAt: "2026-06-01T12:05:00.000Z"
}
```

Send the same `actionId`, `projectId`, and the player's gameplay input to your backend. Do not ask the browser to choose the final payout.

Create the Action Authorization close to the actual game action. It is short-lived, and Forest returns `expiresAt` so your UI can reject stale attempts before calling your backend.

## Trusted Settlement

Forest handles settlement accounting and security checks. Your trusted backend handles game outcome validation.

```txt
HTML game
  -> forest.game.action.authorize({ actionId, debitLimitAmount })
  -> your backend validates gameplay and computes debit/credit
  -> your backend signs the settlement
  -> Forest API records confirmed ledger entries
  -> HTML game calls forest.game.balance
```

### Settlement Signing Secret

<Steps>

<Step>

### Obtain it once

Forest creates the first Settlement Signing Secret when an HTML project launch
completes and shows it **once** on the congratulations screen. Copy the backend
env block into the trusted backend that signs settlement requests. The same Forest
API base URL is also shown later in the project editor's HTML Settlement card.

```bash
FOREST_API_BASE_URL=__FOREST_API_BASE_URL__
SETTLEMENT_SECRET=fsc_live_...
```

</Step>

<Step>

### Read its status later

After that, the project editor shows only secret status metadata: active state,
prefix, last 4 characters, and creation time. It cannot reveal the existing
plaintext secret again.

</Step>

<Step>

### Create or rotate

Use **Create Secret** when no active secret exists. Use **Rotate Secret** to
replace the active secret. Rotation invalidates the previous backend secret and
returns the new plaintext value once.

</Step>

</Steps>

<Callout type="info" title="The secret is server-only">
	Never put the Settlement Signing Secret in uploaded HTML, frontend JavaScript, app-template
	code, or any browser-accessible environment variable. Forest stores settlement secrets encrypted
	at rest and uses the active project secret only to verify settlement HMAC signatures — a
	database row holds encrypted secret material plus display metadata, not the plaintext value.
</Callout>

### Settlement request

<APILink method="POST" path="/playables/{projectId}/html/settlements" />

```http
POST /playables/{projectId}/html/settlements
Content-Type: application/json
X-Forest-Settlement-Signature: v1=<hex-hmac>
```

```js
{
	actionId: "same-action-id",
	debitAmount: "1000000000000000000",
	creditAmount: "2000000000000000000",
	timestamp: Math.floor(Date.now() / 1000)
}
```

<TypeTable
	type={{
		actionId: {
			type: "string (UUID v4)",
			description: "Same UUID v4 used for forest.game.action.authorize.",
			required: true,
		},
		debitAmount: {
			type: "string (base-unit integer)",
			description:
				"Non-negative Project Token base-unit integer string. Must not exceed authorized debit base units.",
			required: true,
		},
		creditAmount: {
			type: "string (base-unit integer)",
			description: "Non-negative Project Token base-unit integer string.",
			required: true,
		},
		timestamp: {
			type: "number (Unix seconds)",
			description: "Current Unix timestamp in seconds. Generate it when sending the request.",
			required: true,
		},
	}}
/>

At least one of `debitAmount` or `creditAmount` must be greater than `0`.

Node.js signing example:

```js
import crypto from "node:crypto";

const body = JSON.stringify({
	actionId,
	debitAmount: "1000000000000000000",
	creditAmount: "2000000000000000000",
	timestamp: Math.floor(Date.now() / 1000),
});

// Sign the exact string you send as the HTTP request body.
const signature = crypto
	.createHmac("sha256", process.env.SETTLEMENT_SECRET)
	.update(body)
	.digest("hex");

await fetch(`${FOREST_API}/playables/${projectId}/html/settlements`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-Forest-Settlement-Signature": `v1=${signature}`,
	},
	body,
});
```

Successful settlement responses return:

```js
{
  id: "settlement-id",
  actionId: "same-action-id",
  debitAmount: "1",
  creditAmount: "2",
  replayed: false
}
```

Settlement responses return display decimal amounts. Settlement requests use base-unit integer strings because they are signed server-to-server API bodies.

<Callout type="info" title="Retrying a settlement">
	If a settlement request times out or the response is lost, retry by sending the **same**
	`actionId`, JSON body, and signature again. Do **not** create a new timestamp or change
	settlement amounts for the same `actionId`.
</Callout>

Settlement failures use the shared [settlement error taxonomy](/docs/developers/forest-playkit/errors-security#settlement-errors) (signature, authorization, timestamp, amount, and reuse errors).

<Callout type="warn" title="Only a trusted server can settle credit">
	Browser-only games cannot safely submit credit-producing settlements. The browser can request
	Action Authorizations, but only a trusted server can hold the Settlement Signing Secret and
	choose final debit/credit amounts.
</Callout>

If your HTML game calls your trusted backend directly from the browser, normal browser origin rules still apply. No CORS setup is needed when the game and backend share the same origin. If they are on different origins, your backend must allow the game document's origin. Forest's iframe proxy relays SDK messages; it does not proxy arbitrary `fetch` calls to your backend.


---

# Game Balance

> Player balance, deposits, withdrawals, transactions, and vault funding.

Source: https://forest.inc/docs/developers/forest-playkit/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](/docs/developers/forest-playkit/game-actions). For the relationship between wallet, Game Balance, and Game Vault, see [Core balances](/docs/developers/forest-playkit#core-balances). Amounts are display decimal strings.

<Callout type="info" title="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](/docs/developers/forest-playkit/burns) page.
</Callout>

### `forest.game.balance`

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

```js
callForest("forest.game.balance");
```

Successful responses return:

```js
{
  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.

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

<TypeTable
	type={{
		amount: {
			type: "string (display amount)",
			description: "Positive Project Token decimal string, up to 18 decimals.",
			required: true,
		},
	}}
/>

Successful responses return:

```js
{
  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.

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

<TypeTable
	type={{
		amount: {
			type: "string (display amount)",
			description: "Positive Project Token decimal string, up to 18 decimals.",
			required: true,
		},
	}}
/>

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

<Callout type="warn" title="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.
</Callout>

#### 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.

<Callout type="warn" title="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.
</Callout>

### `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).

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

<TypeTable
	type={{
		page: {
			type: "number",
			description: "Page number. Defaults to 1.",
		},
		perPage: {
			type: "number",
			description: "Number of rows per page. Defaults to 20.",
		},
	}}
/>

Successful responses return:

```js
{
  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:

<TypeTable
	type={{
		id: {
			type: "string",
			description: "Transaction identifier.",
			required: true,
		},
		type: {
			type: "deposit | claim | fund",
			description:
				"Entry kind. A claim row is a withdrawal request and additionally carries requestId.",
			required: true,
		},
		amount: {
			type: "string (display amount)",
			description: "Display token amount string.",
			required: true,
		},
		status: {
			type: "string",
			description: "Entry status as returned by the feed (e.g. confirmed).",
			required: true,
		},
		requestId: {
			type: "string",
			description: "Present on claim rows only — the withdrawal request identifier.",
		},
		txHash: {
			type: "string (0x hash)",
			description: "On-chain transaction hash.",
		},
		createdAt: {
			type: "string (ISO 8601)",
			description: "Timestamp the entry was created.",
			required: true,
		},
	}}
/>

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

<Callout type="warn" title="Player-scoped read — do not proxy through your backend">
	This is a Forest-authenticated, player-scoped read through the iframe proxy: it returns only the
	signed-in player's rows, never all users' withdrawal requests. It is **not** a creator/admin
	listing API. Do **not** proxy it through your game backend.
</Callout>

<Callout type="info" title="Burns are a separate domain">
	Burns are **not** in this feed — use `forest.game.burns` for the player's recorded burns. See
	[Burns](/docs/developers/forest-playkit/burns).
</Callout>

## 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.

<Callout type="warn" title="Funding is not an iframe RPC method">
	Do **not** ask uploaded HTML to transfer funds or record vault funding. Uploaded HTML cannot
	read or fund Game Vault capacity through iframe RPC. 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.
</Callout>

A creator-side flow should:

<Steps>

<Step>

### Transfer Project Tokens

Transfer Project Tokens to the project's Game Vault address.

</Step>

<Step>

### Wait for the transaction hash

Wait for the on-chain transfer to be mined and capture its transaction hash.

</Step>

<Step>

### Record the funding transaction

Record the funding transaction through the authenticated Forest API:

<APILink method="POST" path="/playables/{projectId}/{gameEntity}/fund" />

```http
POST /playables/{projectId}/html/fund
Content-Type: application/json
```

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

</Step>

</Steps>

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.


---

# Player Identity

> Wallet messages and trusted player identity code redemption.

Source: https://forest.inc/docs/developers/forest-playkit/identity

## Project and Wallet Messages

Forest sends project and wallet messages to your iframe. Your app can also request the latest wallet state.

| Message                      | Direction        | Purpose                                                           |
| ---------------------------- | ---------------- | ----------------------------------------------------------------- |
| `FOREST_PROJECT_CONTEXT`     | Forest to iframe | Provides the active Forest project id and auto-swap availability. |
| `FOREST_REQUEST_WALLET`      | iframe to Forest | Ask Forest to send the current wallet state.                      |
| `FOREST_WALLET_CONNECTED`    | Forest to iframe | Display-only connected wallet address. See the warning below.     |
| `FOREST_WALLET_DISCONNECTED` | Forest to iframe | Tells your app that no wallet is connected.                       |

Request the current wallet state:

```js
window.parent.postMessage({ type: "FOREST_REQUEST_WALLET" }, "*");
```

Handle wallet state:

```js
window.addEventListener("message", (event) => {
	if (event.source !== window.parent) return;

	const data = event.data || {};

	if (data.type === "FOREST_WALLET_CONNECTED") {
		wallet = data.walletAddress;
	}

	if (data.type === "FOREST_WALLET_DISCONNECTED") {
		wallet = null;
	}
});
```

Only the project id and public wallet address are exposed. Forest does not send auth tokens, private keys, cookies, or session data to the iframe.

<Callout type="warn" title="FOREST_WALLET_CONNECTED is display-only">
	The address is fine for rendering (greetings, avatars), but it is **not** an authenticated
	credential. Once it reaches your uploaded HTML it is a plain string the player can rewrite in
	their own browser and report to your backend. **Never use this address for backend identity or
	accounting.** To learn the verified player identity, use the Player Identity flow below.
</Callout>

## Player Identity

When your trusted backend needs to know _which_ Forest player is in the session — to key accounting, anti-abuse, or per-player state — do not trust the wallet message. Run a one-time server-to-server handshake instead. The identity code carries no data and grants no spend authority; it is only a lookup key your backend redeems with the same Settlement Signing Secret HMAC it already uses for settlement.

### The identity handshake

<Steps>

<Step>

### Mint a single-use nonce (your backend)

Your backend mints a single-use nonce for this login attempt and stores it. The nonce binds the identity to one login transaction and is verified on redeem.

</Step>

<Step>

### Request a code from the iframe

The iframe calls `forest.identity.code({ nonce })` with that nonce. Forest returns `{ code, expiresAt }`.

</Step>

<Step>

### Relay the code to your backend

The iframe relays the opaque `code` to your backend. The code carries no identity data — do not log it or put it in URLs.

</Step>

<Step>

### Redeem the code (your backend)

Your backend redeems the code against Forest with the HMAC-signed request, getting back `{ userId, walletAddress, username, nonce, issuedAt }` — `username` is the display name at redeem time (or `null`); use it for display only and key accounting on `userId`.

</Step>

<Step>

### Assert the nonce matches

Your backend asserts the returned `nonce` equals the unconsumed nonce you minted for this login, then burns it.

</Step>

<Step>

### Mint your session

Only after the nonce check passes does your backend mint its own session, keyed on the verified `userId`.

</Step>

</Steps>

### `forest.identity.code`

Issues a short-lived (60s), single-use identity code for the authenticated player session.

```js
callForest("forest.identity.code", {
	// Required. A single-use nonce your backend minted for this login attempt and
	// will verify is echoed on redeem. Binds the identity to one login transaction.
	nonce,
});
// The { code, expiresAt } response arrives via your FOREST_RPC_RESPONSE listener.
```

The code is opaque and contains no identity data. Relay it to your backend; do not log it or put it in URLs.

### Redeem (trusted backend only)

<APILink method="POST" path="/playables/{projectId}/html/identity/redeem" />

```http
POST /playables/{projectId}/html/identity/redeem
X-Forest-Settlement-Signature: v1=<hmac-sha256 of the raw body>
```

Request fields:

<TypeTable
	type={{
		code: {
			type: "string (opaque)",
			description: "The opaque code relayed from the iframe.",
			required: true,
		},
		timestamp: {
			type: "number (Unix seconds)",
			description: "Unix seconds. Same freshness window as settlement.",
			required: true,
		},
	}}
/>

Sign and send exactly like a settlement (reuse your settlement signing helper):

```js
const body = JSON.stringify({ code, timestamp: Math.floor(Date.now() / 1000) });
const signature = `v1=${createHmac("sha256", SETTLEMENT_SIGNING_SECRET).update(body).digest("hex")}`;

const res = await fetch(`${FOREST_API}/playables/${projectId}/html/identity/redeem`, {
	method: "POST",
	headers: { "Content-Type": "application/json", "X-Forest-Settlement-Signature": signature },
	body,
});
// { userId, walletAddress, nonce, issuedAt }
```

Rules that matter:

- Derive `{projectId}` from your own server config, never from the frontend-relayed value.
- Assert the returned `nonce` equals the unconsumed nonce you minted for this login, then burn it.
- Key accounting on `userId` (immutable). Treat `walletAddress` as a verified display/payout reference.
- The code is single-use. A second redeem is rejected and the code must not be cached. See [Identity errors](/docs/developers/forest-playkit/errors-security#identity-errors).
- If the redeem response is lost (network blip after Forest consumed the code), do not retry the redeem — it will fail as consumed. Recover by issuing a fresh code (restart at login).


---

# Quickstart

> Add the Forest bridge to your HTML app and make your first call.

Source: https://forest.inc/docs/developers/forest-playkit/quickstart

This gets a Forest HTML template talking to the parent page: request the wallet, handle Forest's messages, and fire your first quote. For the concepts behind it, see the [Overview](/docs/developers/forest-playkit).

## Add the bridge

Drop this into your HTML app. It sends RPC requests with `callForest(...)` and routes Forest's messages back to your code.

```js
let wallet = null;
let projectId = null;
let autoSwapsEnabled = false;
let latestSnapshot = null;

function requestId() {
	if (crypto.randomUUID) return crypto.randomUUID();
	return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
}

function callForest(method, params = {}) {
	const id = requestId();

	window.parent.postMessage(
		{
			type: "FOREST_RPC_REQUEST",
			version: 1,
			id,
			method,
			params,
		},
		"*"
	);

	return id;
}

window.addEventListener("message", (event) => {
	if (event.source !== window.parent) return;

	const data = event.data || {};

	if (data.type === "FOREST_WALLET_CONNECTED") {
		// Display-only. Never send this to your backend as identity — see Player Identity.
		wallet = data.walletAddress;
		callForest("forest.game.balance");
		callForest("forest.swap.quote", { amount: "0.05", direction: "buy" });
		return;
	}

	if (data.type === "FOREST_WALLET_DISCONNECTED") {
		wallet = null;
		latestSnapshot = null;
		return;
	}

	if (data.type === "FOREST_PROJECT_CONTEXT" && typeof data.projectId === "string") {
		projectId = data.projectId;
		autoSwapsEnabled = data.autoSwapsEnabled === true;
		return;
	}

	if (data.type !== "FOREST_RPC_RESPONSE") return;

	if (data.result && data.result.snapshot) {
		latestSnapshot = data.result.snapshot;
	}

	if (data.result && data.result.balance) {
		console.log("Game balance:", data.result.balance);
	}

	if (data.status === "hash") {
		console.log("Transaction submitted:", data.result && data.result.txHash);
	}

	if (data.status === "success") {
		console.log("Forest request complete:", data.result && data.result.txHash);
	}

	if (data.status === "error") {
		console.error(data.error && data.error.code, data.error && data.error.message);
	}
});

window.parent.postMessage({ type: "FOREST_REQUEST_WALLET" }, "*");
```

<Callout type="info" title="The wallet address is display-only">
	`FOREST_WALLET_CONNECTED` carries a `walletAddress` for display only. Never send it to your
	backend as player identity — use the [Player Identity](/docs/developers/forest-playkit/identity)
	flow instead. Error responses (`status: "error"`) carry an `error.code`; see the [error
	reference](/docs/developers/forest-playkit/errors-security#wallet-and-rpc-errors) for the codes.
</Callout>

## Project context

On load, Forest sends the current project context to your iframe:

```js
{
  type: "FOREST_PROJECT_CONTEXT",
  projectId: "project-id",
  gameEntity: "html",
  autoSwapsEnabled: false
}
```

<TypeTable
	type={{
		projectId: {
			type: "string",
			description:
				"Active project id. Your trusted backend uses it in Forest API paths such as /playables/{projectId}/html/settlements.",
			required: true,
		},
		gameEntity: {
			type: "string",
			description: "Entity type for this project. 'html' for HTML templates.",
			required: true,
		},
		autoSwapsEnabled: {
			type: "boolean",
			description:
				"Whether the project owner enabled user-approved auto-swap sessions for this HTML project.",
			required: true,
		},
	}}
/>

<Callout type="info" title="Store projectId, never hardcode it">
	`projectId` is **not** a secret, but do not hardcode it. The same HTML file can be uploaded to
	different projects, and Forest provides the active id at runtime — store the id Forest sends.
</Callout>

<Callout type="info" title="Gate session UI on autoSwapsEnabled">
	`autoSwapsEnabled` tells the iframe whether the owner enabled user-approved auto-swap sessions.
	If it is `false`, do not render session controls.
</Callout>

## The core loop

Most templates follow the same swap loop. Game, session, burn, and identity flows layer on top — each is documented on its own page.

<Steps>

<Step>

### Request wallet state on load

Send `FOREST_REQUEST_WALLET` and store the incoming `FOREST_PROJECT_CONTEXT`.

</Step>

<Step>

### Quote when the wallet connects

Call `forest.swap.quote` once the wallet connects, and re-quote whenever amount, direction, or slippage changes.

</Step>

<Step>

### Submit on confirm

Call `forest.swap.buy` or `forest.swap.sell` when the user confirms.

</Step>

<Step>

### Refresh after a swap

On `success`, request another quote so wallet balances update:

```js
if (response.status === "success") {
	setTimeout(() => {
		callForest("forest.swap.quote", {
			amount: currentAmount,
			direction: currentDirection,
		});
	}, 750);
}
```

</Step>

</Steps>

From here:

<Cards>
	<Card
		title="Swaps"
		href="/docs/developers/forest-playkit/swaps"
		description="Buy, sell, and quote details."
	/>
	<Card
		title="Swap Sessions"
		href="/docs/developers/forest-playkit/swap-sessions"
		description="User-approved auto-swaps."
	/>
	<Card
		title="Game Balance"
		href="/docs/developers/forest-playkit/game-balance"
		description="Deposits, withdrawals, transactions."
	/>
	<Card
		title="Game Actions"
		href="/docs/developers/forest-playkit/game-actions"
		description="Trusted backend settlement."
	/>
</Cards>


---

# RPC Reference

> Forest RPC request, response, and exposed method reference.

Source: https://forest.inc/docs/developers/forest-playkit/rpc-reference

This is the reference home for the HTML SDK transport: the request and response envelopes, the `result.stage` progress values, the full list of exposed RPC methods, and the signed REST endpoints your backend calls. Topic-specific request and response shapes live on each topic page.

## RPC Request Format

All Forest RPC calls use this request envelope:

```js
{
  type: "FOREST_RPC_REQUEST",
  version: 1,
  id: "unique-request-id",
  method: "forest.swap.quote",
  params: {}
}
```

| Field     | Required | Description                                         |
| --------- | -------- | --------------------------------------------------- |
| `type`    | yes      | Always `FOREST_RPC_REQUEST`.                        |
| `version` | yes      | Use `1`.                                            |
| `id`      | yes      | Unique request id. Responses use the same id.       |
| `method`  | yes      | Forest method name.                                 |
| `params`  | yes      | Method-specific params. Use `{}` if there are none. |

## RPC Response Format

Forest replies with:

```js
{
  type: "FOREST_RPC_RESPONSE",
  version: 1,
  id: "same-request-id",
  status: "pending",
  result: {},
  error: undefined
}
```

| Status    | Meaning                                                                    |
| --------- | -------------------------------------------------------------------------- |
| `pending` | Forest accepted the request and is preparing, quoting, or submitting.      |
| `hash`    | A transaction hash is available, but the transaction is not confirmed yet. |
| `success` | The request completed. For swaps, the transaction receipt has confirmed.   |
| `error`   | The request failed. Read `error.code` and `error.message`.                 |

<Callout type="info" title="Error codes are documented centrally">
	On an `error` status, read `error.code` and `error.message`. Every code, what causes it, and how
	to recover is listed in the [Errors and
	Security](/docs/developers/forest-playkit/errors-security) reference.
</Callout>

### Progress stages

Swap and session responses may include a `result.stage` value while Forest is preparing or submitting work. Treat these as progress updates — the request is done only on the final `success` (or `error`) response.

<TypeTable
	type={{
		accepted: {
			type: "stage",
			description: "Forest has accepted the request and is starting work.",
		},
		configured: {
			type: "stage",
			description: "Project config for the request has been resolved.",
		},
		warming: {
			type: "stage",
			description: "Forest is warming up the swap or session pipeline.",
		},
		quoting: {
			type: "stage",
			description: "A swap quote is being fetched.",
		},
		quoted: {
			type: "stage",
			description: "A swap quote is available.",
		},
		submitting: {
			type: "stage",
			description: "Forest is submitting the transaction.",
		},
		preparing: {
			type: "stage",
			description: "Forest is preparing the transaction for the user to sign.",
		},
		approving: {
			type: "stage",
			description: "A token approval is being requested before the main transaction.",
		},
		creating: {
			type: "stage",
			description: "The session create transaction is being prepared or sent.",
		},
		confirming: {
			type: "stage",
			description: "Forest is waiting for the transaction to confirm on-chain.",
		},
		loading_session: {
			type: "stage",
			description: "An existing auto-swap session is being loaded.",
		},
		revoking: {
			type: "stage",
			description: "A session revoke transaction is being prepared or sent.",
		},
		confirming_revoke: {
			type: "stage",
			description: "Forest is waiting for the revoke transaction to confirm on-chain.",
		},
	}}
/>

Session `hash` responses additionally carry one of these `*_submitted` stages so you can tell which transaction the hash belongs to:

| `result.stage`       | Transaction the hash belongs to            |
| -------------------- | ------------------------------------------ |
| `approval_submitted` | Token approval for the session.            |
| `create_submitted`   | The session (`createSession`) transaction. |
| `revoke_submitted`   | The session revoke transaction.            |

## Exposed RPC Methods

| Method                         | Wallet transaction | Purpose                                                                                                         |
| ------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `forest.swap.quote`            | no                 | Read a swap quote and token-page snapshot.                                                                      |
| `forest.swap.buy`              | yes                | Buy Project Token through the connected wallet.                                                                 |
| `forest.swap.sell`             | yes                | Sell Project Token through the connected wallet.                                                                |
| `forest.swap.session.create`   | yes                | Ask the user to enable an auto-swap session.                                                                    |
| `forest.swap.session.current`  | no                 | Read the latest active auto-swap session.                                                                       |
| `forest.swap.session.get`      | no                 | Read a confirmed auto-swap session.                                                                             |
| `forest.swap.session.revoke`   | yes                | Ask the user to revoke an active auto-swap session.                                                             |
| `forest.game.balance`          | no                 | Read the current player's Game Balance.                                                                         |
| `forest.game.deposit`          | yes                | Move wallet-held Project Token into Game Balance.                                                               |
| `forest.game.withdraw`         | yes                | Move Game Balance back to the connected wallet.                                                                 |
| `forest.game.burn`             | yes                | Transfer wallet-held Project Token on-chain to the signed sink (dead address by default); returns the `txHash`. |
| `forest.game.burns`            | no                 | List the current player's recorded burns (paginated).                                                           |
| `forest.game.burns.summary`    | no                 | Read the current player's burn totals, grouped by reason.                                                       |
| `forest.game.transactions`     | no                 | List the current player's Game Balance / Vault activity (deposits, claims, funding).                            |
| `forest.game.action.authorize` | no                 | Authorize one trusted-backend-settled game action.                                                              |
| `forest.identity.code`         | no                 | Issue a single-use code to resolve verified identity.                                                           |
| `forest.runtime.invoke`        | no                 | Invoke a declared backend capability on the Forest-hosted runtime (capability-gated projects only).             |

## REST endpoints

Signed/relayed endpoints under `/playables/{projectId}/html`. Full request and response detail lives on each topic page.

| Method | Path                                    | Caller               | Documented in                                                                                 |
| ------ | --------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
| POST   | `/action-authorizations`                | iframe (session)     | [Game Actions](/docs/developers/forest-playkit/game-actions#forestgameactionauthorize)        |
| POST   | `/settlements`                          | backend (HMAC `v1=`) | [Game Actions](/docs/developers/forest-playkit/game-actions#trusted-settlement)               |
| POST   | `/burns`                                | backend (HMAC `v1=`) | [Burns](/docs/developers/forest-playkit/burns)                                                |
| POST   | `/identity/codes`                       | iframe (session)     | [Player Identity](/docs/developers/forest-playkit/identity)                                   |
| POST   | `/identity/redeem`                      | backend (HMAC `v1=`) | [Player Identity](/docs/developers/forest-playkit/identity#redeem-trusted-backend-only)       |
| POST   | `/swap-sessions/{sessionId}/executions` | backend (HMAC `v1=`) | [Swap Sessions](/docs/developers/forest-playkit/swap-sessions#trusted-swap-session-execution) |


---

# Swap Sessions

> User-approved auto-swap sessions and trusted backend execution.

Source: https://forest.inc/docs/developers/forest-playkit/swap-sessions

Swap sessions are user-approved auto-swap permissions. The iframe asks the user to enable a session; your trusted backend executes against it. They are available only when the project owner has enabled auto-swaps for the HTML project (`autoSwapsEnabled` in [project context](/docs/developers/forest-playkit/quickstart#project-context)).

<Callout type="warn" title="Gate session UI on availability">
	If `autoSwapsEnabled` is `false`, do **not** render session controls — execution will be
	rejected with `SWAP_SESSION_DISABLED`.
</Callout>

## How sessions work

<Steps>

<Step>

### Enable (create)

The iframe requests a session with display-decimal budgets. Forest converts them
into contract base units, prepares the required token approvals for the session
executor contract, and prepares the session transaction. The user confirms the
wallet prompts; Forest then confirms the `createSession` transaction and stores
the active session.

</Step>

<Step>

### Execute (backend)

Session execution is a backend-to-Forest API flow. Forest uses the user's managed
executor wallet to send the on-chain execution transaction. HTML templates do not
configure executor wallet addresses — Forest owns the executor-wallet setup and
confirmation flow.

</Step>

<Step>

### Revoke

Users can revoke active sessions from the Forest UI or via
`forest.swap.session.revoke`.

</Step>

</Steps>

<Callout type="warn" title="Never cache the session id">
	Before **every** backend execution, request `forest.swap.session.current` and use that returned
	`session.id`. Do **not** execute against a session id restored from `localStorage` or another
	stale client cache.
</Callout>

<Callout type="info" title="Approval hashes are progress, not completion">
	The create flow may emit `hash` responses with `stage: "approval_submitted"` before the final
	`stage: "create_submitted"` hash. Treat approval hashes as progress updates; the session is
	active only after the final `success` response.
</Callout>

<Callout type="info" title="Executor wallet needs gas">
	The managed executor wallet must hold native gas on the configured chain for executions to land.
</Callout>

## Session Methods

### `forest.swap.session.create`

```js
callForest("forest.swap.session.create", {
	forestBudget: "50",
	projectBudget: "1000.5",
	expiresAt: Math.floor(Date.now() / 1000) + 86400,
});
```

Unlimited budget:

```js
callForest("forest.swap.session.create", {
	forestBudget: null,
	projectBudget: null,
	expiresAt: Math.floor(Date.now() / 1000) + 86400,
});
```

<TypeTable
	type={{
		forestBudget: {
			type: "string | null",
			description:
				"Max FOREST display amount the session may use for buys, or null for unlimited.",
			required: true,
		},
		projectBudget: {
			type: "string | null",
			description:
				"Max Project Token display amount the session may use for sells, or null for unlimited.",
			required: true,
		},
		expiresAt: {
			type: "number (Unix seconds)",
			description: "When the session expires.",
			required: true,
		},
	}}
/>

Budgets are display decimal strings. Use `null` for a side that should be unlimited until `expiresAt` is reached or the user revokes the session. Successful responses return the confirmed session plus the transaction hash:

```js
{
  session: {
    id: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
    onChainSessionId: "42",
    chainId: 97,
    status: "active",
    snapshot: {
      routerAddress: "0x...",
      forestBudget: "50000000000000000000",
      projectBudget: "1000500000000000000000",
      expiresAt: "2026-05-15T12:00:00.000Z",
      createTxHash: "0x...",
      createdAt: "2026-05-14T12:00:00.000Z"
    },
    createdAt: "2026-05-14T12:00:00.000Z",
    updatedAt: "2026-05-14T12:00:00.000Z"
  },
  limits: {
    forestBudget: "50000000000000000000",
    projectBudget: "1000500000000000000000",
    expiresAt: "2026-05-15T12:00:00.000Z"
  },
  txHash: "0x..."
}
```

### `forest.swap.session.current`

```js
callForest("forest.swap.session.current");
```

Returns the latest active session for the current project and authenticated wallet user, using the same response shape as `forest.swap.session.get`. Use this method immediately before passing a session id to your backend for execution.

### `forest.swap.session.get`

```js
callForest("forest.swap.session.get", {
	sessionId: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
});
```

Returns the stored session so your app can inspect status, limits, and expiry. Forest resolves router and pair addresses internally; HTML apps never provide or persist those addresses.

<Callout type="warn" title="Sessions do not re-route">
	Sessions do not fall back to a new route after router or pair changes. If the on-chain session
	route is no longer usable, the user must recreate the session.
</Callout>

```js
{
  limits: {
    forestBudget: "50000000000000000000",
    projectBudget: null,
    expiresAt: "2026-05-15T12:00:00.000Z"
  },
  session: {
    id: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
    onChainSessionId: "42",
    chainId: 97,
    status: "active",
    snapshot: {
      routerAddress: "0x...",
      forestBudget: "50000000000000000000",
      projectBudget: null,
      expiresAt: "2026-05-15T12:00:00.000Z",
      createTxHash: "0x...",
      createdAt: "2026-05-14T12:00:00.000Z"
    },
    createdAt: "2026-05-14T12:00:00.000Z",
    updatedAt: "2026-05-14T12:00:00.000Z"
  }
}
```

HTML SDK session responses use base-unit integer strings for budgets. `limits` mirrors `session.snapshot` budget fields and exists only as a convenient place to read the configured session caps and expiry.

### `forest.swap.session.revoke`

```js
callForest("forest.swap.session.revoke", {
	sessionId: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
});
```

Revokes an active session through the connected wallet, then confirms the revoke transaction with Forest. This opens a wallet prompt and returns the same response shape as `forest.swap.session.get`, plus `txHash` when the revoke transaction is confirmed.

## Trusted Swap Session Execution

Uploaded HTML can request that a user enables a session, but execution must come from your trusted backend. Use the same server-only Settlement Signing Secret and HMAC header as settlement:

<APILink method="POST" path="/playables/{projectId}/html/swap-sessions/{sessionId}/executions" />

```http
POST /playables/{projectId}/html/swap-sessions/{sessionId}/executions
Content-Type: application/json
X-Forest-Settlement-Signature: v1=<hex-hmac>
```

```js
{
	sessionId: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
	requestId: "6ae1ea37-19a2-46db-a59f-742e58fb8c4d",
	direction: "buy",
	projectAmount: "1000000000000000000",
	forestAmountLimit: "1000000000000000000",
	timestamp: Math.floor(Date.now() / 1000)
}
```

<TypeTable
	type={{
		sessionId: {
			type: "string (UUID v4)",
			description: "Session ID being executed. Must match the route session ID.",
			required: true,
		},
		requestId: {
			type: "string (UUID v4)",
			description:
				"UUID v4 generated by your backend for idempotency. Retry the same body for the same request.",
			required: true,
		},
		direction: {
			type: '"buy" | "sell"',
			description: "Swap direction.",
			required: true,
		},
		projectAmount: {
			type: "string (base-unit integer)",
			description:
				"Project Token amount as a base-unit integer string. Buy treats it as exact output; sell as exact input.",
			required: true,
		},
		forestAmountLimit: {
			type: "string (base-unit integer)",
			description:
				"FOREST amount as a base-unit integer string. Buy treats it as max input; sell as min output.",
			required: true,
		},
		timestamp: {
			type: "number (Unix seconds)",
			description: "Current Unix timestamp in seconds.",
			required: true,
		},
		deadline: {
			type: "number (Unix seconds)",
			description: "Optional router deadline. Forest defaults it when omitted.",
		},
	}}
/>

Sign the exact JSON string you send. Store the signed body by `sessionId + requestId` and replay that same body if the response is lost. Reusing a request id with a different direction, amount, or deadline is rejected.

A successful response contains the confirmed execution transaction:

```js
{
  id: "execution-id",
  sessionId: "9db7f2d8-5e03-4c73-96f9-31b99747d0c6",
  requestId: "same-request-id",
  direction: "buy",
  txHash: "0x...",
  projectAmount: "1000000000000000000",
  forestAmount: "100000000000000000",
  forestBudgetRemaining: "49000000000000000000",
  projectBudgetRemaining: "100000000000000000000",
  replayed: false
}
```

Forest records confirmed executions only after the contract emits the matching `SwapSessionExecuted` event. If your backend loses the response, retry the same `requestId` and exact signed body. Signature and timestamp failures use the shared [settlement error taxonomy](/docs/developers/forest-playkit/errors-security#settlement-errors); session state, route mismatches, and chain-validation failures can return normal HTTP errors without an app-specific `code`.

Embedded HTML apps can revoke sessions with `forest.swap.session.revoke`; users can also revoke active sessions from Forest UI.


---

# Swaps

> Swap quote, buy, and sell methods, plus the snapshot shape.

Source: https://forest.inc/docs/developers/forest-playkit/swaps

Swaps run through the connected wallet. Quote is a read; buy and sell open the wallet. Amounts are display decimal strings — see [Amounts](/docs/developers/forest-playkit#amounts-display-vs-base-units). For user-approved auto-swaps, see [Swap Sessions](/docs/developers/forest-playkit/swap-sessions).

## Swap Methods

### `forest.swap.quote`

Gets a read-only quote and snapshot. This does not open the wallet or submit a transaction.

```js
callForest("forest.swap.quote", {
	amount: "0.05",
	direction: "buy",
	slippage: 0.5,
});
```

<TypeTable
	type={{
		amount: {
			type: "string (display decimal)",
			description: "Positive display decimal string.",
			required: true,
		},
		direction: {
			type: '"buy" | "sell"',
			description: "Swap direction.",
			required: true,
		},
		slippage: {
			type: "number (percent)",
			description: "Percent slippage. Forest uses its default when omitted.",
		},
	}}
/>

### `forest.swap.buy`

Submits a buy transaction through the connected wallet. `amount` is the amount of the pay token to spend.

```js
callForest("forest.swap.buy", {
	amount: "0.05",
	slippage: 0.5,
});
```

<TypeTable
	type={{
		amount: {
			type: "string (display decimal)",
			description: "Positive display decimal string of pay token to spend.",
			required: true,
		},
		slippage: {
			type: "number (percent)",
			description: "Percent slippage. Forest uses its default when omitted.",
		},
	}}
/>

### `forest.swap.sell`

Submits a sell transaction through the connected wallet. `amount` is the amount of the launched token to sell.

```js
callForest("forest.swap.sell", {
	amount: "100",
	slippage: 0.5,
});
```

<TypeTable
	type={{
		amount: {
			type: "string (display decimal)",
			description: "Positive display decimal string of launched token to sell.",
			required: true,
		},
		slippage: {
			type: "number (percent)",
			description: "Percent slippage. Forest uses its default when omitted.",
		},
	}}
/>

## Snapshot Reference

Quote and swap responses can include `result.snapshot`. Store the latest snapshot and render your UI from it. The base snapshot always includes direction, slippage, pay token, and receive token. Quote and route fields are present only after Forest has enough data for them.

```js
{
  direction: "buy",
  slippage: 0.5,
  payToken: {
    symbol: "BNB",
    balance: 1.25,
    locked: 0
  },
  receiveToken: {
    symbol: "TOKEN"
  },
  quote: {
    payAmount: 0.05,
    receiveAmount: 1234.56,
    receivePerPay: 24691.2,
    payPerReceive: 0.0000405
  },
  priceImpact: 1.2,
  liquidityDepth: 8.7,
  swapBreakdown: {
    steps: [],
    totalEffectiveFee: 0.01,
    expectedOutput: 1234.56
  }
}
```

Snapshot values are display numbers, not base-unit integers.

### Top-level fields

<TypeTable
	type={{
		direction: {
			type: '"buy" | "sell"',
			description: "Direction the quote was computed for.",
			required: true,
		},
		slippage: {
			type: "number (percent)",
			description: "Percent slippage applied to the quote.",
			required: true,
		},
		payToken: {
			type: "object",
			description: "Token being spent. Has symbol, balance, and locked sub-fields.",
			required: true,
		},
		receiveToken: {
			type: "object",
			description: "Token being received. Has a symbol sub-field.",
			required: true,
		},
		quote: {
			type: "object",
			description:
				"Quoted amounts and rates. Present after a successful quote. Has payAmount, receiveAmount, receivePerPay, and payPerReceive sub-fields.",
		},
		priceImpact: {
			type: "number",
			description: "Price impact of the quote, when available.",
		},
		liquidityDepth: {
			type: "number",
			description: "Liquidity depth available for the quote, when available.",
		},
		swapBreakdown: {
			type: "object",
			description:
				"Route detail, when available. Has steps, totalEffectiveFee, and expectedOutput sub-fields.",
		},
	}}
/>

### `payToken` / `receiveToken`

<TypeTable
	type={{
		symbol: {
			type: "string",
			description: "Token symbol.",
			required: true,
		},
		balance: {
			type: "number (display)",
			description: "Wallet balance of the token in display units. Present on payToken.",
		},
		locked: {
			type: "number (display)",
			description:
				"Portion of the balance that is locked, in display units. Subtract from balance for spendable amount. Present on payToken.",
		},
	}}
/>

### `quote`

When `quote` is present, it has:

<TypeTable
	type={{
		payAmount: {
			type: "number (display)",
			description: "Amount of the pay token spent, in display units.",
			required: true,
		},
		receiveAmount: {
			type: "number (display)",
			description: "Amount of the receive token returned, in display units.",
			required: true,
		},
		receivePerPay: {
			type: "number",
			description: "Receive token amount per unit of pay token.",
			required: true,
		},
		payPerReceive: {
			type: "number",
			description: "Pay token amount per unit of receive token.",
			required: true,
		},
	}}
/>

### `swapBreakdown`

When `swapBreakdown` is present, it has:

<TypeTable
	type={{
		steps: {
			type: "array",
			description: "Route steps for the swap.",
			required: true,
		},
		totalEffectiveFee: {
			type: "number",
			description: "Total effective fee for the route.",
			required: true,
		},
		expectedOutput: {
			type: "number (display)",
			description: "Expected output amount, in display units.",
			required: true,
		},
	}}
/>

Calculate spendable balance from the snapshot:

```js
const available = snapshot.payToken.balance - (snapshot.payToken.locked || 0);
```

## Error handling

Quote, buy, and sell failures use the shared swap error taxonomy. See [Errors and Security](/docs/developers/forest-playkit/errors-security#swap-and-session-errors) for each code's cause and resolution.


---

# API Reference

> Forest REST API endpoints generated from the OpenAPI schema.

Source: https://forest.inc/docs/reference

The Forest API is a JSON REST API behind the Forest app: tokens and trading pairs, projects and campaigns, game settlement, the vibe builder, vault auctions, competitions, and account data. This reference is generated from the OpenAPI schema, so every page reflects the current public API surface.

## Authentication

Endpoints marked with a lock require a Bearer JWT obtained by signing in with an Ethereum wallet (SIWE):

1. Request a challenge: <APILink method="POST" path="/auth/ethereum/challenge" />
2. Sign the challenge with your wallet and exchange it for a session: <APILink method="POST" path="/auth/ethereum" />
3. Send the token on subsequent requests:

```http
Authorization: Bearer <jwt>
```

Sessions are refreshed via <APILink method="POST" path="/auth/refresh" /> and ended with <APILink method="POST" path="/auth/logout" />.

Endpoints without a lock are public reads and need no credentials.

### Trusted backend endpoints

Game settlement endpoints (burns, settlements, swap session executions, identity redeem) are not called with a user JWT. They are server-to-server and authenticated with an HMAC signature over the raw request body:

```http
X-Forest-Settlement-Signature: v1=<hmac-sha256 of the raw body>
```

The signing secret is issued per project and must never reach a browser or game iframe. See [Game Actions](/docs/developers/forest-playkit/game-actions) for the signing walkthrough.

## Errors

Errors are JSON with the HTTP status code mirrored in the body:

```json
{
	"statusCode": 401,
	"message": "Unauthorized"
}
```

Validation failures (400) return `message` as an array of field-level problems. Codes follow standard HTTP semantics: `401` missing/invalid token, `403` authenticated but not allowed, `404` unknown resource, `409` conflicting write.

## Pagination

List endpoints paginate with query parameters — most commonly `page` + `perPage` or `limit` + `offset`, with `orderBy`/`direction` for sorting. The exact parameters and defaults are listed on each endpoint page.

## Trying endpoints

Every endpoint page has an interactive playground: fill parameters, attach your Bearer token, and send real requests from the browser. Each page also offers **Copy Markdown** — and the whole API surface is available to AI tools via [llms.txt](/llms.txt).

Select a resource from the sidebar to get started.


---

# Create a new agent session

> Starts a new conversation with an AI agent.

Source: https://forest.inc/docs/reference/agents/createSessionAgent

## Endpoint

`POST /agents/{agentId}/sessions`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get agent details

> Returns the details of an AI agent.

Source: https://forest.inc/docs/reference/agents/getAgent

## Endpoint

`GET /agents/{agentId}`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get session details

> Returns a specific session with its message history.

Source: https://forest.inc/docs/reference/agents/getSessionAgent

## Endpoint

`GET /agents/{agentId}/sessions/{sessionId}`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)
- `sessionId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List session messages

> Returns a specific sessions message history.

Source: https://forest.inc/docs/reference/agents/listMessagesAgents

## Endpoint

`GET /agents/{agentId}/sessions/{sessionId}/messages`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)
- `sessionId` (path, required)
- `limit` (query) — Number of items per page
- `direction` (query) — The direction of the sort. Can be either "asc" or "desc".

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List agent sessions

> Returns all AI agent sessions for the current user.

Source: https://forest.inc/docs/reference/agents/listSessionsAgents

## Endpoint

`GET /agents/{agentId}/sessions`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Retry a message previously sent to the agent

> Retries a message previously sent to the AI agent and gets a response.

Source: https://forest.inc/docs/reference/agents/retryMessageAgent

## Endpoint

`PUT /agents/{agentId}/sessions/{sessionId}/messages/{messageId}`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)
- `sessionId` (path, required)
- `messageId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Send a message to the agent

> Sends a message to the AI agent and gets a response.

Source: https://forest.inc/docs/reference/agents/sendMessageAgent

## Endpoint

`POST /agents/{agentId}/sessions/{sessionId}/messages`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)
- `sessionId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Sse Agent

Source: https://forest.inc/docs/reference/agents/sseAgent

## Endpoint

`GET /agents/{agentId}/sessions/{sessionId}/events`

## Authentication

- `bearer`

## Parameters

- `agentId` (path, required)
- `sessionId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get an app template

> Returns a specific app template by its id.

Source: https://forest.inc/docs/reference/app-templates/getAppTemplate

## Endpoint

`GET /app-templates/{appTemplateId}`

## Parameters

- `appTemplateId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List app templates

> List all available app templates

Source: https://forest.inc/docs/reference/app-templates/listAppTemplates

## Endpoint

`GET /app-templates`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Generate a nonce

> Generate a single-use nonce to sign.

Source: https://forest.inc/docs/reference/auth/challenge

## Endpoint

`POST /auth/ethereum/challenge`

## Responses

- `201` — The nonce to sign
- `401` — Unauthorized
- `500` — Internal server error


---

# Logout user

> Destroys the current session and clears the cookie

Source: https://forest.inc/docs/reference/auth/logout

## Endpoint

`POST /auth/logout`

## Responses

- `201`
- `204` — Session destroyed
- `401` — Unauthorized
- `500` — Internal server error


---

# Refresh user's access token

> Creates a new access token for the user, if the session is active

Source: https://forest.inc/docs/reference/auth/refresh

## Endpoint

`POST /auth/refresh`

## Responses

- `200` — The access token to use for the authentication
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Verify a user's signature

> Verify a user's signature and consume the nonce embedded in the signed message.

Source: https://forest.inc/docs/reference/auth/siweLogin

## Endpoint

`POST /auth/ethereum`

## Request body

Required.

- `application/json`

## Responses

- `201` — The access token to use for the authentication
- `401` — Unauthorized
- `500` — Internal server error


---

# Claim a confirmed credit purchase

> Verifies the purchase transaction on-chain and grants the credits immediately (the event sync remains the backstop). Returns the updated balance.

Source: https://forest.inc/docs/reference/builder/claimPurchaseBuilder

## Endpoint

`POST /builder/credits/purchases`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Create a new builder session

> Starts a new token-builder draft session.

Source: https://forest.inc/docs/reference/builder/createSessionBuilder

## Endpoint

`POST /builder/sessions`

## Authentication

- `bearer`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get builder credit balance

> Returns the credit balance (micro-USD) and whether it clears the prompt gate.

Source: https://forest.inc/docs/reference/builder/getCreditBalanceBuilder

## Endpoint

`GET /builder/credits`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get builder session

> Returns a token-builder draft session.

Source: https://forest.inc/docs/reference/builder/getSessionBuilder

## Endpoint

`GET /builder/sessions/{sessionId}`

## Authentication

- `bearer`

## Parameters

- `sessionId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List builder sessions

> Returns all token-builder draft sessions.

Source: https://forest.inc/docs/reference/builder/listSessionsBuilders

## Endpoint

`GET /builder/sessions`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Retry a builder prompt

> Checks the credit gate and retries a failed token-builder prompt.

Source: https://forest.inc/docs/reference/builder/retryMessageBuilder

## Endpoint

`POST /builder/sessions/{sessionId}/messages/{messageId}/retry`

## Authentication

- `bearer`

## Parameters

- `sessionId` (path, required)
- `messageId` (path, required)

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Send a builder prompt

> Checks the credit gate and starts token-builder generation; steps are billed from credits as they finish.

Source: https://forest.inc/docs/reference/builder/sendMessageBuilder

## Endpoint

`POST /builder/sessions/{sessionId}/messages`

## Authentication

- `bearer`

## Parameters

- `sessionId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Sse Builder

Source: https://forest.inc/docs/reference/builder/sseBuilder

## Endpoint

`GET /builder/sessions/{sessionId}/events`

## Authentication

- `bearer`

## Parameters

- `sessionId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Trash a builder session

> Hides a token-builder draft session from the draft list.

Source: https://forest.inc/docs/reference/builder/trashSessionBuilder

## Endpoint

`DELETE /builder/sessions/{sessionId}`

## Authentication

- `bearer`

## Parameters

- `sessionId` (path, required)

## Responses

- `200`
- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get buyback history for a token

Source: https://forest.inc/docs/reference/buyback/getBuybackHistoryBuyback

## Endpoint

`GET /buyback/{tokenId}/history`

## Parameters

- `tokenId` (path, required) — Token UUID
- `limit` (query) — Number of records to return (default: 50)
- `offset` (query) — Number of records to skip (default: 0)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get next buyback execution time

Source: https://forest.inc/docs/reference/buyback/getNextExecutionBuyback

## Endpoint

`GET /buyback/next-execution`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get competition data by id

> Returns top wallets ranked by FOREST equivalent trading volume for the specified competition.

Source: https://forest.inc/docs/reference/competitions/getCompetitionCompetition

## Endpoint

`GET /competitions/{id}`

## Parameters

- `id` (path, required)
- `limit` (query) — Number of results to return (default: 100)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get competitions

> Returns a list of competitions. Use status filter to get active, ended, or all competitions.

Source: https://forest.inc/docs/reference/competitions/getCompetitionsCompetition

## Endpoint

`GET /competitions`

## Parameters

- `status` (query) — Filter by competition status. Default is "all".

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get competition reward stats

> Returns aggregate reward statistics across all competitions.

Source: https://forest.inc/docs/reference/competitions/getStatsCompetition

## Endpoint

`GET /competitions/stats`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get user leaderboard stats

> Returns ranking and volume stats for a specific wallet in the specified competition. Requires authentication.

Source: https://forest.inc/docs/reference/competitions/getUserStatsCompetition

## Endpoint

`GET /competitions/{id}/user/{wallet}`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)
- `wallet` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Claim being referred by another user

Source: https://forest.inc/docs/reference/me/claimReferralBonus

## Endpoint

`POST /me/referrals/claim-bonus`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `201`
- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Mark welcome flow as dismissed

Source: https://forest.inc/docs/reference/me/dismissOnboarding

## Endpoint

`POST /me/onboarding/dismiss`

## Authentication

- `bearer`

## Responses

- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get current user

> Returns the currently authenticated user

Source: https://forest.inc/docs/reference/me/getMe

## Endpoint

`GET /me`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get recent portfolio activity

> Returns the last 10 trades for all linked wallets independently of RPC balances

Source: https://forest.inc/docs/reference/me/getPortfolioActivity

## Endpoint

`GET /me/portfolio/activity`

## Authentication

- `bearer`

## Parameters

- `currency` (query) — Currency for portfolio values (default: usd)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get portfolio overview

> Returns holdings, staked balances, and PnL for all linked wallets

Source: https://forest.inc/docs/reference/me/getPortfolioOverview

## Endpoint

`GET /me/portfolio`

## Authentication

- `bearer`

## Parameters

- `currency` (query) — Currency for portfolio values (default: usd)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get or generate the current user referral code

Source: https://forest.inc/docs/reference/me/getReferralCode

## Endpoint

`GET /me/referrals/code`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get referral stats (seeds earned + referees count)

Source: https://forest.inc/docs/reference/me/getReferralSummary

## Endpoint

`GET /me/referrals/summary`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List current user tokens

> Alias for GET /tokens?owner=me. Lists all tokens belonging to the current user

Source: https://forest.inc/docs/reference/me/getTokens

## Endpoint

`GET /me/tokens`

## Authentication

- `bearer`

## Parameters

- `owner` (query)
- `orderBy` (query) — The field to sort by
- `search` (query)
- `currency` (query) — Currency to convert the prices to
- `graduated` (query)
- `populate` (query) — List of relations to populate, as a comma separated string. Allowed values: 'projects'
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get current user username settings

Source: https://forest.inc/docs/reference/me/getUsernameSettings

## Endpoint

`GET /me/settings/username`

## Authentication

- `bearer`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Set the current user username

Source: https://forest.inc/docs/reference/me/setUsername

## Endpoint

`PATCH /me/settings/username`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get news by slug

> Returns a specific news article by slug.

Source: https://forest.inc/docs/reference/news/getNews

## Endpoint

`GET /news/{slug}`

## Parameters

- `slug` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List News

> Lists all published news articles.

Source: https://forest.inc/docs/reference/news/listNews

## Endpoint

`GET /news`

## Parameters

- `orderBy` (query) — The field to sort by
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List ongoing events

> Returns currently live vault auctions and active trading competitions, sorted by end date ascending.

Source: https://forest.inc/docs/reference/ongoing-events/findOngoingOngoingEvents

## Endpoint

`GET /ongoing-events`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get OHLCV candles for a pair

> Returns aggregated OHLCV candles for a pair, ascending by time.

Source: https://forest.inc/docs/reference/pairs/getCandlesPair

## Endpoint

`GET /pairs/{pairAddress}/candles`

## Parameters

- `pairAddress` (path, required)
- `interval` (query)
- `limit` (query)
- `to` (query) — Exclusive ISO timestamp upper cursor. Returns candles whose bucket start is < to.
- `currency` (query)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get History Pair

Source: https://forest.inc/docs/reference/pairs/getHistoryPair

## Endpoint

`GET /pairs/{pairAddress}/history`

## Parameters

- `pairAddress` (path, required)
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `currency` (query)
- `orderBy` (query) — The field to sort by
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get a pair

> Returns a specific pair

Source: https://forest.inc/docs/reference/pairs/getPair

## Endpoint

`GET /pairs/{pairAddress}`

## Parameters

- `pairAddress` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get recent swaps for a pair

> Returns recent swap rows for the transaction table.

Source: https://forest.inc/docs/reference/pairs/getSwapsPair

## Endpoint

`GET /pairs/{pairAddress}/swaps`

## Parameters

- `pairAddress` (path, required)
- `limit` (query)
- `offset` (query)
- `currency` (query)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List pairs

> Lists all pairs.

Source: https://forest.inc/docs/reference/pairs/listPairs

## Endpoint

`GET /pairs`

## Parameters

- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `orderBy` (query) — The field to sort by
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Search pairs

> Searches for pairs by token name or symbol.

Source: https://forest.inc/docs/reference/pairs/searchPair

## Endpoint

`GET /pairs/search`

## Parameters

- `query` (query, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get bet history

> Returns paginated bet history for the current user

Source: https://forest.inc/docs/reference/playables-/-coin-flip/getHistoryCoinFlip

## Endpoint

`GET /playables/{projectId}/coinflip/history`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get settings

> Returns the settings for the specific project

Source: https://forest.inc/docs/reference/playables-/-coin-flip/getSettingsCoinFlip

## Endpoint

`GET /playables/{projectId}/coinflip/settings`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Make a bet

> Places a bet using the game engine RNG

Source: https://forest.inc/docs/reference/playables-/-coin-flip/makeBetCoinFlip

## Endpoint

`POST /playables/{projectId}/coinflip/bets`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Confirm claim result

> Reports on-chain withdrawal result to update claim status

Source: https://forest.inc/docs/reference/playables-/-game/confirmClaimGameEngine

## Endpoint

`POST /playables/{projectId}/{gameEntity}/claim/{claimId}/confirm`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug
- `claimId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200` — Claim status updated
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get game balance

> Returns the computed game balance for the current user

Source: https://forest.inc/docs/reference/playables-/-game/getBalanceGameEngine

## Endpoint

`GET /playables/{projectId}/{gameEntity}/balance`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get player burns

> Returns the current player's paginated on-chain burns for this project

Source: https://forest.inc/docs/reference/playables-/-game/getPlayerBurnsGameEngine

## Endpoint

`GET /playables/{projectId}/{gameEntity}/burns`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get player burn summary

> Returns the current player's burn totals for this project, grouped by reason

Source: https://forest.inc/docs/reference/playables-/-game/getPlayerBurnSummaryGameEngine

## Endpoint

`GET /playables/{projectId}/{gameEntity}/burns/summary`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get player game transactions

> Returns paginated deposit, claim, and fund transactions for the current user

Source: https://forest.inc/docs/reference/playables-/-game/getTransactionsGameEngine

## Endpoint

`GET /playables/{projectId}/{gameEntity}/transactions`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get vault funding transactions

> Returns paginated Game Vault funding records for the project owner

Source: https://forest.inc/docs/reference/playables-/-game/getVaultFundingTransactionsGameEngine

## Endpoint

`GET /playables/{projectId}/{gameEntity}/vault-funding`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Record a deposit

> Verifies on-chain transaction and records the deposit

Source: https://forest.inc/docs/reference/playables-/-game/recordDepositGameEngine

## Endpoint

`POST /playables/{projectId}/{gameEntity}/deposit`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Record a vault fund

> Verifies on-chain transaction and records a Game Vault funding transfer. Does not affect user game balance.

Source: https://forest.inc/docs/reference/playables-/-game/recordFundGameEngine

## Endpoint

`POST /playables/{projectId}/{gameEntity}/fund`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Release claim reservation

> Releases a pending claim when no successful withdrawal transaction exists

Source: https://forest.inc/docs/reference/playables-/-game/releaseClaimGameEngine

## Endpoint

`POST /playables/{projectId}/{gameEntity}/claim/{claimId}/release`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug
- `claimId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200` — Claim reservation released
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Request a claim

> Requests withdrawal of game balance with EIP-712 signature

Source: https://forest.inc/docs/reference/playables-/-game/requestClaimGameEngine

## Endpoint

`POST /playables/{projectId}/{gameEntity}/claim`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `gameEntity` (path, required) — Game entity slug

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Authorize an HTML game action

> Creates a short-lived player authorization for an externally settled HTML game action.

Source: https://forest.inc/docs/reference/playables-/-html/authorizeActionHtmlUser

## Endpoint

`POST /playables/{projectId}/html/action-authorizations`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Create or rotate HTML settlement secret

> Creates the first signing secret or replaces the current one, returning the new plaintext secret once.

Source: https://forest.inc/docs/reference/playables-/-html/createOrRotateSigningSecretHtml

## Endpoint

`POST /playables/{projectId}/html/settlement-signing-secret`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Execute an HTML swap session

> Accepts a signed external HTML swap-session execution and submits the confirmed transaction from the Forest-managed executor wallet.

Source: https://forest.inc/docs/reference/playables-/-html/executeSwapSessionHtml

## Endpoint

`POST /playables/{projectId}/html/swap-sessions/{sessionId}/executions`

## Parameters

- `projectId` (path, required)
- `sessionId` (path, required)
- `x-forest-settlement-signature` (header, required) — HMAC signature over the raw request body.

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get public playable state

> Returns the public JSON state for a live HTML project. Private state is never returned by this endpoint.

Source: https://forest.inc/docs/reference/playables-/-html/getPlayableStateHtml

## Endpoint

`GET /playables/{projectId}/html/state`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get settings

> Returns the settings for the specific project

Source: https://forest.inc/docs/reference/playables-/-html/getSettingsHtml

## Endpoint

`GET /playables/{projectId}/html/settings`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get HTML settlement secret status

> Returns status metadata for the active HTML settlement signing secret.

Source: https://forest.inc/docs/reference/playables-/-html/getSigningSecretStatusHtml

## Endpoint

`GET /playables/{projectId}/html/settlement-signing-secret`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Invoke generated HTML runtime method

> Verifies the player session, loads the live project or owned HTML draft runtime version, and invokes the generated runtime in the sandbox runner.

Source: https://forest.inc/docs/reference/playables-/-html/invokeRuntimeHtmlUser

## Endpoint

`POST /playables/{projectId}/html/rpc`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Issue a single-use identity code

> Issues a short-lived, single-use code for the authenticated player session. The code carries no identity data; the developer server redeems it server-to-server to learn the verified player identity. Use this instead of trusting the iframe wallet event.

Source: https://forest.inc/docs/reference/playables-/-html/issueIdentityCodeHtmlUser

## Endpoint

`POST /playables/{projectId}/html/identity/codes`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Redeem an identity code

> Resolves the verified Forest identity behind a single-use identity code. Authenticated by the per-project settlement signing secret HMAC. Single-use: a redeemed code cannot be redeemed again.

Source: https://forest.inc/docs/reference/playables-/-html/redeemIdentityHtml

## Endpoint

`POST /playables/{projectId}/html/identity/redeem`

## Parameters

- `projectId` (path, required)
- `x-forest-settlement-signature` (header, required) — HMAC signature over the raw request body.

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Submit a signed HTML game burn

> Server-verifiable on-chain burn, symmetric with /settlements: HMAC-signed body, single-use actionId (idempotent), bound to an action-authorization debit limit, with an optional signed `reason` slug (the grouping key) and free-form `metadata`. Verifies the supplied `txHash` is an ERC-20 transfer of exactly `amount` Project Tokens from a linked wallet to the signed `burnAddress` sink, and records it. A transfer to the dead address (0x...dead) is a real supply burn; any other sink is the app-chosen destination. `txHash` is required - burns are on-chain only.

Source: https://forest.inc/docs/reference/playables-/-html/settleBurnHtml

## Endpoint

`POST /playables/{projectId}/html/burns`

## Parameters

- `projectId` (path, required)
- `x-forest-settlement-signature` (header, required) — HMAC signature over the raw request body.

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Submit an HTML game settlement

> Accepts a signed external HTML game settlement and writes confirmed ledger entries.

Source: https://forest.inc/docs/reference/playables-/-html/settleHtml

## Endpoint

`POST /playables/{projectId}/html/settlements`

## Parameters

- `projectId` (path, required)
- `x-forest-settlement-signature` (header, required) — HMAC signature over the raw request body.

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get bet history

> Returns paginated bet history for the current user

Source: https://forest.inc/docs/reference/playables-/-lucky-reel/getHistoryLuckyReel

## Endpoint

`GET /playables/{projectId}/luckyreel/history`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get settings

> Returns the settings for the specific project

Source: https://forest.inc/docs/reference/playables-/-lucky-reel/getSettingsLuckyReel

## Endpoint

`GET /playables/{projectId}/luckyreel/settings`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Make a bet

> Places a lucky reel bet using the game engine RNG

Source: https://forest.inc/docs/reference/playables-/-lucky-reel/makeBetLuckyReel

## Endpoint

`POST /playables/{projectId}/luckyreel/bets`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Authorize an action for the sandbox player

Source: https://forest.inc/docs/reference/playables/authorizeActionHtmlSandboxPreview

## Endpoint

`POST /playables/{projectId}/html/preview/action-authorizations`

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Authorize for the project

> Creates a new access token for the user, if the session is active

Source: https://forest.inc/docs/reference/playables/authorizePlayable

## Endpoint

`POST /playables/{projectId}/auth`

## Parameters

- `projectId` (path, required)

## Responses

- `200` — The access token to use for the authentication
- `401` — Unauthorized
- `500` — Internal server error


---

# Read the sandbox play-money balance

> Returns the harness player balance so a draft can render real ledger effects during integration testing.

Source: https://forest.inc/docs/reference/playables/getBalanceHtmlSandboxPreview

## Endpoint

`GET /playables/{projectId}/html/preview/balance`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get Burns Html Sandbox Preview

Source: https://forest.inc/docs/reference/playables/getBurnsHtmlSandboxPreview

## Endpoint

`GET /playables/{projectId}/html/preview/burns`

## Parameters

- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get Burn Summary Html Sandbox Preview

Source: https://forest.inc/docs/reference/playables/getBurnSummaryHtmlSandboxPreview

## Endpoint

`GET /playables/{projectId}/html/preview/burns/summary`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get Transactions Html Sandbox Preview

Source: https://forest.inc/docs/reference/playables/getTransactionsHtmlSandboxPreview

## Endpoint

`GET /playables/{projectId}/html/preview/transactions`

## Parameters

- `projectId` (path, required)
- `perPage` (query) — Number of items per page
- `page` (query) — Page number
- `direction` (query) — Sort direction
- `orderBy` (query) — The field to sort by

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Invoke a sandbox runtime method from the test harness

> Runs a generated backend method against the sandbox project using its real runtime and ledger. Requires a sandbox preview token.

Source: https://forest.inc/docs/reference/playables/invokeRuntimeHtmlSandboxPreview

## Endpoint

`POST /playables/{projectId}/html/preview/rpc`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Issue an identity code for the sandbox player

Source: https://forest.inc/docs/reference/playables/issueIdentityCodeHtmlSandboxPreview

## Endpoint

`POST /playables/{projectId}/html/preview/identity/codes`

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Batch upload project images

> Upload multiple project images simultaneously. Field names should match image names (e.g., heads, tails, background). This prevents race conditions when uploading multiple images.

Source: https://forest.inc/docs/reference/projects/batchUploadImagesProject

## Endpoint

`POST /projects/{projectId}/images/batch`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Create a project

> Creates a new blank project for the token. Must be called after the user chooses the template. Use the update endpoint to populate it with data

Source: https://forest.inc/docs/reference/projects/createProject

## Endpoint

`POST /projects`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Delete a project

> Deletes a project. The project must be in draft status.

Source: https://forest.inc/docs/reference/projects/deleteProject

## Endpoint

`DELETE /projects/{projectId}`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get a project

> Return a specific project

Source: https://forest.inc/docs/reference/projects/getProject

## Endpoint

`GET /projects/{projectId}`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List projects

> Lists all projects created by the user.

Source: https://forest.inc/docs/reference/projects/listProjects

## Endpoint

`GET /projects`

## Authentication

- `bearer`

## Parameters

- `orderBy` (query) — The field to sort by
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Update a project

> Updates an already existing project. The project must be in draft status, except autoSwapsEnabled which can be changed after publish for HTML v2 projects. If the body contains status and it's set to live, it will publish the project

Source: https://forest.inc/docs/reference/projects/updateProject

## Endpoint

`PATCH /projects/{projectId}`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Upload project image

> Used to upload an image needed for a project

Source: https://forest.inc/docs/reference/projects/uploadImageProject

## Endpoint

`POST /projects/{projectId}/images`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Request body

Required.

- `multipart/form-data`

## Responses

- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Claim a quest reward

Source: https://forest.inc/docs/reference/quests/claimQuestQuest

## Endpoint

`POST /quests/{namespace}/{key}/claim`

## Authentication

- `bearer`

## Parameters

- `namespace` (path, required)
- `key` (path, required)

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# List active quests for a namespace

Source: https://forest.inc/docs/reference/quests/getQuestsQuest

## Endpoint

`GET /quests`

## Parameters

- `namespace` (query, required) — Quest namespace to list

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get seed ledger activity for current user

> Returns paginated ledger activity for the authenticated user, optionally filtered by source type.

Source: https://forest.inc/docs/reference/seeds/getActivitySeed

## Endpoint

`GET /seeds/activity`

## Authentication

- `bearer`

## Parameters

- `sourceType` (query) — Filter ledger activity by source type
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `orderBy` (query) — The field to sort by
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get seed balance for current user

> Returns the available seed balance for the authenticated user, optionally with a per-source-type breakdown.

Source: https://forest.inc/docs/reference/seeds/getBalanceSeed

## Endpoint

`GET /seeds`

## Authentication

- `bearer`

## Parameters

- `includeBreakdown` (query) — Include seed balance breakdown by source type (default: false)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Create a swap session

> Verifies the user-submitted createSession transaction and stores the active session.

Source: https://forest.inc/docs/reference/swap-sessions/createSwapSession

## Endpoint

`POST /swap-sessions`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get project swap-session executor wallet

> Creates the Forest-managed executor wallet for the configured swap-session chain if it does not exist, then returns the address and gas balance for an HTML project owned by the current user.

Source: https://forest.inc/docs/reference/swap-sessions/getExecutorWalletProjectSwapSession

## Endpoint

`GET /projects/{projectId}/swap-sessions/executor-wallet`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get project swap sessions

> Returns whether auto-swaps are ready for a live HTML project and the current user swap sessions for that project.

Source: https://forest.inc/docs/reference/swap-sessions/getProjectSwapSessionsProjectSwapSession

## Endpoint

`GET /projects/{projectId}/swap-sessions`

## Authentication

- `bearer`

## Parameters

- `projectId` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get current user swap session

Source: https://forest.inc/docs/reference/swap-sessions/getSwapSession

## Endpoint

`GET /swap-sessions/{id}`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Request a swap session transaction

> Returns required token approvals and user-wallet transaction calldata for createSession without creating a database row.

Source: https://forest.inc/docs/reference/swap-sessions/requestSwapSession

## Endpoint

`POST /swap-sessions/request`

## Authentication

- `bearer`

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Confirm swap session revoke

> Confirms the user-submitted revokeSession transaction and marks the local session revoked.

Source: https://forest.inc/docs/reference/swap-sessions/revokeSwapSession

## Endpoint

`POST /swap-sessions/{id}/revoke`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Create a token

> Creates a new token for the user. The image is required and the status will be set to draft

Source: https://forest.inc/docs/reference/tokens/createToken

## Endpoint

`POST /tokens`

## Authentication

- `bearer`

## Request body

Required.

- `multipart/form-data`

## Responses

- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Delete a token

> Deletes a token. Will also delete all projects and their data. The token must be in draft status.

Source: https://forest.inc/docs/reference/tokens/deleteToken

## Endpoint

`DELETE /tokens/{tokenId}`

## Authentication

- `bearer`

## Parameters

- `tokenId` (path, required)

## Responses

- `204`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get token derived stats

> Returns derived token metrics that can be slower to calculate than the base token payload.

Source: https://forest.inc/docs/reference/tokens/getDetailStatsToken

## Endpoint

`GET /tokens/{tokenId}/stats`

## Parameters

- `tokenId` (path, required)
- `currency` (query) — Currency to convert the prices to

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get token holders

> Returns paginated list of token holders with balances and percentages

Source: https://forest.inc/docs/reference/tokens/getHoldersToken

## Endpoint

`GET /tokens/{tokenId}/holders`

## Parameters

- `tokenId` (path, required)
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `orderBy` (query) — The field to sort by
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get token stats

> Returns the stats for a token

Source: https://forest.inc/docs/reference/tokens/getStatsToken

## Endpoint

`GET /tokens/stats`

## Parameters

- `currency` (query) — Currency to convert the prices to

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get a token

> Returns a specific token. If the token is not published and the user is not the owner, will return 404

Source: https://forest.inc/docs/reference/tokens/getToken

## Endpoint

`GET /tokens/{tokenId}`

## Parameters

- `tokenId` (path, required)
- `currency` (query) — Currency to convert the prices to
- `populate` (query) — List of relations to populate, as a comma separated string. Allowed values: 'projects', 'projects.appTemplate', 'competitions'

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List tokens

> Lists all tokens. By default, only published tokens are returned. If owner=me is provided, returns all tokens for the user.

Source: https://forest.inc/docs/reference/tokens/listTokens

## Endpoint

`GET /tokens`

## Parameters

- `owner` (query) — Filters by the owner. Allowed values: 'me'. If 'me' is provided, the user must be authenticated. If not, only published tokens will be returned
- `orderBy` (query) — The field to sort by
- `search` (query) — Filters by the name and/or symbol
- `currency` (query) — Currency to convert the prices to
- `graduated` (query) — Filter by graduation status. true = graduated only, false = not graduated only.
- `populate` (query) — List of relations to populate, as a comma separated string. Allowed values: 'projects', 'projects.appTemplate', 'competitions'
- `page` (query) — Page number
- `perPage` (query) — Number of items per page
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Update a token

> Updates an existing token for the user.

Source: https://forest.inc/docs/reference/tokens/updateToken

## Endpoint

`PATCH /tokens/{tokenId}`

## Authentication

- `bearer`

## Parameters

- `tokenId` (path, required)

## Request body

Required.

- `multipart/form-data`

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get auction activity feed

Source: https://forest.inc/docs/reference/vault/getActivitySeedVault

## Endpoint

`GET /vault/auctions/{id}/activity`

## Parameters

- `id` (path, required)
- `page` (query) — Page (default: 1)
- `perPage` (query) — Per page (default: 20)
- `orderBy` (query) — The field to sort by
- `direction` (query) — Sort direction

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get auction detail

Source: https://forest.inc/docs/reference/vault/getAuctionByIdSeedVault

## Endpoint

`GET /vault/auctions/{id}`

## Parameters

- `id` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# List auctions

Source: https://forest.inc/docs/reference/vault/getAuctionsSeedVault

## Endpoint

`GET /vault/auctions`

## Parameters

- `status` (query) — Filter: live, upcoming, ended, or all (default)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get auction bidders

Source: https://forest.inc/docs/reference/vault/getBiddersSeedVault

## Endpoint

`GET /vault/auctions/{id}/bidders`

## Parameters

- `id` (path, required)
- `limit` (query) — Number of bidders (default: 100)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get aggregated chart data for an auction

Source: https://forest.inc/docs/reference/vault/getChartDataSeedVault

## Endpoint

`GET /vault/auctions/{id}/chart`

## Parameters

- `id` (path, required)
- `points` (query) — Number of data points (auto-scaled by duration if omitted, max: 100)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Get current user position

Source: https://forest.inc/docs/reference/vault/getUserPositionSeedVault

## Endpoint

`GET /vault/auctions/{id}/position`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)

## Responses

- `200`
- `401` — Unauthorized
- `500` — Internal server error


---

# Place or increase a bid

Source: https://forest.inc/docs/reference/vault/placeBidSeedVault

## Endpoint

`POST /vault/auctions/{id}/bid`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)

## Request body

Required.

- `application/json`

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Request claim signature for auction rewards

Source: https://forest.inc/docs/reference/vault/requestClaimSeedVault

## Endpoint

`POST /vault/auctions/{id}/claim`

## Authentication

- `bearer`

## Parameters

- `id` (path, required)

## Responses

- `200`
- `201`
- `401` — Unauthorized
- `500` — Internal server error


---

# Core Concepts Overview

> The mechanics that make token creation on Forest flexible, programmable, and predictable.

Source: https://forest.inc/docs/whitepaper/core-concepts-overview

<Callout type="info">
	FOREST is built on a set of mechanics that work together to make token creation flexible,
	programmable and predictable. This page explains the concepts you will see throughout the docs
	and how they interact when a token is launched inside the protocol.
</Callout>

Forest Protocol is a modular creation protocol on BNB Chain. Every part of a token — supply, pricing, staking, games, rewards and more — is configurable by the creator.

## 1. Token Structure

<Tabs items={['Supply', 'Distribution']}>

<Tab value="Supply">

Every token launched on Forest Protocol has a fixed supply of 1,000,000,000 tokens. Supply does not inflate or change after launch. What creators control is how that supply is distributed and what mechanics operate around it — fees, buybacks, burns, staking rewards, and game vaults.

- Fixed supply: 1B tokens per launch
- Deflationary mechanics available through burns and buybacks
- Supply allocation is fully configurable at launch

</Tab>

<Tab value="Distribution">

Creators decide how the fixed supply is allocated:

- Liquidity
- Treasury
- Staking rewards
- Airdrops
- Game vault / reward pools
- External purposes

Distribution determines creator influence, available liquidity, and community incentives.

</Tab>

</Tabs>

## 2. Bonding Curves & Graduation

First permissionless launchpad with customizable bonding curves. The curve defines how token price moves during the early stage of its lifecycle.

<img
	src="/docs/images/bonding-curves.webp"
	alt="Bonding curve types — linear, logarithmic, and exponential price behaviour"
	style={{
		display: "block",
		margin: "1.5rem auto",
		maxWidth: "440px",
		width: "100%",
		borderRadius: "0.5rem",
	}}
/>

<Tabs items={['Curve Types', 'Curve Duration', 'Why It Matters']}>

<Tab value="Curve Types">

**Curve Types:**

- **Linear** — Steady price increase per buy. Predictable, transparent. Best for straightforward launches with no surprises.
- **Logarithmic** — Fast initial ramp that stabilizes over time. Rewards early participants while keeping later entries stable.
- **Exponential** — Slow start, steep acceleration as demand builds. Rewards patience and conviction.

</Tab>

<Tab value="Curve Duration">

The curve phase lasts until the graduation threshold is reached — an amount of $FOREST the creator selects from a set of predefined options at launch. This gives creators full control over how their token behaves at launch — whether it favors early adopters, smooth distribution, or narrative-driven momentum.

</Tab>

<Tab value="Why It Matters">

This mechanism gives creators full control over how their token behaves at launch — whether it favours early adopters, smooth distribution or narrative-driven volatility.

</Tab>

</Tabs>

## 3. Liquidity System

<Callout type="info">Liquidity is the backbone of every token launched in FOREST.</Callout>

Every token launched on Forest Protocol is paired with $FOREST liquidity from the first trade.

<Tabs items={['Curve Phase', 'Graduation', 'Why $FOREST Liquidity Matters']}>

<Tab value="Curve Phase">

The token begins on the bonding curve selected by the creator. The curve enables early price discovery and steady liquidity growth. No LP bootstrapping needed — virtual liquidity is live instantly.

</Tab>

<Tab value="Graduation">

Once a defined threshold is reached, the token transitions into a standard liquidity model. Price is set by pool balance. The token trades like any other asset in an automated market environment.

</Tab>

<Tab value="Why $FOREST Liquidity Matters">

- Every trade routes through $FOREST
- Every transaction feeds the $FOREST flywheel
- Every token benefits from protocol-backed liquidity from day one
- No cold starts. No empty pools.

Lifecycle: **Discovery → Stability → Long-term trading**

</Tab>

</Tabs>

## 4. Fees & Buybacks

Fees play a central role in how tokens behave in FOREST. Creators define both buy and sell fees, expressed as percentages.

<Tabs items={['Fee Routing', 'Buybacks']}>

<Tab value="Fee Routing">

Fees can route value in different ways:

- to project treasury
- to the protocol
- to automatic buybacks
- to burns
- to reward pools

</Tab>

<Tab value="Buybacks">

Creators can direct part of fee revenue into purchasing their own token from the market. This can:

- Introduce deflationary pressure
- Support liquidity depth
- Create predictable recurring demand
- Fund reward pools for games and campaigns

</Tab>

</Tabs>

## 5. Staking & Reward Mechanics

Forest Protocol has two staking layers — protocol-level $FOREST staking and project-level token staking. Both are native. No third-party contracts. No extra setup.

<Tabs items={['$FOREST Staking', 'Individual Token Staking', 'Why Both Matter']}>

<Tab value="$FOREST Staking">

[Staking](https://forest.inc/stake) $FOREST is the core participation mechanic of the protocol:

- Earn APY on staked $FOREST (variable, based on staking duration and total staked)
- Earn Seeds — the off-chain currency used to claim token rewards through Seed Vault auctions
- Longer lock durations earn higher multipliers on both yield and Seeds
- Duration options: 1, 3, 6, 9, 12 months

</Tab>

<Tab value="Individual Token Staking">

Every token launched on Forest Protocol can be configured with built-in staking:

- Creators allocate a portion of token supply toward staking rewards
- Rewards can be fixed, dynamic, or tied to app engagement
- Creators set the pacing and size of reward emissions
- Stakers earn yield in the project token
- Encourages long-term holding and active participation in the token's economy

</Tab>

<Tab value="Why Both Matter">

- $FOREST staking connects users to the protocol economy — Seeds, auctions, flywheel
- Token staking connects holders to the individual project economy — yield, rewards, retention
- Both run simultaneously. A user can stake $FOREST for Seeds and yield and stake a project token for yield at the same time.

</Tab>

</Tabs>

## 6. $FOREST & Seed Economy

<Tabs items={['$FOREST', 'Seeds', 'Seed Vault', 'The Loop']}>

<Tab value="$FOREST">

The native token and liquidity backbone:

- Every token launched is paired with $FOREST
- Every trade routes through it
- Every fee and buyback touches it
- It's the value layer everything sits on

</Tab>

<Tab value="Seeds">

The off-chain currency of the Forest economy. Earned by:

- Staking $FOREST
- Joining Trading competitions
- Participating in specified play campaigns

Seeds are not tradeable. They are usable — in the Seed Vault.

</Tab>

<Tab value="Seed Vault">

Time-bound auctions where Seeds convert into real tokens:

- Each auction has a fixed reward pool ($FOREST or partner tokens)
- Users deposit Seeds to compete for a pro-rata share
- Top depositors earn multipliers on their effective Seed count
- Rewards distributed proportionally when the auction ends

[Seed Vault](https://forest.inc/vault)

</Tab>

<Tab value="The Loop">

Stake, trade, play → Earn Seeds → Deposit in Vault → Claim token rewards → Stake, trade, play again

</Tab>

</Tabs>

## 7. Trading Environment

The trading interface adapts based on the token's current state.

**During Curve Phase:** Trades follow the bonding curve formula.

**After Graduation:** Trading follows the liquidity pool balance.

**Visible to users at all times:**

- Current price
- Liquidity depth
- Fees
- Recent trades
- Buyback activity
- Tokenomics overview

Full transparency. Anyone can understand how a token behaves at a glance.

## 8. Creator Control & Finality

Before publishing, the creator can modify all configuration settings.

Once published, the token becomes immutable:

- Tokenomics are frozen
- Fees and routes are locked
- Distribution cannot be changed

Forest gives creators full flexibility before deployment, and users full predictability after.


---

# $FOREST & Seed Economy

> The economics behind Forest Protocol — $FOREST as the liquidity backbone, Seeds as the incentive layer.

Source: https://forest.inc/docs/whitepaper/forest-and-seed-economy

![$FOREST & Seed Economy](/docs/images/seed-economy-banner.webp)

<Callout type="info">
	$FOREST is the economic backbone of the protocol. Seeds are the incentive layer that rewards
	participation and aligns users with protocol growth. Together, they form a self-sustaining
	flywheel.
</Callout>

Every token launched on Forest Protocol pairs with $FOREST. Every trade routes through it. Every fee and buyback touches it. $FOREST is the liquidity backbone and the value layer everything sits on.

## Why $FOREST Matters

- **Shared liquidity** — All tokens pair with $FOREST. More tokens launched = deeper $FOREST liquidity. Every launch strengthens the pool.
- **Value routing** — Whether users are buying meme tokens, playing games, or trading — volume flows through $FOREST. Even users who never buy $FOREST directly contribute to its flywheel.
- **Deflationary pressure** — Protocol fees and creator-configured buybacks continuously purchase $FOREST from the market. More activity = more buybacks = more demand.
- **Protocol-backed launches** — Every new token launches with $FOREST liquidity from the first trade. No bootstrapping. No cold starts. No empty pools.

<Callout type="warn" title="Edgars, CEO | FOREST">
"Everything people do in FOREST feeds the ecosystem. That's the whole point."

🔗 Original post: [x.com/0xEulers/status/1990419891245990047](https://x.com/0xEulers/status/1990419891245990047)

</Callout>

## SEED: The Incentive Layer

Seeds are the off-chain currency of the Forest Protocol economy. They are earned through participation and used to claim real token rewards.

**How to Earn Seeds:**

- **Stake $FOREST** — Longer lock durations earn higher Seed multipliers (1, 3, 6, 9, 12 months)
- **Trade Campaigns** — Buy or sell the campaign tokens on Forest Protocol.
- **Quest Board** — Complete tasks in Seed Vault

Seeds are not tradeable. They are not transferable. They have one purpose: earning real token rewards through the Seed Vault.

## Seed Vault

The Seed Vault is where Seeds turn into real token rewards. It's a time-bound auction system at the core of the Forest economy.

**How It Works:**

<Steps>

<Step>An auction launches with a fixed reward pool (e.g. 100K $FOREST or partner tokens)</Step>

<Step>Users bid Seeds into the auction during the open period</Step>

<Step>
	When the auction ends, the reward pool is distributed pro-rata based on each user's share of
	total Seeds deposited
</Step>

<Step>Top depositors earn multipliers that boost their effective Seed count</Step>

</Steps>

## The Flywheel

Every part of Forest Protocol feeds the same loop:

1. **Launch** — New tokens launch with $FOREST liquidity and games attached
2. **Trade** — Volume routes through $FOREST. Fees generate buybacks. Traders earn Seeds in competitions.
3. **Stake** — $FOREST stakers earn yield and Seeds. Longer locks earn more.
4. **Auction** — Seeds are deposited into Seed Vault auctions to claim $FOREST and partner tokens
5. **Repeat** — Claimed tokens flow back into trading, staking, and gameplay. More Seeds earned. More auctions entered.

More creators → more tokens → more games → more players → more volume → more Seeds → more auctions → more $FOREST demand → more creators.

The loop is self-sustaining. Every new app, game, or agent that plugs in compounds the same economy.

## $FOREST Tokenomics

<Callout type="warn">
	**Ticker:** $FOREST
	<br />
	**Total Supply:** 1,000,000,000
	<br />
	**CA (BNB Smart Chain – BEP20):** `0x11cf6bf6d87cb0eb9c294fd6cbfec91ee3a1a7d0`
</Callout>

| Pool            | %   | Tokens      | Unlock | Cliff | Vesting |
| --------------- | --- | ----------- | ------ | ----- | ------- |
| Team & Advisors | 19% | 190,000,000 | 0%     | 18m   | 48m     |
| Investors       | 23% | 230,000,000 | 0%     | 12m   | 21m     |
| Public Sale     | 2%  | 20,000,000  | 100%   | 0     | 0       |
| Staking         | 15% | 150,000,000 | 0%     | 0     | 60m     |
| Rewards         | 12% | 120,000,000 | 10%    | 0     | 12m     |
| Liquidity       | 5%  | 50,000,000  | 50%    | 0     | 12m     |
| Community       | 24% | 240,000,000 | 10%    | 0     | 60m     |


---

# Forest Builder

> A prompt-native creation layer for Forest Protocol — one sentence in, a live economy out.

Source: https://forest.inc/docs/whitepaper/forest-builder

![Forest Builder](/docs/images/forest-builder-banner.webp)

<Callout type="info">One sentence in. A live economy out.</Callout>

## What is Forest Builder?

Forest Builder is a prompt-native creation layer for Forest Protocol. Describe what you want to build and Forest Builder assembles it on Playkit infrastructure, configures the token mechanics, wires the economy, and deploys it live.

## How It Works

<Steps>

<Step>Describe your app or game to Forest Builder</Step>

<Step>
	Builder assembles it on Playkit rails — wallets, trading, vaults, settlement all wired in
</Step>

<Step>Configure your token mechanics — supply allocation, bonding curve, staking, fees</Step>

<Step>Review and deploy</Step>

<Step>Your app is live with a working token economy</Step>

</Steps>

The build step becomes a sentence. The economy runs itself from the first trade.

## What Forest Builder Handles

- **App generation** — Converts your description into a functional app or game
- **Playkit wiring** — Automatically connects wallets, trading, vaults, and settlement
- **Token configuration** — Sets up tokenomics, bonding curve, staking, and fee structure
- **Deployment** — Pushes the app live on Forest Protocol with $FOREST liquidity from the first trade

## What Makes It Unique

Most no-code tools stop at the app. Forest Builder additionally builds the entire economy around it. Token, liquidity, staking, game vault, settlement layer, Seed integration. All from a prompt. All live on BNB Chain.


---

# Forest Cloud

> The always-on autonomous infrastructure layer where AI agents run on Forest Protocol.

Source: https://forest.inc/docs/whitepaper/forest-cloud

![Forest Cloud](/docs/images/forest-cloud-banner.webp)

<Callout type="info">Forest Builder creates. Forest Cloud operates.</Callout>

## What is Forest Cloud?

Forest Cloud is the always-on autonomous infrastructure layer where AI agents run on Forest Protocol. It extends every capability of the protocol — launching, trading, managing, settling — to agents operating 24/7 without human intervention.

## What Agents Can Do

- **Trade (Live)** — Buy and sell any token on the platform with balance awareness
- **Launch tokens (Soon)** — Deploy new tokens with full tokenomics configuration
- **Deploy apps and games (Soon)** — Build and ship through Forest Builder autonomously
- **Settle game actions (Soon)** — Process player results through the settlement API

## Agent Payments — Binance x402

For agents to operate autonomously, they need to pay autonomously. Forest Cloud integrates Binance x402 — the native payment protocol for agents on BNB Chain.

- Agents pay service fees per action natively on-chain
- No human signing or approval required
- Every token deployment, every trade, every settlement — agents pay and execute in a single call


---

# How Forest Playkit Works

> The no-code economic infrastructure layer powering every app and game on Forest Protocol.

Source: https://forest.inc/docs/whitepaper/forest-playkit

![How Forest Playkit Works](/docs/images/forest-playkit-banner.webp)

<Callout type="info">
	The no-code economic infrastructure layer powering every app and game on Forest Protocol.
	Builders focus on the experience. Playkit runs the economics.
</Callout>

## What is Playkit?

Forest Playkit is the settlement and economy engine that sits between any app and the Forest Protocol economy. It handles every financial operation a game or app needs — wallets, trading, vaults, settlements, leaderboards — so builders ship with a complete economic stack without smart contract development.

## Infrastructure Stack

- **Wallet Integration** — Automatic. Players connect once, every game reads their wallet. No SDK setup, no wallet libraries, no boilerplate.
- **In-Game Trading** — Players buy and sell tokens directly inside the game. They never leave the screen to trade.
- **Game Vaults** — Every project deploys with a dedicated vault. Creators set a reward pool percentage at launch. The vault funds automatically. Forest enforces solvency — if the vault runs low, payouts cap. It never pays out more than it holds.
- **Server-Side Settlement** — Game results settle through the developer's backend, not the browser. Signing secrets stay off the frontend. Safer for builders, harder to exploit.
- **Player-Approved Actions** — Before any game action is settled, the player authorizes the maximum amount that can be charged. No surprises. Full transparency on worst-case cost.
- **Settlement Validation** — Forest validates every settlement call against guardrails:
    - Max payout per action
    - Max payout multiplier
    - Daily payout caps
    - Idempotent action IDs (no duplicate settlements)
    - Vault solvency checks
- **Leaderboards** — Player rankings based on game activity, trading volume, or custom metrics. Built in, no extra development.
- **Reward Pools** — Configurable token pools that distribute to players based on activity. Funded from supply allocation, or manual top-up.
- **Deposits & Withdrawals** — Wallet-signed, on-chain transactions. Players deposit tokens into the game, play, and withdraw earnings. Full transaction history available.
- **Live Price Data** — Real-time swap quotes, price impact, and liquidity depth. Games can build UI around actual market conditions.
- **Balance-Aware Mechanics** — Read the player's live token balance and build game logic around it. Bet sizing, entry gates, reward tiers — all dynamic, all real.

## How the Settlement Flow Works

<Steps>

<Step>Player performs an action in the game</Step>

<Step>Game calls the developer's backend to determine the result</Step>

<Step>Developer backend submits the result to Forest's settlement API</Step>

<Step>Forest validates — balance, payout limits, vault solvency, action uniqueness</Step>

<Step>Game balance updates</Step>

<Step>Player withdraws to wallet anytime</Step>

</Steps>

Developers own the game logic. Forest owns the settlement layer. The separation is clean and secure.

<Callout type="info">
	Building an integration? The [Forest Playkit developer docs](/docs/developers/forest-playkit)
	cover the bridge, RPC methods, and signed backend settlement in full.
</Callout>


---

# Launch Tokenomics

> How supply, fees, curves, buybacks, and distribution combine into a complete economic system.

Source: https://forest.inc/docs/whitepaper/launch-tokenomics

![Launch Tokenomics](/docs/images/launch-tokenomics-banner.webp)

<Callout type="info">
	Tokenomics in FOREST is built around one principle: **every token should be able to express its
	own economic behaviour.**
</Callout>

Instead of forcing tokens into a fixed template, FOREST allows creators to configure supply, fees, curves, buybacks, and distribution logic in a modular way. This section explains how each component works and how they interact to form a complete economic system.

## 1. Supply Model

<Callout type="warn">Every token launches with a fixed total supply of 1,000,000,000.</Callout>

The full supply is minted at launch and split across the allocation pools — no tokens
are minted afterwards:

- Buys and sells move tokens between the bonding-curve pool and holders
- Burns permanently remove tokens from circulation
- Staking, rewards, and airdrops draw from the defined allocation pools

#### Circulating Supply updates in real time based on:

- tokens bought
- tokens sold
- tokens staked
- tokens burned
- tokens claimed from airdrops

<Callout type="info">
	[ Creator Configuration ] → [ Allocation Pools ] → [ Live Supply Behaviour ]
</Callout>

This gives creators flexibility while ensuring users can always track supply transparently.

## 2. Allocation Splits

Creators define how the token's initial distribution is split across four main pools:

| Pool        | Purpose                                                                 |
| ----------- | ----------------------------------------------------------------------- |
| Liquidity   | Tokens paired with $FOREST to open trading and price discovery          |
| Reserve     | Project-owned supply for future use (team, marketing, ecosystem growth) |
| Staking     | Tokens rewarded to participants staking into the ecosystem              |
| Reward Pool | Tokens funding in-game rewards for the token's playable experience      |

These percentages always equal **100%**.

#### Example:

- Liquidity: 40%
- Reserve: 25%
- Staking: 20%
- Reward Pool: 15%

#### How Splits Work in Practice

- Liquidity is locked into the pool at publish.
- Reserve tokens remain in the project's control.
- Staking rewards release over time based on staking behaviour.

## 3. Fees

Fees create the economic engine that powers each token.

Creators configure:

- Buy Fee: 0–93.9%
- Sell Fee: 0–93.9%

(The cap reserves the fixed 5% protocol fee and 0.1% IP fee within the 99% ceiling.)

Fees can be routed to:

- creator treasury
- protocol
- buybacks
- other configured destinations (depending on template)

#### Example Fee Routing

**Buy Fee (5%)**

- 2% → Creator Treasury
- 2% → Protocol
- 1% → Buybacks

**Sell Fee (7%)**

- 3% → Protocol
- 4% → Buybacks

Fees influence:

- sustainability
- token liquidity
- long-term incentives
- market behaviour

<Callout type="error">
	High buy fees can discourage rapid entry. High sell fees can discourage dumping. Balanced fees
	stabilise the ecosystem.
</Callout>

## 4. Buybacks

Buybacks convert a % of collected fees or app revenue into automatic purchases of the token.

Buyback % can be configured from 0–100%.

#### Buybacks can operate in two modes:

**A. Buy and Hold**

Purchased tokens move into a designated treasury or module.

**B. Buy and Burn**

Purchased tokens are permanently removed from supply. Burning reduces circulating supply and increases scarcity.

## 5. Full Token Lifecycle Diagram

<Callout type="info">
	This section outlines the complete lifecycle of a token created through FOREST, from initial
	configuration to long-term ecosystem mechanics.
</Callout>

### Lifecycle Overview

The token moves through a series of defined states. Each state activates new mechanics while preserving the logic set by the creator.

<Tabs items={['Conceptual Explanation', 'Lifecycle Flow']}>

<Tab value="Conceptual Explanation">

- **Creator Config** — The creator defines all foundational mechanics.
- **Bonding Curve Launch** — Early trading builds liquidity and price discovery.
- **Graduation Threshold Hit** — A milestone that triggers progression into full liquidity.
- **AMM Liquidity Mode** — Advanced token features activate and market dynamics expand.
- **Long-term Ecosystem Mechanics** — The token reaches its mature phase and operates as part of a broader ecosystem.

</Tab>

<Tab value="Lifecycle Flow">

#### 1. Creator Config

This is the starting point. All parameters, mechanics, curves, fees, and logic are defined here.

↓

#### 2. Bonding Curve Launch

The token begins trading on its bonding curve. Liquidity expands automatically as trading occurs.

↓

#### 3. Graduation Threshold Hit

Once the graduation threshold is reached, the system transitions from bonding curve mode into open liquidity.

↓

#### 4. AMM Liquidity Mode

The token now trades in AMM liquidity. Active systems begin operating:

- fees
- buybacks
- staking
- airdrops

↓

#### 5. Long-term Ecosystem Mechanics

Sustained behaviour, rewards, supply logic, and ongoing token utilities evolve here.

</Tab>

</Tabs>

<Callout type="success">
	The lifecycle ensures that a FOREST token evolves from a creator-defined concept into a fully
	autonomous economy with ongoing mechanics.
</Callout>


---

# The Vision

> A glimpse into Forest Protocol’s future and trajectory.

Source: https://forest.inc/docs/whitepaper/the-vision

![The Vision](/docs/images/the-vision-banner.webp)

## The Problem

Token launches are broken. Every launchpad does the same thing — deploy a token with no utility, no economy and no reason to come back. Creators launch into nothing. Communities show up and leave.

Games on-chain were broken too. GameFi 1.0 forced studios to build everything from scratch — smart contracts, wallet integrations, liquidity, backends — before a single player could show up. Most didn't survive the build phase.

The missing piece was always the same: economic infrastructure.

## What Forest Protocol Is

Forest Protocol is a modular creation protocol on BNB Chain where tokens, apps, and games launch into a programmable, self-sustaining economy.

Three layers power it:

- **Forest Playkit** — No-code economic infrastructure. Wallets, trading, vaults, settlement, leaderboards, reward pools. Any app ships with a complete token economy without a single smart contract.
- **Forest Builder** — Prompt-native creation. Describe what you want. Builder assembles it on Playkit rails and deploys it live. One conversation to a live economy.
- **Forest Cloud** — Autonomous operations for AI agents. Launch, trade, manage, settle — all via API, 24/7, without human intervention. Agent payments powered by Binance x402 on BNB Chain.

## The Economy

Everything on Forest Protocol feeds the same flywheel:

- Every token launched is paired with $FOREST liquidity
- Every trade routes through $FOREST
- Protocol participation earns Seeds
- Seeds convert into real token rewards through Seed Vault auctions
- Rewards flow back into trading, staking, and gameplay

Stake, trade, play → earn Seeds → claim tokens → repeat. The loop is self-sustaining. Every new app, game, or token compounds the same economy.

## The Agentic Thesis

The next wave of on-chain activity won't come from humans alone. AI agents are already trading, deploying, and managing assets autonomously. The protocols that win are the ones agents can operate on natively.

Forest Protocol is built for this. Major protocol mechanics are programmable and accessible to agents through Forest Cloud. Same infrastructure humans use. Same liquidity. Same settlement. Same flywheel. The protocol scales with every agent that plugs in.

## The Big Picture

Forest Protocol is building toward a future where economies create themselves. Where a prompt becomes an app, an app becomes an economy, and an economy runs and grows without anyone needing to maintain it. Humans and agents building side by side on the same rails, generating value through the same flywheel, at any scale, around the clock. The infrastructure is live. The economy is running.