API Reference

STON.fi DEX API reference - REST endpoints for pools, swaps, liquidity, and market data

This page provides a brief overview of all available endpoints in the STON.fi DEX API v1.168.0.

For detailed parameters, request/response schemas, and interactive testing, browse our Swagger UI or Redoc viewers.

Base URL: https://api.ston.fi

DEX Operations

Swap Simulation

POST /v1/swap/simulate - Simulate a token swap before execution. Calculates expected output, fees, and gas costs.

Reverse Swap Simulation

POST /v1/reverse_swap/simulate - Calculate required input amount to receive a specific output amount.

Liquidity Provision Simulation

POST /v1/liquidity_provision/simulate - Preview liquidity addition with support for Initial, Balanced, and Arbitrary provision types.

Swap Status

GET /v1/swap/status - Check the status of a swap operation using router address, owner address, and query ID.

Transaction Action Tree

POST /v1/transaction/action_tree - Return the flattened list of STON.fi actions and statuses triggered by an originating transaction.

Transaction Query

POST /v1/transaction/query - Resolve a transaction by (wallet_address + query_id) or ext_msg_hash; returns a TxId with lt, hash, and contract_address.

Routers

  • GET /v1/routers - List all available routers

  • GET /v1/routers/{address} - Get specific router details

Markets

GET /v1/markets - Get all available trading pairs

Assets

Asset Operations

  • GET /v1/assets - List all available assets

  • GET /v1/assets/{address} - Get specific asset details

  • POST /v1/assets/query - Query assets with conditions (supports search_term, sort_by, and limit filters)

  • POST /v1/assets/search - Legacy asset search endpoint; prefer POST /v1/assets/query

Jetton Operations

GET /v1/jetton/{address}/address - Get jetton wallet address for a specific owner

Pools

Pool Operations

  • GET /v1/pools - List all liquidity pools

  • GET /v1/pools/{address} - Get specific pool details

  • GET /v1/pools/by_market/{asset0}/{asset1} - Get pools for a token pair

  • POST /v1/pools/query - Query pools with conditions (supports search_term, sort_by, and limit; /v1/pool/query remains for backward compatibility)

Farms

Farm Operations

  • GET /v1/farms - List all farms

  • GET /v1/farms/{address} - Get specific farm details

  • GET /v1/farms/by_pool/{pool_address} - Get farms by pool

Wallets

Wallet-Specific Data

  • GET /v1/wallets/{address}/assets - Get wallet's assets

  • GET /v1/wallets/{address}/assets/{asset} - Get specific asset in wallet

  • GET /v1/wallets/{address}/pools - Get wallet's liquidity positions

  • GET /v1/wallets/{address}/pools/{pool} - Get specific pool position

  • GET /v1/wallets/{address}/farms - Get wallet's farm positions

  • GET /v1/wallets/{address}/farms/{farm} - Get specific farm position

  • GET /v1/wallets/{address}/stake - Get wallet's staking positions

  • GET /v1/wallets/{address}/operations - Get wallet's transaction history

  • GET /v1/wallets/{address}/transactions/last - Fetch the most recent transactions for a wallet

  • GET /v1/wallets/{address}/fee_vaults - List referral fee vaults for STON.fi DEX v2 for the given wallet (referrer × token pairs). DEX v1 pools do not use vaults, so v1 referral fees will not appear here.

Statistics

Protocol Statistics

  • GET /v1/stats/dex - Overall DEX statistics (TVL, volume, users, trades)

  • GET /v1/stats/pool - Pool statistics for time period

  • GET /v1/stats/stake - Staking statistics for time period

  • GET /v1/stats/operations - Trading operation statistics

Fee Statistics

  • GET /v1/stats/fees - Aggregated referral fee statistics (e.g. total accrued amount / USD value) for STON.fi DEX v1 and v2.

  • GET /v1/stats/fee_accruals - Detailed referral fee accrual history for STON.fi DEX v1 and v2. For v1 pools, accruals are paid immediately to the referrer (no vault), so there are no matching withdrawal events. For v2 pools, accruals represent deposits into referral fee vaults; the corresponding withdrawals are exposed via stats.fee_withdrawals.

  • GET /v1/stats/fee_withdrawals - Withdrawal operations from STON.fi DEX v2 referral fee vaults. Not applicable to v1.

Note: These endpoints only cover STON.fi DEX v1/v2 pools. Omniston routes that execute on external DEXes such as DeDust or Tonco are not yet exposed via the DEX stats API.

Export

Third-Party Integrations

  • GET /export/cmc/v1 - Export data in CoinMarketCap format

  • GET /export/dexscreener/v1/latest-block - Latest indexed block

  • GET /export/dexscreener/v1/asset/{address} - Asset info for DexScreener

  • GET /export/dexscreener/v1/pair/{address} - Pool info for DexScreener

  • GET /export/dexscreener/v1/events - Event stream for block range

Common Parameters

Query Parameters

  • Time ranges: Use format YYYY-MM-DDTHH:MM:SS

  • Addresses: TON blockchain addresses (e.g., EQBynBO23ywHy_CgarY9NK9FTz0yDsG82PtcbSTQgGoXwiuA)

  • Amounts: String values in smallest units (1 TON = "1000000000")

  • Slippage: Decimal values (0.001 = 0.1%)

Filters

  • dex_v2: Boolean to filter V2 pools/routers (default: true)

  • only_active: Show only active farms

  • op_type: Filter operations by type (swap, provide_liquidity, etc.)

Rate Limits

Currently, there are no rate limits for the DEX API.

SDK

For easier integration, use our TypeScript SDK:

Support

For the most up-to-date information about parameters, response formats, and new endpoints, always refer to our Swagger UI or Redoc.

PreviousREST APINextFarm

Last updated