Ston Fi API

https://github.com/ston-fi/api
Admin
Ston Fi API is a TypeScript client library for the Ston.fi decentralized exchange HTTP API, enabling...
Tokens:34,084
Snippets:357
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @ston-fi/api with NPM

Source: https://github.com/ston-fi/api/blob/main/README.md

Use this command to install the API client using NPM.

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

--------------------------------

### Install @ston-fi/api with Yarn

Source: https://github.com/ston-fi/api/blob/main/README.md

Use this command to install the API client using Yarn.

```bash
yarn add @ston-fi/api
```

--------------------------------

### Install @ston-fi/api with PNPM

Source: https://github.com/ston-fi/api/blob/main/README.md

Use this command to install the API client using PNPM.

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

--------------------------------

### Install STON.fi API package

Source: https://github.com/ston-fi/api/blob/main/_autodocs/README.md

Use your preferred package manager to install the STON.fi API client.

```bash
npm install @ston-fi/api
# or
yarn add @ston-fi/api
# or
pnpm add @ston-fi/api
```

--------------------------------

### Get Staking Statistics

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches general staking statistics. No specific setup or parameters are required beyond client initialization.

```javascript
const stakingStats = await client.getStakingStats();
```

--------------------------------

### Retrieve wallet vaults fee example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example usage of the getWalletVaultsFee method.

```typescript
const vaults = await client.getWalletVaultsFee({
  walletAddress: "UQA...",
});
vaults.forEach(vault => {
  console.log(`Vault: ${vault.vaultAddress}, Balance: ${vault.balance}`);
});
```

--------------------------------

### Retrieve jetton wallet address example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example usage of the getJettonWalletAddress method.

```typescript
const walletAddr = await client.getJettonWalletAddress({
  jettonAddress: "EQ...",
  ownerAddress: "UQA...",
});
console.log(`Jetton wallet: ${walletAddr}`);
```

--------------------------------

### Retrieve routers example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example usage of the getRouters method to list available routers.

```typescript
const routers = await client.getRouters();
routers.forEach(router => {
  console.log(`Router v${router.majorVersion}.${router.minorVersion}`);
});
```

--------------------------------

### GET /v1/wallets/{walletAddress}/farms/{farmAddress}

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Get wallet farm position.

```APIDOC
## GET /v1/wallets/{walletAddress}/farms/{farmAddress}

### Description
Get wallet farm position.

### Method
GET

### Endpoint
/v1/wallets/{walletAddress}/farms/{farmAddress}

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address
- **farmAddress** (string) - Required - The farm address

### Response
#### Success Response (200)
- **farm** (FarmInfoResponse) - Farm information
```

--------------------------------

### normalizeResponse usage example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/04-mappers.md

A complete example showing the transformation of a raw API response object.

```typescript
const rawResponse = {
  asset_list: [
    {
      contract_address: "EQBl3Z...",
      symbol: "STON",
      dex_price_usd: "0.05",
      wallet_address: null,
      balance: "1000000"
    }
  ]
}

const normalized = normalizeResponse(rawResponse)

// Result:
// {
//   assetList: [
//     {
//       contractAddress: "EQBl3Z...",
//       symbol: "STON",
//       dexPriceUsd: "0.05",
//       walletAddress: undefined,
//       balance: "1000000"
//     }
//   ]
// }
```

--------------------------------

### GET /v1/wallets/{walletAddress}/farms

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Get wallet farms with positions.

```APIDOC
## GET /v1/wallets/{walletAddress}/farms

### Description
Get wallet farms with positions.

### Method
GET

### Endpoint
/v1/wallets/{walletAddress}/farms

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address
#### Query Parameters
- **dexV2** (boolean) - Optional - Use dexV2 (default true)

### Response
#### Success Response (200)
- **farm_list** (FarmInfoResponse[]) - List of farms
```

--------------------------------

### Retrieve single router example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example usage of the getRouter method to fetch details for a specific router address.

```typescript
const router = await client.getRouter("EQ...");
console.log(`Router enabled for pool creation: ${router.poolCreationEnabled}`);
```

--------------------------------

### GET /v1/wallets/{walletAddress}/pools

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Get wallet pools with LP balances.

```APIDOC
## GET /v1/wallets/{walletAddress}/pools

### Description
Get wallet pools with LP balances.

### Method
GET

### Endpoint
/v1/wallets/{walletAddress}/pools

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address
#### Query Parameters
- **dexV2** (boolean) - Optional - Use dexV2 (default true)

### Response
#### Success Response (200)
- **pool_list** (PoolInfoResponse[]) - List of pools
```

--------------------------------

### Set API Base URL environments

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Examples of configuring the client for specific environments or through a proxy.

```typescript
const client = new StonApiClient({
  baseURL: "https://api.ston.fi", // Default
});
```

```typescript
const stagingClient = new StonApiClient({
  baseURL: "https://staging-api.ston.fi",
});
```

```typescript
const devClient = new StonApiClient({
  baseURL: "http://localhost:3000",
});
```

```typescript
const proxiedClient = new StonApiClient({
  baseURL: "https://api-proxy.example.com/ston-fi",
});
```

--------------------------------

### Initialize Ston.fi API Client

Source: https://github.com/ston-fi/api/blob/main/_autodocs/06-usage-guide.md

Basic setup for the StonApiClient and initial data retrieval for assets and pools.

```typescript
import { StonApiClient, AssetTag } from "@ston-fi/api";

// Create client
const client = new StonApiClient();

// Get all assets
const assets = await client.getAssets();
console.log(`Total assets: ${assets.length}`);

// Get specific asset
const ston = await client.getAsset("EQBl3Z...");
console.log(`STON: ${ston.symbol}, Price: $${ston.dexPriceUsd}`);

// Get all pools
const pools = await client.getPools();
console.log(`Total pools: ${pools.length}`);
```

--------------------------------

### Get List of Routers

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all available routers on the DEX. No specific setup is required beyond having an initialized client.

```typescript
const routers = await client.getRouters();
```

--------------------------------

### GET /v1/assets

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves a list of all available assets.

```APIDOC
## GET /v1/assets

### Description
Get all available assets.

### Method
GET

### Endpoint
/v1/assets

### Response
#### Success Response (200)
- **asset_list** (AssetInfoResponse[]) - A list of all available assets.
```

--------------------------------

### GET /v1/markets

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves all available swap pairs.

```APIDOC
## GET /v1/markets

### Description
Get all swap pairs.

### Method
GET

### Endpoint
/v1/markets

### Parameters
#### Query Parameters
- **dexV2** (boolean) - Optional - default true
```

--------------------------------

### Query transactions example

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example usage of the queryTransactions method showing both query patterns.

```typescript
// Query by wallet address and query ID
const tx = await client.queryTransactions({
  walletAddress: "UQA...",
  queryId: 12345,
});

// Query by external message hash
const tx = await client.queryTransactions({
  extMsgHash: "abcd...",
  minTxTimestamp: new Date(Date.now() - 3600000),
});

if (tx.txId) {
  console.log(`Tx Hash: ${tx.txId.hash}`);
}
```

--------------------------------

### Get Assets

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX assets.

```APIDOC
## Get Assets

### Description
Retrieves a list of all DEX assets.

### Method
`client.getAssets()`

### Parameters
None

### Response
- **assets** (array) - A list of asset objects.
```

--------------------------------

### Usage example for normalizeRequest

Source: https://github.com/ston-fi/api/blob/main/_autodocs/04-mappers.md

Demonstrates basic usage of the normalizeRequest function.

```typescript
const [path, opts] = normalizeRequest("/v1/pools/{poolAddress}", {
  method: "GET",
  query: {
    poolAddress: "EQBl3Z...",
    dexV2: true
  }
})

// path: "/v1/pools/EQBl3Z%2E%2E%2E"
// opts.query: { dex_v2: true }
```

--------------------------------

### Define Environment Variables

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Example values for setting the STON_API_URL environment variable across different environments.

```bash
# Production
STON_API_URL=https://api.ston.fi

# Staging
STON_API_URL=https://staging-api.ston.fi

# Development
STON_API_URL=http://localhost:3000
```

--------------------------------

### GET /v1/farms

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves a list of all available farms.

```APIDOC
## GET /v1/farms

### Description
Get all farms.

### Method
GET

### Endpoint
/v1/farms

### Parameters
#### Query Parameters
- **dexV2** (boolean) - Optional - default true
```

--------------------------------

### GET /v1/pools

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves a list of all available liquidity pools.

```APIDOC
## GET /v1/pools

### Description
Get all pools.

### Method
GET

### Endpoint
/v1/pools

### Parameters
#### Query Parameters
- **dexV2** (boolean) - Optional - default true
```

--------------------------------

### Get Farms

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX farms.

```APIDOC
## Get Farms

### Description
Retrieves a list of all DEX farms.

### Method
`client.getFarms()`

### Parameters
None

### Response
- **farms** (array) - A list of farm objects.
```

--------------------------------

### Get Pools

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX pools.

```APIDOC
## Get Pools

### Description
Retrieves a list of all DEX pools.

### Method
`client.getPools()`

### Parameters
None

### Response
- **pools** (array) - A list of pool objects.
```

--------------------------------

### Get Routers

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all available routers on the DEX.

```APIDOC
## Get Routers

### Description
Retrieves a list of all available routers on the DEX.

### Method
`client.getRouters()`

### Parameters
None

### Response
- **routers** (array) - A list of router objects.
```

--------------------------------

### Usage of getWithdrawalsFeeStats

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example demonstrating how to call getWithdrawalsFeeStats and log withdrawal details.

```typescript
const withdrawals = await client.getWithdrawalsFeeStats({
  since: new Date("2024-08-01"),
  until: new Date("2024-08-31"),
  referrerAddress: "UQA...",
});

withdrawals.forEach(w => {
  console.log(`Withdrawn: ${w.amount} from vault ${w.vaultAddress}`);
});
```

--------------------------------

### Get Wallet Farm Info with Balance

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches information for a specific farm within a given wallet, including its balance. Requires both farm and wallet addresses.

```typescript
const walletFarm = await client.getWalletFarm({
  farmAddress: "EQ...",
  walletAddress: "UQ...",
});
```

--------------------------------

### Usage of getAssetsFeeStats

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Example demonstrating how to call getAssetsFeeStats and iterate over the returned asset statistics.

```typescript
const feeStats = await client.getAssetsFeeStats({
  since: new Date("2024-08-01"),
  until: new Date("2024-08-31"),
  referrerAddress: "UQA...",
});

feeStats.assetsFeeStats.forEach(stat => {
  console.log(`Asset: ${stat.assetAddress}, Accrued: ${stat.accrued}`);
});
```

--------------------------------

### Get Asset by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves information about a specific asset by its address.

```APIDOC
## Get Asset by Address

### Description
Retrieves information about a specific asset by its address.

### Method
`client.getAsset(address: string)`

### Parameters
#### Path Parameters
- **address** (string) - Required - The address of the asset.
```

--------------------------------

### Initialize and use StonApiClient

Source: https://github.com/ston-fi/api/blob/main/_autodocs/README.md

Demonstrates basic client initialization, asset querying, and simulation of swaps and liquidity provisions.

```typescript
import { StonApiClient, AssetTag, LiquidityProvisionType } from "@ston-fi/api";

const client = new StonApiClient();

// Get assets
const assets = await client.getAssets();

// Query with filters
const liquidAssets = await client.queryAssets({
  condition: `${AssetTag.LiquidityHigh} | ${AssetTag.LiquidityVeryHigh}`,
  limit: 50,
});

// Simulate swap
const swap = await client.simulateSwap({
  offerAddress: "EQ...",
  offerUnits: "1000000",
  askAddress: "EQ...",
  slippageTolerance: "0.01",
});

// Simulate liquidity provision
const lp = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Balanced,
  poolAddress: "EQ...",
  tokenA: "EQ...",
  tokenB: "EQ...",
  tokenAUnits: "1000000",
  slippageTolerance: "0.01",
});
```

--------------------------------

### Get Wallet Assets

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of DEX assets with balances for a given wallet.

```APIDOC
## Get Wallet Assets

### Description
Retrieves a list of DEX assets with balances for a given wallet.

### Method
`client.getWalletAssets(walletAddress: string)`

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### Get Wallet Stakes Summary

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a summary of all stake NFTs and staking information for a given wallet address. Requires the wallet's address.

```typescript
const walletStakes = await client.getWalletStakes({
  walletAddress: "UQAQnxLqlX2B6w4jQzzzPWA8eyWZVZBz6Y0D_8noARLOaEAn",
});
```

--------------------------------

### Configure StonApiClient

Source: https://github.com/ston-fi/api/blob/main/_autodocs/README.md

Shows how to initialize the client with default settings, a custom base URL, or environment variables.

```typescript
// Default (production)
const client = new StonApiClient();

// Custom base URL
const devClient = new StonApiClient({
  baseURL: "https://staging-api.ston.fi",
});

// Using environment variable
const client = new StonApiClient({
  baseURL: process.env.STON_API_URL || "https://api.ston.fi",
});
```

--------------------------------

### GET /v1/wallets/{walletAddress}/fee_vaults

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Get wallet fee vault balances.

```APIDOC
## GET /v1/wallets/{walletAddress}/fee_vaults

### Description
Get wallet fee vault balances.

### Method
GET

### Endpoint
/v1/wallets/{walletAddress}/fee_vaults

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The wallet address

### Response
#### Success Response (200)
- **vault_list** (VaultFeeInfo[]) - List of fee vaults
```

--------------------------------

### GET /v1/pools/{poolAddress}

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves details for a specific liquidity pool by its address.

```APIDOC
## GET /v1/pools/{poolAddress}

### Description
Get a single pool by address.

### Method
GET

### Endpoint
/v1/pools/{poolAddress}

### Parameters
#### Path Parameters
- **poolAddress** (string) - Required
```

--------------------------------

### Get Wallet Farms

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX farms with balances for a given wallet.

```APIDOC
## Get Wallet Farms

### Description
Retrieves a list of all DEX farms with balances for a given wallet.

### Method
`client.getWalletFarms(walletAddress: string)`

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### Get Wallet Asset

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves asset information with balance for a given wallet.

```APIDOC
## Get Wallet Asset

### Description
Retrieves asset information with balance for a given wallet.

### Method
`client.getWalletAsset(params: { assetAddress: string, walletAddress: string })`

### Parameters
#### Query Parameters
- **assetAddress** (string) - Required - The address of the asset.
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### Get Wallet Farm

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves farm information with balance for a given wallet.

```APIDOC
## Get Wallet Farm

### Description
Retrieves farm information with balance for a given wallet.

### Method
`client.getWalletFarm(params: { farmAddress: string, walletAddress: string })`

### Parameters
#### Query Parameters
- **farmAddress** (string) - Required - The address of the farm.
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### Get Wallet Asset Info with Balance

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches information for a specific asset within a given wallet, including its balance. Requires both asset and wallet addresses.

```typescript
const walletAsset = await client.getWalletAsset({
  assetAddress: "EQ...",
  walletAddress: "UQ...",
});
```

--------------------------------

### Get Wallet Pool Info with Balance

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches information for a specific pool within a given wallet, including its balance. Requires both pool and wallet addresses.

```typescript
const walletPool = await client.getWalletPool({
  poolAddress: "EQ...",
  walletAddress: "UQ...",
});
```

--------------------------------

### Configure StonApiClient with Environment Variables

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Demonstrates initializing the client using environment variables for dynamic base URL selection.

```typescript
// Example: Use environment variable for API URL
const client = new StonApiClient({
  baseURL: process.env.STON_API_URL || "https://api.ston.fi",
});

// Example: Use different URLs based on NODE_ENV
const client = new StonApiClient({
  baseURL: process.env.NODE_ENV === "production"
    ? "https://api.ston.fi"
    : "https://staging-api.ston.fi",
});
```

--------------------------------

### Get All Operations

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches a list of all operations performed on the platform within a specified time period.

```APIDOC
## getOperations

### Description
Gets a list of ALL operations during a specified period of time on the platform.

### Method
`client.getOperations(params)`

### Parameters
#### Query Parameters
- **since** (Date) - Required - The start of the period.
- **until** (Date) - Required - The end of the period.

### Request Example
```javascript
await client.getOperations({
  since: new Date("2024-08-05T12:00:00"),
  until: new Date("2024-08-06T21:00:00"),
});
```

### Response
(Details not provided in source)
```

--------------------------------

### Get Wallet Pools

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX pools with balances for a given wallet.

```APIDOC
## Get Wallet Pools

### Description
Retrieves a list of all DEX pools with balances for a given wallet.

### Method
`client.getWalletPools(walletAddress: string)`

### Parameters
#### Path Parameters
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### POST /v1/liquidity_provision/simulate

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Simulate liquidity provision in initial, balanced, or arbitrary modes.

```APIDOC
## POST /v1/liquidity_provision/simulate

### Description
Simulate liquidity provision in three modes: initial, balanced, or arbitrary.

### Method
POST

### Endpoint
/v1/liquidity_provision/simulate

### Parameters
#### Query Parameters
- **provisionType** (string) - Required - Mode of provision (Initial, Balanced, Arbitrary)
- **tokenA** (string) - Required - Address of token A
- **tokenB** (string) - Required - Address of token B
- **tokenAUnits** (string) - Required - Amount of token A
- **tokenBUnits** (string) - Optional - Amount of token B
- **slippageTolerance** (string) - Required - Slippage tolerance
- **walletAddress** (string) - Optional - Wallet address
- **poolAddress** (string) - Optional - Pool address (required for Balanced/Arbitrary modes)

### Response
#### Success Response (200)
- **LiquidityProvisionSimulationResponse** (object) - Simulation result
```

--------------------------------

### Get Swap Pairs

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all possible swap pairs available on the DEX. This is useful for understanding trading options.

```typescript
const pairs = await client.getSwapPairs();
```

--------------------------------

### Get Asset Info by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches detailed information for a specific asset using its address. Requires a valid asset address.

```typescript
const asset = await client.getAsset("EQ...");
```

--------------------------------

### Using Referral Links

Source: https://github.com/ston-fi/api/blob/main/_autodocs/06-usage-guide.md

Apply a referral address and fee basis points to a swap simulation.

```typescript
// Swap with referral fee
const referralSwap = await client.simulateSwap({
  offerAddress: "EQ...",
  offerUnits: "1000000",
  askAddress: "EQ...",
  slippageTolerance: "0.01",
  referralAddress: "UQreferral...", // Your referral wallet
  referralFeeBps: "50", // 0.5% referral fee (max 100 = 1%)
});
```

--------------------------------

### Get Wallet Farms with Balances

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX farms a specific wallet is participating in, including their balances. Requires the wallet's address.

```typescript
const walletFarms = await client.getWalletFarms("UQ...");
```

--------------------------------

### Simulate Initial Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates new pool creation with a ratio based on provided token amounts for initial liquidity provision.

```APIDOC
## Simulate Initial Liquidity Provision

### Description
Simulates new pool creation with a ratio based on provided token amounts for initial liquidity provision.

### Method
`client.simulateLiquidityProvision(params: { provisionType: 'Initial', slippageTolerance: string, tokenA: string, tokenB: string, tokenAUnits: string, tokenBUnits: string })`

### Parameters
#### Request Body
- **provisionType** (string) - Required - Must be 'Initial'.
- **slippageTolerance** (string) - Required - The maximum acceptable slippage.
- **tokenA** (string) - Required - The address of the first token.
- **tokenB** (string) - Required - The address of the second token.
- **tokenAUnits** (string) - Required - The amount of token A to provide.
- **tokenBUnits** (string) - Required - The amount of token B to provide.
```

--------------------------------

### Get Farm Info by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches detailed information for a specific farm using its address. Requires a valid farm address.

```typescript
const farm = await client.getFarm("EQ...");
```

--------------------------------

### simulateLiquidityProvision(query)

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Simulates liquidity provision in three modes: initial pool creation, balanced addition, or arbitrary ratio addition.

```APIDOC
## simulateLiquidityProvision(query)

### Description
Simulates liquidity provision in three modes: initial pool creation, balanced addition, or arbitrary ratio addition.

### Method
TypeScript SDK Method

### Parameters
- **query** (LiquidityProvisionSimulationQuery) - Required - The configuration object for the simulation, including provisionType, token addresses, units, and slippage tolerance.

### Returns
- **Promise<LiquidityProvisionSimulation>** - A promise resolving to the simulation results.

### Response Fields
- **provisionType** (LiquidityProvisionType) - Type of provision
- **poolAddress** (string) - Pool address
- **estimatedLpUnits** (string) - Expected LP tokens to receive
- **minLpUnits** (string) - Minimum LP tokens with slippage
- **priceImpact** (string) - Impact on pool price
```

--------------------------------

### Create Initial Liquidity Pool

Source: https://github.com/ston-fi/api/blob/main/_autodocs/06-usage-guide.md

Initializes a new pool with a specific token ratio. Requires defining both token units and the provision type as 'Initial'.

```typescript
// Create new pool with ratio 1:2 (USDT:STON)
const initialLp = await client.simulateLiquidityProvision({
  provisionType: "Initial",
  tokenA: "EQ9EQj...", // USDT
  tokenB: "EQBl3Z...", // STON
  tokenAUnits: "1000000", // 1 USDT
  tokenBUnits: "2000000000", // 2 STON
  slippageTolerance: "0.01",
});

console.log(`LP Tokens: ${initialLp.estimatedLpUnits}`);
console.log(`Min LP Tokens: ${initialLp.minLpUnits}`);
```

--------------------------------

### Get List of DEX Assets

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves all available assets listed on the DEX. This is a foundational call for asset-related operations.

```typescript
const assets = await client.getAssets();
```

--------------------------------

### Initialize HTTP Client with ofetch

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Shows the internal implementation of the StonApiClient constructor using ofetch for HTTP requests.

```typescript
export class StonApiClient {
  private readonly apiFetch;

  constructor(options?: StonApiClientOptions) {
    this.apiFetch = ofetch.create({
      baseURL: options?.baseURL ?? options?.baseUrl ?? "https://api.ston.fi",
    });
  }
}
```

--------------------------------

### Get Wallet Assets with Balances

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX assets held in a specific wallet, including their balances. Requires the wallet's address.

```typescript
const walletAssets = await client.getWalletAssets("UQ...");
```

--------------------------------

### Get Swap Status

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Queries the current state of a swap transaction using its unique identifier.

```typescript
public async getSwapStatus(query: {
  routerAddress: string;
  ownerAddress: string;
  queryId: string;
})
```

```typescript
const status = await client.getSwapStatus({
  routerAddress: "EQ...",
  ownerAddress: "UQA...",
  queryId: "12345",
});

if (status["@type"] === "Found") {
  console.log(`Tx Hash: ${status.txHash}`);
  console.log(`Exit code: ${status.exitCode}`);
} else {
  console.log("Swap not found");
}
```

--------------------------------

### Get Wallet Pools with Balances

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX pools a specific wallet is participating in, including their balances. Requires the wallet's address.

```typescript
const walletPools = await client.getWalletPools("UQ...");
```

--------------------------------

### Simulate Initial Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates the creation of a new liquidity pool with initial token amounts and a specified slippage tolerance. Requires addresses and amounts for both tokens.

```typescript
const initialLiquidityProvision = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Initial,
  slippageTolerance: "0.001",
  tokenA: "EQ...",
  tokenB: "EQ...",
  tokenAUnits: "1000",
  tokenBUnits: "1000",
});
```

--------------------------------

### Get Pool Info by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Fetches detailed information for a specific pool using its address. Requires a valid pool address.

```typescript
const pool = await client.getPool("EQ...");
```

--------------------------------

### Initialize StonApiClient

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Shows the constructor signature for the API client.

```typescript
constructor(options?: StonApiClientOptions)
```

--------------------------------

### POST /v1/swap/simulate

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Simulates a direct swap operation.

```APIDOC
## POST /v1/swap/simulate

### Description
Simulate a direct swap (sell token A for token B).

### Method
POST

### Endpoint
/v1/swap/simulate

### Parameters
#### Query Parameters
- **offerAddress** (string) - Required
- **offerUnits** (string) - Required
- **askAddress** (string) - Required
- **slippageTolerance** (string) - Required
- **referralAddress** (string) - Optional
- **referralFeeBps** (string) - Optional
- **dexV2** (boolean) - Optional
- **dexVersion** (Array) - Optional
- **poolAddress** (string) - Optional
```

--------------------------------

### simulateSwap(query)

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Simulates a direct swap (sell token A for token B) and returns expected output with slippage.

```APIDOC
## simulateSwap(query)

### Description
Simulates a direct swap (sell token A for token B) and returns expected output with slippage.

### Parameters
#### Query Parameters
- **offerAddress** (string) - Required - Address of token to sell
- **offerUnits** (string) - Required - Amount of units to sell
- **askAddress** (string) - Required - Address of token to buy
- **slippageTolerance** (string) - Required - Max slippage as fraction (e.g., "0.01" for 1%)
- **referralAddress** (string) - Optional - Referral wallet address
- **referralFeeBps** (string) - Optional - Referral fee in basis points (0-100)
- **dexV2** (boolean) - Optional - Allow V2 pool selection (Default: true)
- **dexVersion** (Array<"1" | 1 | "2" | 2>) - Optional - Restrict to specific DEX version(s)
- **poolAddress** (string) - Optional - Force specific pool address

### Response
- **Returns** (Promise<SwapSimulation>) - The simulation result containing output units, fees, and price impact.
```

--------------------------------

### Instantiate StonApiClient

Source: https://github.com/ston-fi/api/blob/main/README.md

Import and create a new instance of the StonApiClient. No configuration is required for basic usage.

```typescript
import { StonApiClient } from "@ston-fi/api";

const client = new StonApiClient();
```

--------------------------------

### Get Router by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a specific router by its address.

```APIDOC
## Get Router by Address

### Description
Retrieves a specific router by its address.

### Method
`client.getRouter(address: string)`

### Parameters
#### Path Parameters
- **address** (string) - Required - The address of the router.
```

--------------------------------

### simulateReverseSwap(query)

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

Simulates a reverse swap (buy token B with amount of token A) and calculates required input.

```APIDOC
## simulateReverseSwap(query)

### Description
Simulates a reverse swap (buy token B with amount of token A) and calculates required input.

### Parameters
#### Query Parameters
- **offerAddress** (string) - Required - Address of token to sell
- **askAddress** (string) - Required - Address of token to buy
- **askUnits** (string) - Required - Amount of units to buy
- **slippageTolerance** (string) - Required - Max slippage as fraction
- **referralAddress** (string) - Optional - Referral wallet address
- **referralFeeBps** (string) - Optional - Referral fee in basis points
- **dexV2** (boolean) - Optional - Allow V2 pool selection (Default: true)
- **dexVersion** (Array<"1" | 1 | "2" | 2>) - Optional - Restrict to specific DEX version
- **poolAddress** (string) - Optional - Force specific pool address

### Response
- **Returns** (Promise<SwapSimulation>) - The simulation result containing required input units.
```

--------------------------------

### POST /v1/reverse_swap/simulate

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Simulates a reverse swap operation to buy an exact amount of a token.

```APIDOC
## POST /v1/reverse_swap/simulate

### Description
Simulate a reverse swap (buy exact token B amount).

### Method
POST

### Endpoint
/v1/reverse_swap/simulate

### Parameters
#### Query Parameters
- **offerAddress** (string) - Required
- **askAddress** (string) - Required
- **askUnits** (string) - Required
- **slippageTolerance** (string) - Required
- **referralAddress** (string) - Optional
- **referralFeeBps** (string) - Optional
- **dexV2** (boolean) - Optional
- **dexVersion** (Array) - Optional
- **poolAddress** (string) - Optional
```

--------------------------------

### Simulate Arbitrary Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates adding liquidity with an arbitrary ratio. During provisioning, funds will be swapped to match the required pool ratio.

```APIDOC
## Simulate Arbitrary Liquidity Provision

### Description
Simulates adding liquidity with an arbitrary ratio. During provisioning, funds will be swapped to match the required pool ratio.

### Method
`client.simulateLiquidityProvision(params: { provisionType: 'Arbitrary', poolAddress?: string, slippageTolerance: string, tokenA: string, tokenB: string, tokenAUnits: string, tokenBUnits: string })`

### Parameters
#### Request Body
- **provisionType** (string) - Required - Must be 'Arbitrary'.
- **poolAddress** (string) - Optional - The address of the pool. If not provided, a new pool will be simulated.
- **slippageTolerance** (string) - Required - The maximum acceptable slippage.
- **tokenA** (string) - Required - The address of token A.
- **tokenB** (string) - Required - The address of token B.
- **tokenAUnits** (string) - Required - The amount of token A to provide.
- **tokenBUnits** (string) - Required - The amount of token B to provide.
```

--------------------------------

### GET /v1/stats/fee_accruals

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves fee accruals from operations for a specific referrer.

```APIDOC
## GET /v1/stats/fee_accruals

### Description
Get fee accruals from operations for referrer.

### Method
GET

### Endpoint
/v1/stats/fee_accruals

### Parameters
#### Query Parameters
- **since** (string) - Optional - Start of time range
- **until** (string) - Optional - End of time range
- **referrerAddress** (string) - Optional - Referrer address

### Response
#### Success Response (200)
- **operations** (OperationFeeStat[]) - List of fee accruals
```

--------------------------------

### GET /v1/stats/fee_withdrawals

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves fee withdrawal history for a specific referrer.

```APIDOC
## GET /v1/stats/fee_withdrawals

### Description
Get fee withdrawal history for referrer.

### Method
GET

### Endpoint
/v1/stats/fee_withdrawals

### Parameters
#### Query Parameters
- **since** (string) - Optional - Start of time range
- **until** (string) - Optional - End of time range
- **referrerAddress** (string) - Optional - Referrer address

### Response
#### Success Response (200)
- **withdrawals** (WithdrawalFeeStat[]) - List of fee withdrawals
```

--------------------------------

### Instantiate StonApiClient with Options

Source: https://github.com/ston-fi/api/blob/main/README.md

Create a new instance of StonApiClient, providing an optional configuration object of type StonApiClientOptions.

```typescript
import { StonApiClient, StonApiClientOptions } from "@ston-fi/api";

const client = new StonApiClient({ /* options */ });
```

--------------------------------

### GET /v1/stats/fees

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves accrued fees by asset for a specific referrer.

```APIDOC
## GET /v1/stats/fees

### Description
Get accrued fees by asset for referrer.

### Method
GET

### Endpoint
/v1/stats/fees

### Parameters
#### Query Parameters
- **since** (string) - Optional - Start of time range
- **until** (string) - Optional - End of time range
- **referrerAddress** (string) - Optional - Referrer address

### Response
#### Success Response (200)
- **data** (AssetsFeeStatsResponse) - Accrued fees by asset
```

--------------------------------

### Get Staking Statistics

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves the overall staking statistics for the platform.

```APIDOC
## getStakingStats

### Description
Retrieves the overall staking statistics for the platform.

### Method
`client.getStakingStats()`

### Parameters
None

### Response
(Details not provided in source)
```

--------------------------------

### Get Staking Stats

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves global statistics about the Ston.fi staking.

```APIDOC
## Get Staking Stats

### Description
Retrieves global statistics about the Ston.fi staking.

### Method
`client.getStakingStats()`

### Parameters
None

### Response
- **stats** (object) - An object containing global staking statistics.
```

--------------------------------

### Configure Swap Parameters

Source: https://github.com/ston-fi/api/blob/main/_autodocs/05-configuration.md

Lists parameters required for executing swaps and setting slippage tolerance.

```typescript
offerAddress: string;      // Token to sell
offerUnits: string;        // Amount to sell (in token base units)
askAddress: string;        // Token to buy
askUnits: string;          // Amount to buy (in token base units) [reverse swap only]
slippageTolerance: string; // Max acceptable slippage (e.g., "0.01" for 1%)
referralAddress?: string;  // Referral wallet address
referralFeeBps?: string;   // Referral fee in basis points (0-100)
dexV2?: boolean;           // Include V2 pools (default: true)
dexVersion?: Array<"1" | 1 | "2" | 2>; // Restrict to specific DEX version
poolAddress?: string;      // Force specific pool
```

```typescript
// 0.1% slippage (conservative, recommended minimum)
slippageTolerance: "0.001"

// 1% slippage (typical)
slippageTolerance: "0.01"

// 5% slippage (aggressive, only for volatile pairs)
slippageTolerance: "0.05"
```

--------------------------------

### Get Farm by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves information about a specific farm by its address.

```APIDOC
## Get Farm by Address

### Description
Retrieves information about a specific farm by its address.

### Method
`client.getFarm(address: string)`

### Parameters
#### Path Parameters
- **address** (string) - Required - The address of the farm.
```

--------------------------------

### Get Pool by Address

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves information about a specific pool by its address.

```APIDOC
## Get Pool by Address

### Description
Retrieves information about a specific pool by its address.

### Method
`client.getPool(address: string)`

### Parameters
#### Path Parameters
- **address** (string) - Required - The address of the pool.
```

--------------------------------

### Swap Methods

Source: https://github.com/ston-fi/api/blob/main/_autodocs/INDEX.md

Methods for simulating swaps and checking swap status.

```APIDOC
## Swap Methods

- `simulateSwap(query)`: Simulates a direct swap.
- `simulateReverseSwap(query)`: Simulates a reverse swap.
- `getSwapStatus(query)`: Retrieves the status of a swap operation.
- `getSwapPairs(query?)`: Retrieves available swap pairs.
```

--------------------------------

### GET /v1/stats/operations

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves platform operations within a specified time range.

```APIDOC
## GET /v1/stats/operations

### Description
Get platform operations in time range.

### Method
GET

### Endpoint
/v1/stats/operations

### Parameters
#### Query Parameters
- **since** (ISO date) - Optional - Start of time range
- **until** (ISO date) - Optional - End of time range

### Response
#### Success Response (200)
- **operations** (OperationInfoResponse[]) - List of platform operations
```

--------------------------------

### GET /v1/farms_by_pool/{poolAddress}

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves all farms associated with a specific pool address.

```APIDOC
## GET /v1/farms_by_pool/{poolAddress}

### Description
Get all farms for a pool.

### Method
GET

### Endpoint
/v1/farms_by_pool/{poolAddress}

### Parameters
#### Path Parameters
- **poolAddress** (string) - Required
```

--------------------------------

### Fetch Assets and Wallet Balances

Source: https://github.com/ston-fi/api/blob/main/_autodocs/06-usage-guide.md

Methods for retrieving general asset information or specific wallet-related asset data.

```typescript
// Get all assets
const allAssets = await client.getAssets();

// Get specific asset
const asset = await client.getAsset("EQBl3Z...");

// Get assets with wallet balances
const walletAssets = await client.getWalletAssets("UQA...");
walletAssets.forEach(asset => {
  console.log(`${asset.symbol}: ${asset.balance}`);
});

// Get single asset with wallet balance
const walletAsset = await client.getWalletAsset({
  walletAddress: "UQA...",
  assetAddress: "EQBl3Z...",
});
```

--------------------------------

### Get Swap Status

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves the status of a swap by its ID and additional information.

```APIDOC
## Get Swap Status

### Description
Retrieves the status of a swap by its ID and additional information.

### Method
`client.getSwapStatus(params: { ... })`

### Parameters
#### Request Body
- **params** (object) - Required - An object containing swap status query parameters, including swap ID and potentially wallet address.
```

--------------------------------

### Simulate Liquidity Provision Method Signature

Source: https://github.com/ston-fi/api/blob/main/_autodocs/01-api-client.md

The core method signature for simulating liquidity provision.

```typescript
public async simulateLiquidityProvision(query: LiquidityProvisionSimulationQuery)
```

--------------------------------

### Simulate Balanced Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates adding liquidity to an existing pool using a balanced ratio. Only one token amount is required; the other is calculated. Requires pool and token addresses.

```typescript
const balancedLiquidityProvision = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Balanced,
  poolAddress: "EQ...",
  slippageTolerance: "0.001",
  tokenA: "EQ...",
  tokenB: "EQ...",
  tokenAUnits: "1000",
});
```

--------------------------------

### Get Farms by Pool

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves a list of all DEX farms for a given pool.

```APIDOC
## Get Farms by Pool

### Description
Retrieves a list of all DEX farms for a given pool.

### Method
`client.getFarmsByPool(poolAddress: string)`

### Parameters
#### Path Parameters
- **poolAddress** (string) - Required - The address of the pool.
```

--------------------------------

### Define Liquidity Provision Simulation Parameters

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Query parameters for simulating liquidity provision in Initial, Balanced, or Arbitrary modes.

```typescript
provisionType: "Initial";
tokenA: string;
tokenB: string;
tokenAUnits: string;
tokenBUnits: string;
slippageTolerance: string;
walletAddress?: string;
```

```typescript
provisionType: "Balanced";
poolAddress: string;
tokenA: string;
tokenB: string;
tokenAUnits: string;  // OR tokenBUnits, one required
slippageTolerance: string;
walletAddress?: string;
```

```typescript
provisionType: "Arbitrary";
poolAddress: string;
tokenA: string;
tokenB: string;
tokenAUnits: string;
tokenBUnits: string;
slippageTolerance: string;
walletAddress?: string;
```

--------------------------------

### Get Wallet Pool

Source: https://github.com/ston-fi/api/blob/main/README.md

Retrieves pool information with balance for a given wallet.

```APIDOC
## Get Wallet Pool

### Description
Retrieves pool information with balance for a given wallet.

### Method
`client.getWalletPool(params: { poolAddress: string, walletAddress: string })`

### Parameters
#### Query Parameters
- **poolAddress** (string) - Required - The address of the pool.
- **walletAddress** (string) - Required - The address of the wallet.
```

--------------------------------

### Simulate Balanced Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates adding liquidity to an existing pool at the current pool ratio. Only one amount is required; the corresponding second amount will be calculated.

```APIDOC
## Simulate Balanced Liquidity Provision

### Description
Simulates adding liquidity to an existing pool at the current pool ratio. Only one amount is required; the corresponding second amount will be calculated.

### Method
`client.simulateLiquidityProvision(params: { provisionType: 'Balanced', poolAddress: string, slippageTolerance: string, tokenA: string, tokenB: string, tokenAUnits?: string, tokenBUnits?: string })`

### Parameters
#### Request Body
- **provisionType** (string) - Required - Must be 'Balanced'.
- **poolAddress** (string) - Required - The address of the pool.
- **slippageTolerance** (string) - Required - The maximum acceptable slippage.
- **tokenA** (string) - Required - The address of token A.
- **tokenB** (string) - Required - The address of token B.
- **tokenAUnits** (string) - Optional - The amount of token A to provide. If not provided, token B units must be provided and token A will be calculated.
- **tokenBUnits** (string) - Optional - The amount of token B to provide. If not provided, token A units must be provided and token B will be calculated.
```

--------------------------------

### Simulate Arbitrary Liquidity Provision

Source: https://github.com/ston-fi/api/blob/main/README.md

Simulates adding liquidity to an existing pool with an arbitrary ratio. Tokens will be swapped to match the pool's required ratio. Requires pool and token addresses.

```typescript
const arbitraryLiquidityProvision = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Arbitrary,
  poolAddress: "EQ...",
  slippageTolerance: "0.001",
  tokenA: "EQ...",
  tokenB: "EQ...",
  tokenAUnits: "1000",
  tokenBUnits: "2000",
});
```

--------------------------------

### GET /v1/jetton/{jettonAddress}/address

Source: https://github.com/ston-fi/api/blob/main/_autodocs/03-endpoints.md

Retrieves the jetton wallet address for a specific owner.

```APIDOC
## GET /v1/jetton/{jettonAddress}/address

### Description
Get jetton wallet address for owner.

### Method
GET

### Endpoint
/v1/jetton/{jettonAddress}/address

### Parameters
#### Query Parameters
- **jettonAddress** (string) - Required
- **ownerAddress** (string) - Required
```

--------------------------------

### Swap Simulations

Source: https://github.com/ston-fi/api/blob/main/_autodocs/06-usage-guide.md

Methods for simulating standard and reverse swaps, including support for referral fees and specific pool/DEX version selection.

```APIDOC
## client.simulateSwap(params)
### Description
Simulates a swap operation between two assets. Supports slippage tolerance, referral addresses, referral fees, specific pool selection, and DEX version forcing.

## client.simulateReverseSwap(params)
### Description
Calculates the required input amount to receive a specific output amount of an asset.
```

--------------------------------

### Query Assets with Wallet Context

Source: https://github.com/ston-fi/api/blob/main/_autodocs/INDEX.md

Filter assets based on wallet balance by providing the wallet address.

```typescript
await client.queryAssets({
  condition: "asset:wallet_has_balance",
  walletAddress: "UQA...",
});
```
Tokens:
Raw