> For the complete documentation index, see [llms.txt](https://docs.surged.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.surged.fun/integration/sdk/quoting.md).

# Quoting a trade

`previewBuy` and `previewSell` run the contract's own arithmetic. They take a curve state and return what the trade would do, down to the last wei, without touching the chain.

## A buy

```ts
import { curveStateFromApi, previewBuy } from '@surged/sdk'

const launch = await fetch(`${API}/launches/${token}`).then((r) => r.json())
const { head } = await fetch(`${API}/health`).then((r) => r.json())

const quote = previewBuy(curveStateFromApi(launch), 10n * 10n ** 18n, {
  currentBlock: BigInt(head) + 1n,
  exempt: false,
})
```

What comes back:

| Field        | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| `spent`      | USDC actually used. Less than you offered only on a crossing buy.   |
| `tokensOut`  | Tokens delivered.                                                   |
| `fee`        | The 1% trade fee, in USDC.                                          |
| `creatorTax` | The creator's cut, in USDC.                                         |
| `snipeTax`   | The anti-snipe charge, in USDC. Zero outside the window.            |
| `net`        | What actually reaches the curve's reserve after the three charges.  |
| `crossing`   | `true` when this buy takes the last tokens and triggers graduation. |
| `refund`     | USDC the curve sends back on a crossing buy.                        |

**`currentBlock` is the block your buy will land in, not the current head.** A transaction sent now executes in the next block at the earliest. Quote against the head and you will under-report the snipe tax during a launch, which makes the buy revert on its slippage guard. See [Fees and the snipe tax](/integration/fees.md).

## A sell

```ts
import { previewSell } from '@surged/sdk'

const quote = previewSell(state, tokensIn)
```

Sells have no snipe tax and no block context. `quoteOut` is what you receive after the fee and the creator tax, both of which come back separately.

## Slippage

The quote is what happens if nothing moves in between. Something usually moves, so both entry points take a minimum and revert rather than fill you at a worse price.

```ts
import { minOutWithSlippage, DEFAULT_SLIPPAGE_BPS } from '@surged/sdk'

const minTokensOut = minOutWithSlippage(quote.tokensOut, DEFAULT_SLIPPAGE_BPS)
```

`DEFAULT_SLIPPAGE_BPS` is 2,000, or 20%, which is what the frontend defaults to on a curve this steep. During the snipe window the price moves violently, so a tight tolerance will simply revert; that is the correct outcome.

## Simulating a sequence

`applyBuy` and `applySell` return the state after a trade, which lets you price several trades in a row with no further reads. Useful for sizing a position, or for a bundle of buys that all land in the same block.

```ts
import { applyBuy, previewBuy } from '@surged/sdk'

let state = curveStateFromApi(launch)
const quotes = []
for (const amount of amounts) {
  const quote = previewBuy(state, amount, { currentBlock })
  quotes.push(quote)
  state = applyBuy(state, quote)
}
```

`readyToGraduate(state)` on the resulting state tells you whether the sequence closes the curve.

## Other helpers

* `sellableTokens(state)` — tokens still for sale, excluding the pool's reserved slice.
* `quoteToGraduation(state)` — USDC still needed before the curve closes.
* `spotPriceX18(state)` — price of one token in USDC, scaled by 1e18.
* `splitFees(fee, creatorTax, protocolFeeShareBps)` — how a trade's charges divide between the protocol and the creator.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.surged.fun/integration/sdk/quoting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.