# API Reference

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

{% hint style="info" %}
For detailed parameters, request/response schemas, and interactive testing, browse our [Swagger UI](https://api.ston.fi/swagger-ui/) or [Redoc](https://api.ston.fi/redoc) viewers.
{% endhint %}

**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) over a time period.
* `GET /v1/stats/fee_accruals` - Detailed referral fee accrual history for **STON.fi DEX v2 referral fee vaults**. This endpoint is built from vault operations (filtered by owner and time range), so it does **not** include DEX v1 referral fees paid directly to wallet addresses.
* `GET /v1/stats/fee_withdrawals` - Withdrawal operations from **STON.fi DEX v2** referral fee vaults. DEX v1 does not use vaults, so there are no v1 entries here.

> **Note:** These endpoints only cover referral activity on STON.fi DEX 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](https://github.com/ston-fi/api):

```bash
npm install @ston-fi/api
```

```typescript
import { DEX } from '@ston-fi/api';

const dex = new DEX();
const assets = await dex.getAssets();
```

## Support

For the most up-to-date information about parameters, response formats, and new endpoints, always refer to our [Swagger UI](https://api.ston.fi/swagger-ui/) or [Redoc](https://api.ston.fi/redoc).