API reference v2

This section describes different op codes of AMM smart contracts v2

API reference

Overview

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

• Pool

• Router

• LpAccount

• LpWallet

• Vault

Definitions of terminology used can be found in Glossary

Example schemes

Example schemes can be found here:

• Swap examples

• Lp provide examples

• Vault examples

Op code list

A table with DEX v2 op codes:

• 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%)

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 the0.01 %–1 % range and must later be withdrawn by the referrer. See the Omniston referral fees guide (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.

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