Swaps

Swaps run through the connected wallet. Quote is a read; buy and sell open the wallet. Amounts are display decimal strings — see Amounts. For user-approved auto-swaps, see Swap Sessions.

Swap Methods

forest.swap.quote

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

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

forest.swap.buy

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

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

forest.swap.sell

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

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

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.

{
  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

payToken / receiveToken

quote

When quote is present, it has:

swapBreakdown

When swapBreakdown is present, it has:

Calculate spendable balance from the snapshot:

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 for each code's cause and resolution.