Developer DocumentationPlaykit Integration
Swap quote, buy, and sell methods, plus the snapshot shape.
Swaps run through the connected wallet. Quote is a read; buy and sell open the wallet. Params are strict: unknown keys, numeric amounts, or currency/direction on buy and sell fail with INVALID_PARAMS. A newer quote replaces an in-flight one, which then gets no answer. Amounts are display decimal strings — see Amounts. For user-approved auto-swaps, see Swap Sessions.
For Harness games, import { forest } from @forest/runtime and await the calls below. Legacy HTML uploads pass the same params to callForest("forest.swap.quote", params) and the other named methods.
forest.swap.quoteGets a read-only quote and snapshot. This does not open the wallet or submit a transaction.
await forest.swap.quote({
amount: "0.05",
direction: "buy",
slippage: 0.5,
});Prop
Type
Pass currency: "FOREST" to price a swap session trade. Forest reads the market at one block and does not change the swap widget.
const { sessionQuote, snapshot } = await forest.swap.quote({
amount: "1",
direction: "buy",
currency: "FOREST",
slippage: 1,
});For a buy, amount is the most FOREST to spend, including slippage. For a sell, amount is the exact Project Token amount to sell. Its decimals cannot exceed the pay token's decimals. BNB amounts are not supported.
Prop
Type
snapshot here is smaller than the wallet snapshot below: direction, slippage, payToken.symbol, receiveToken.symbol, and quote.payAmount/quote.receiveAmount as display strings. Send sessionQuote to your backend, which passes its amounts and expiresAt to executeSwapSession. Fetch a new quote after expiresAt.
Session quotes fail with QUOTE_FAILED when the chain head is stale or the trade cannot fit the budget, and with SWAP_UNAVAILABLE when the token has no Forest pair. Harness Preview ignores currency and returns no sessionQuote; test that path with a fixture.
forest.swap.buySubmits a buy transaction through the connected wallet. amount is the amount of the pay token to spend. Success returns { txHash, snapshot }.
await forest.swap.buy({
amount: "0.05",
slippage: 0.5,
});Prop
Type
forest.swap.sellSubmits a sell transaction through the connected wallet. amount is the amount of the launched token to sell. Success returns { txHash, snapshot }.
await forest.swap.sell({
amount: "100",
slippage: 0.5,
});Prop
Type
The SDK's returned object can include snapshot; legacy message responses expose it as 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.
{
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.
Prop
Type
payToken / receiveTokenProp
Type
quoteWhen quote is present, it has:
Prop
Type
swapBreakdownWhen swapBreakdown is present, it has:
Prop
Type
Calculate spendable balance from the snapshot:
const available = snapshot.payToken.balance - (snapshot.payToken.locked || 0);Quote, buy, and sell failures use the shared swap error taxonomy. See Errors and Security for each code's cause and resolution.