> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/dex/sdk/v2.md).

# Setup and environments (DEX v2)

Shared client setup, mainnet simulation and router metadata, testnet scope, and asset units.

The operation guides build transactions for DEX v2 contracts with `@ston-fi/sdk` 2.x, `@ston-fi/api`, and a TON client. Choose the operation directly: [Swap](https://docs.ston.fi/developer-section/dex/sdk/swap.md), [Add liquidity](https://docs.ston.fi/developer-section/dex/sdk/provide-liquidity.md), [Withdraw liquidity](https://docs.ston.fi/developer-section/dex/sdk/burn-lp-tokens.md), [Recover pending liquidity](https://docs.ston.fi/developer-section/dex/sdk/refund-liquidity.md), or [Claim integrator fees](https://docs.ston.fi/developer-section/dex/sdk/vault-operations.md).

## Mainnet clients

```ts
import { Client } from "@ston-fi/sdk";
import { StonApiClient } from "@ston-fi/api";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});
const apiClient = new StonApiClient();
```

The STON.fi REST API serves mainnet metadata and simulation. The TON RPC endpoint used for contract reads must match the network of those addresses. Follow provider configuration for authentication/rate limits when required.

## Metadata and contract selection

1. Discover/verify asset addresses and decimals with API asset methods; symbols are display labels.
2. For a swap or deposit, simulate the operation with the intended amount/slippage and user context.
3. Use the returned router metadata with `dexFactory()`; do not hardcode a different router from an old example.
4. Build the operation using simulation amounts/minimums. When TON participates, use the router's `ptonMasterAddress` and matching pTON wrapper.

For an existing pool/LP account/Vault, fetch its router metadata with `getRouter()` before constructing version-specific wrappers. A factory only supports versions/types implemented by the installed SDK; handle an unsupported result instead of forcing the latest wrapper onto an older contract.

Run a new simulation after changing the wallet, asset pair, amount, or referral configuration.

For browser integrations, configure your bundler for the TON libraries' runtime requirements, including `Buffer`. See the [example application](https://github.com/ston-fi/sdk/tree/main/examples/next-js-app) for configuration.

## Units and identifiers

DEX builder amounts use integer asset units. Read decimals from metadata; `toNano()` is appropriate for TON, not every jetton. Use `toUnits(displayAmount, verifiedDecimals)` for a decimal-aware conversion.

Use distinct query IDs for operations you need to correlate. Record the sender wallet, query ID, and outgoing external-message/transaction identifier returned by the wallet where available. See [REST API reference](https://docs.ston.fi/developer-section/dex/api/reference.md#transaction-query) for query/action-tree methods and the operation's own completion guidance.

## TON testnet

Testnet examples use `https://testnet.toncenter.com/api/v2/jsonRPC`. Configure testnet contract addresses, obtain testnet jettons, and fund the relevant pools. The STON.fi REST API serves mainnet data.

Configure your [wallet sender](https://docs.ston.fi/developer-section/common/transaction-sending.md) for the same network as the selected contracts.

## Fees

See [DEX fees](https://docs.ston.fi/developer-section/dex/fees.md) for direct versus Vault payout semantics, [Claim integrator fees](https://docs.ston.fi/developer-section/dex/sdk/vault-operations.md) for withdrawal code, and [REST reference](https://docs.ston.fi/developer-section/dex/api/reference.md#fee-statistics) for fee datasets.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/dex/sdk/v2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
