> 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/installation.md).

# Installation

```sh
npm add @surged/sdk viem
```

MIT licensed. The package is pure TypeScript on top of [viem](https://viem.sh): no React, no Node APIs, no network calls of its own. It runs the same in a browser, in a worker and on a server.

`viem` is a peer in practice. The package returns viem's types and expects you to send the calldata with it, though nothing stops you passing the `data` and `value` it returns to ethers or to a raw JSON-RPC call.

## What is in it

| Module      | What it gives you                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `curve`     | `previewBuy`, `previewSell`, `applyBuy`, `applySell`, `curveStateFromApi`, `sellableTokens`, `readyToGraduate` and the math underneath. |
| `encoders`  | `encodeBuy`, `encodeSell`, `encodeLaunchToken`, `encodeLaunchAndBuy` and the bundle variants.                                           |
| `units`     | `toNativeUnits`, `toErc20Units`, `minOutWithSlippage`, `BPS`.                                                                           |
| `bundle`    | `bundleBuyTypedData`, `hashBundleBuy`: the consent a wallet signs to join a bundle.                                                     |
| `errors`    | `explainError`, `decodeLaunchpadError`: a stable code and a sentence, never raw calldata.                                               |
| `chains`    | `arc`, `arcTestnet`, `USDC_PREDEPLOY`, `NATIVE_QUOTE`, `ARC_BLOCK_TIME_MS`.                                                             |
| `abi`       | The generated ABIs: factory, curve, hooked curve, forwarder, escrow, token, locker.                                                     |
| `addresses` | `deployments[chainId]`, generated from the contracts repo.                                                                              |

## Every amount is a bigint

Nothing in this package takes or returns a `number` for an amount. Token balances and USDC amounts on Arc do not fit in a JavaScript number, and a quote computed through one is wrong without failing.

The api sends amounts as decimal strings for the same reason. `curveStateFromApi` is the one place they become `bigint`; use it rather than mapping the fields yourself.

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

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

## Versions

The package ships the addresses of the live contracts, so a version is a claim about what is on chain.

* **A redeploy of any contract is a minor bump, never a patch.** Pinning `~0.2.0` keeps you on contracts that still exist.
* **The formula and the encoders change only on a minor.** A patch is for a bug that made this package disagree with the chain, where the old behaviour was already wrong.

While the package is `0.x` the public surface may still change between minors. Pin an exact version if you run unattended.


---

# 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/installation.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.