Trade Previews

Curve previews use the Curve fee policy and the same checked cash-flow calculations as the amount helpers.

import { DumpsterClient } from '@dumpster-cash/dumpster-sdk';

const client = new DumpsterClient(connection);

Units and price impact

Preview rates and transaction slippage use different units:

priceImpactBps measures an absolute price difference relative to the pre-trade spot price, rounded down to whole basis points. It has no direction sign.

Curve buys compare post-trade spot against pre-trade spot. Curve sells and both AMM directions compare execution against pre-trade spot. Execution includes buy fees or uses net sell proceeds. These measurements are not interchangeable estimates of reserve movement or limits on a later fill.

prices contains exact ratios in asset base units; apply mint decimals when displaying token prices. See fee helpers for fee selection and rounding.

In SDK 2.0.0 and 2.0.1, price impact remains a JavaScript number. Extreme reserve ratios can exceed its safe conversion range and make a preview throw even when the integer amount helper can quote the trade. Treat that as unavailable, not as a zero-price quote.

Curve buy preview

Start here when the user enters a GOR trade budget. Fetch the paired Curve state before calling this pure preview.

import BN from 'bn.js';

const preview = client.preview.curveBuy({
  feeConfig,
  bondingCurve,
  amountInGor: new BN(1_000_000_000),
});

Key fields:

• preview.amountOutTokens -> token output after fees
• preview.amountInGor -> actual fee-inclusive trade cost, which can be less than the budget
• preview.amountInNetGor -> fee-exclusive principal added to the curve
• preview.fees.feeAmountGor -> sum of independently rounded protocol and applicable creator fees
• preview.priceImpactBps -> change between post-trade and pre-trade reserve spot prices
• preview.postTradeReserves -> virtual reserves after applying principal and token output

The result selects the greatest affordable token output within sale inventory. A zero/no-affordable-output budget returns zero spend, fees and output with unchanged reserves; do not build a buy instruction from it. Positive output equal to remaining inventory completes the sale.

Curve buy preview by target output

Choose this path when the target token output is known and the missing number is the required GOR input.

const preview = client.preview.curveBuyExactOut({
  feeConfig,
  bondingCurve,
  amountOutTokens: new BN(25_000_000_000),
});

Key fields:

• preview.amountInGor -> total GOR input required
• preview.amountInNetGor -> GOR that actually reaches the curve after fees
• preview.amountOutTokens -> exact token output being targeted

Curve sell preview

Start here when the user enters a token amount to sell.

const preview = client.preview.curveSell({
  feeConfig,
  bondingCurve,
  amountInTokens: new BN(25_000_000_000),
});

Key fields:

• preview.amountOutGorGross -> output before fees
• preview.amountOutGorNet -> output after fees
• preview.fees.feeAmountGor -> estimated fee amount
• preview.priceImpactBps -> net execution price difference from the pre-trade spot price

Gross output floors virtualGorReserves * amountInTokens / (virtualTokenReserves + amountInTokens). Post-trade virtual GOR reserves decrease by that gross amount, not the net estimate.

This matches the Curve sell calculation. The preview rejects completed state, invalid amounts, insufficient recorded liquidity, overflowing reserves and fee underflow. A valid zero-net sell remains a visible zero-GOR result, distinct from a thrown quote error. Other account/wallet checks can still prevent execution; choose a positive minimum if zero payout is unacceptable.

AMM buy preview

This preview answers the exact-output AMM buy question: how much quote does this output actually cost?

const preview = client.preview.swapBuy({
  feeConfig,
  pool,
  baseReserves,
  quoteReserves,
  baseMintSupply,
  baseAmountOut: new BN(5_000_000_000),
});

Key fields:

• preview.quoteAmountForSwap -> quote amount consumed by the pool before fees
• preview.quoteAmountInTotal -> total spend including fees
• preview.fees.totalFeeAmount -> total fee charged on the quote side
• preview.priceImpactBps -> fee-inclusive execution price difference from the pre-trade spot price

AMM buy preview by total quote input

This preview answers the exact-input AMM buy question: how much base output fits inside a total quote budget?

const preview = client.preview.swapBuyExactIn({
  feeConfig,
  pool,
  baseReserves,
  quoteReserves,
  baseMintSupply,
  quoteAmountInTotal: new BN(1_000_000_000),
});

Key fields:

• preview.baseAmountOut -> token output that fits inside the total quote budget
• preview.quoteAmountInTotal -> total quote input used for the preview
• preview.fees.totalFeeAmount -> total fee charged on the quote side
• preview.priceImpactBps -> fee-inclusive execution price difference from the pre-trade spot price

AMM sell preview

Start here when the sell size is known up front.

const preview = client.preview.swapSell({
  feeConfig,
  pool,
  baseReserves,
  quoteReserves,
  baseMintSupply,
  baseAmountIn: new BN(5_000_000_000),
});

Key fields:

• preview.quoteAmountOutGross -> quote output before fees
• preview.quoteAmountOutNet -> final output after fees
• preview.priceImpactBps -> net execution price difference from the pre-trade spot price

When the math helpers still make sense

The raw math helpers still exist for simulations, tests, and analytics. For quoting and transaction building, the preview surface is usually better because it keeps amounts, fees, impact, and post-trade state together.