Player Identity

Project and Wallet Messages

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

Request the current wallet state:

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

Handle wallet state:

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.

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

forest.identity.code

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

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)

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

Request fields:

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

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}/campaigns/${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.
• 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).