# v2

## API reference

> **Important**: This API reference documents low-level smart contract methods and opcodes. For **production applications**, we **strongly recommend** using the [official SDK](https://docs.ston.fi/developer-section/dex/sdk/v2) + [TonConnect](https://docs.ton.org/develop/dapps/ton-connect/overview) instead of manually compiling BOCs and sending transactions. The SDK provides better developer experience, handles edge cases, and receives official support. Custom BOC compilation should only be used for specialized/advanced use cases.

### Overview

The section contains separate documents for each smart contract used in AMM:

* [Pool](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/pool)
* [Router](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/router)
* [LpAccount](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/lpaccount)
* [LpWallet](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/lpwallet)
* [Vault](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/vault)

### Example schemes

Example schemes can be found here:

* [Swap examples](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/swap)
* [Lp provide examples](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/lp-provide)
* [Vault examples](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/examples/vault)

### Op code list

A table with DEX v2 op codes:

* [Op Codes](https://docs.ston.fi/developer-section/dex/smart-contracts/v2/op-codes)

## New DEX v2 features:

### Swap

* custom payload & nested operations after swaps
* chain multiple swaps on the same `Router`
* chain multiple swaps on different v2 `Routers`
* custom refund address and payload on swap failure
* deadline for tx completion

### Liquidity

* custom payload after liquidly provision
* improved initial liquidity locking management, no coins are lost anymore
* now always mints a maximum possible amount of lp tokens to user even if provision ratio is different from current one in `Pool`
* single side liquidity provision
* deadline for tx completion

### Referral

* referral fees are stored in `Vault` contract
* custom referral fee value in each swap (maximum 1%)

> **Note**: Protocol fees in DEX v2 are collected in ASK jetton.

#### Referral Fees

DEX v2 accumulates each swap's referral portion in a dedicated `Vault` contract (one per `referrer × token` pair). Fees can be configured in the `0.01 %`–`1 %` range and must later be withdrawn by the referrer. See the Omniston [referral fees guide](https://docs.ston.fi/omniston/referral-fees#referral-fees-with-dex-v2) (note: although the guide is Omniston-oriented, the referenced paragraph explains in detail how DEX V2 referral fees work).

You can inspect vault balances and accrual history using the Stats & Vaults REST API:

* `GET /v1/wallets/{addr_str}/fee_vaults` – lists all known vaults per referrer
* `GET /v1/stats/fee_accruals` – shows all operations that led to fee accrual for the referrer, filterable by period
* `GET /v1/stats/fee_withdrawals` – lists all withdrawals from the referrer's vaults, filterable by period
* `GET /v1/stats/fees` – returns aggregated referral fee metrics (for example, total accrued USD value) by time frame

All endpoints are documented in the [Swagger UI](https://api.ston.fi/swagger-ui/#/).

### pTON v2

* now uses a custom op code for ton transfers
* ton transfer to user is non-bouncable
* improved gas management
* can chain ton transfers between 2 pTON wallets (to chain pTON swaps on v2 `Routers`)

### Other

* `LpAccount` and `Vault` are deleted if they have 0 tokens on balance to avoid paying storage cost
* better error management: no coins are lost if `Pool` doesn't exist / payload is not correct
* complete refactoring of the codebase and usage of libs in masterchain to make all operations cheaper
* fixed various excesses issues
* fixed some `Pools` having broken `get_jetton_data`

### Removed

#### Pool

* off-chain `get_expected_outputs`
* off-chain `get_expected_tokens`
* off-chain `get_expected_liquidity`
* on-chain `getter_expected_outputs`
* on-chain `getter_expected_tokens`
* on-chain `getter_expected_liquidity`
* user-called `collect_fees`