### 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 and Instantiate StonApiClient

Source: https://context7.com/ston-fi/api/llms.txt

Install the package using npm, yarn, or pnpm. Instantiate StonApiClient with an optional custom base URL for testing or proxying.

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

// Zero-config (defaults to https://api.ston.fi)
const client = new StonApiClient();

// Custom base URL (e.g. for testing or proxy)
const customClient = new StonApiClient({ baseURL: "https://my-proxy.example.com" });
```

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

### 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();
```

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

### StonApiClient Initialization

Source: https://context7.com/ston-fi/api/llms.txt

Demonstrates how to install the package and instantiate the StonApiClient with default or custom base URLs.

```APIDOC
## Installation and Client Setup

Install the package and instantiate `StonApiClient` with optional base URL override.

```ts
// npm install @ston-fi/api  |  yarn add @ston-fi/api  |  pnpm add @ston-fi/api

import {
  StonApiClient,
  AssetTag,
  AssetKind,
  LiquidityProvisionType,
  OperationType,
  StakeNftStatus,
} from "@ston-fi/api";

// Zero-config (defaults to https://api.ston.fi)
const client = new StonApiClient();

// Custom base URL (e.g. for testing or proxy)
const customClient = new StonApiClient({ baseURL: "https://my-proxy.example.com" });
```
```

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

### 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.
```

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

### 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 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 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 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.
```

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

### 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.
```

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

### 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",
});
```

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

### 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...",
});
```

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

### 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 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 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 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 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 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...",
});
```

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

### Get All DEX Assets with StonApiClient

Source: https://context7.com/ston-fi/api/llms.txt

Retrieve the complete list of assets on the Ston.fi DEX. Filter results to include only specific types like Jettons or find assets by symbol. The 'tags' property provides categorization, and 'dexPriceUsd' offers the current price.

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

const client = new StonApiClient();

const assets = await client.getAssets();

// Filter to only real jettons (not TON/wTON wrappers)
const jettons = assets.filter((a) => a.kind === AssetKind.Jetton);

// Find USDT by symbol
const usdt = assets.find((a) => a.symbol === "USD₮");
console.log(usdt?.contractAddress);  // EQ...
console.log(usdt?.dexPriceUsd);      // "1.0001"
console.log(usdt?.tags);             // ["asset:essential", "asset:popular", ...]
```

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

### 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.
```

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

### 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 Swap Pairs

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

Retrieves a list of tuples with all possible swap pairs on the DEX.

```APIDOC
## Get Swap Pairs

### Description
Retrieves a list of tuples with all possible swap pairs on the DEX.

### Method
`client.getSwapPairs()`

### Parameters
None

### Response
- **pairs** (array) - A list of swap pair objects.
```

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

### 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...");
```

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

### 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.
```

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

### 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...");
```

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

### 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...");
```

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

### Get Pools by Asset Pair

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

Retrieves a list of pools with the given asset pair.

```APIDOC
## Get Pools by Asset Pair

### Description
Retrieves a list of pools with the given asset pair.

### Method
`client.getPoolsByAssetPair(params: { asset0Address: string, asset1Address: string })`

### Parameters
#### Query Parameters
- **asset0Address** (string) - Required - The address of the first asset in the pair.
- **asset1Address** (string) - Required - The address of the second asset in the pair.
```

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

### Get Wallet Asset Balances with StonApiClient

Source: https://context7.com/ston-fi/api/llms.txt

Retrieve all assets and their balances for a given wallet address, or fetch the balance for a single specified asset within that wallet. The balance is returned in raw units.

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

const client = new StonApiClient();
const WALLET = "UQAQnxLqlX2B6w4jQzzzPWA8eyWZVZBz6Y0D_8noARLOaEAn";
const STON_ADDRESS = "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO";

// All assets in wallet
const allAssets = await client.getWalletAssets(WALLET);
const nonZero = allAssets.filter((a) => a.balance && BigInt(a.balance) > 0n);

// Single asset balance for wallet
const stonAsset = await client.getWalletAsset({
  walletAddress: WALLET,
  assetAddress: STON_ADDRESS,
});

console.log(stonAsset.symbol);  // "STON"
console.log(stonAsset.balance); // "1500000000"  (raw units)
```

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

### Get Wallet Stakes

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

Retrieves all wallet stake NFTs and a summary of stakes for a given wallet address.

```APIDOC
## Get Wallet Stakes

### Description
Retrieves all wallet stake NFTs and a summary of stakes for a given wallet address.

### Method
`client.getWalletStakes(params: { walletAddress: string })`

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

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

### 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();
```

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

### 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...");
```

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

### getAsset — Get Single Asset by Address

Source: https://context7.com/ston-fi/api/llms.txt

Fetches detailed metadata for a specific asset using its on-chain contract address.

```APIDOC
## `getAsset` — Get Single Asset by Address

Fetches metadata for one specific asset by its on-chain contract address.

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

const client = new StonApiClient();

const TON_ADDRESS = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";

const asset = await client.getAsset(TON_ADDRESS);

console.log(asset.symbol);        // "TON"
console.log(asset.kind);          // "Ton"
console.log(asset.decimals);      // 9
console.log(asset.dexPriceUsd);   // "5.42"
console.log(asset.popularityIndex); // 1000
```
```

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

### 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...");
```

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

### Fetch Wallet's Liquidity Pool Positions

Source: https://context7.com/ston-fi/api/llms.txt

Retrieve all pools where a specific wallet address has provided liquidity, or get the details for a single pool position. This helps users track their investments and earnings.

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

const client = new StonApiClient();
const WALLET = "UQAQnxLqlX2B6w4jQzzzPWA8eyWZVZBz6Y0D_8noARLOaEAn";

// All pools with wallet LP balance
const walletPools = await client.getWalletPools({
  walletAddress: WALLET,
  dexV2: true,
});
const activePools = walletPools.filter((p) => p.lpBalance && p.lpBalance !== "0");

// Single pool position
const position = await client.getWalletPool({
  walletAddress: WALLET,
  poolAddress: "EQC_-t0nCnmFEeKOxHbhbXXmGiGdMCHBPXqAM9MHLkiagK8",
});

console.log(position.lpBalance);        // wallet's LP token balance
console.log(position.lpWalletAddress);  // wallet's LP token jetton wallet address
```

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

### 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...");
```

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

### Get DEX Routers

Source: https://context7.com/ston-fi/api/llms.txt

Fetches metadata for all DEX routers (optionally including v2) or details for a specific router by its address. Useful for identifying router configurations.

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

const client = new StonApiClient();

// Get all routers including v2
const routers = await client.getRouters({ dexV2: true });

routers.forEach((r) => {
  console.log(r.address);
  console.log(r.majorVersion, r.minorVersion);  // e.g. 2, 1
  console.log(r.routerType);
  console.log(r.poolCreationEnabled);
});

// Single router details
const router = await client.getRouter("EQ...routerAddress");
console.log(router.ptonMasterAddress);
console.log(router.ptonVersion);
```

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

### Get Router by Address

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

Fetches a specific router's information using its unique address. Ensure the provided address is valid.

```typescript
const router = await client.getRouter("EQ...");
```

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

### Get Available Swap Pairs

Source: https://context7.com/ston-fi/api/llms.txt

Retrieves a list of all valid asset-pair combinations available for swapping on the DEX, including v2 pairs. Useful for checking tradeability.

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

const client = new StonApiClient();

const pairs = await client.getSwapPairs({ dexV2: true });

// pairs is Array<[string, string]> of address tuples
console.log(pairs.length);         // total number of tradeable pairs
console.log(pairs[0]);             // ["EQ...", "EQ..."]

// Check if a specific pair is tradeable
const TON  = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";
const USDT = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
const isTradeable = pairs.some(
  ([a, b]) => (a === TON && b === USDT) || (a === USDT && b === TON)
);
console.log(isTradeable); // true
```

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

### Get Referral Fee Statistics

Source: https://context7.com/ston-fi/api/llms.txt

Query referral fee accruals, withdrawals, and per-asset fee statistics for a referrer address over a specified time range. Requires setting up the StonApiClient with necessary date and referrer address parameters.

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

const client = new StonApiClient();
const REFERRER = "EQ...referrerAddress";
const since = new Date("2024-08-01T00:00:00Z");
const until = new Date("2024-08-31T23:59:59Z");

// Per-asset fee stats
const feeStats = await client.getAssetsFeeStats({ since, until, referrerAddress: REFERRER });
feeStats.assetsFeeStats.forEach((stat) => {
  console.log(stat.assetAddress, stat.accruedFeeUnits);
});

// Fee accruals per operation
const accruals = await client.getAccrualsFeeStats({ since, until, referrerAddress: REFERRER });
accruals.forEach((op) => {
  console.log(op.operationHash, op.feeUnits);
});

// Withdrawal history
const withdrawals = await client.getWithdrawalsFeeStats({ since, until, referrerAddress: REFERRER });
withdrawals.forEach((w) => {
  console.log(w.withdrawalHash, w.feeUnits);
});
```

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

### getAssets — Get All DEX Assets

Source: https://context7.com/ston-fi/api/llms.txt

Retrieves a comprehensive list of all assets available on the Ston.fi DEX, including metadata, pricing, liquidity information, and wallet balances.

```APIDOC
## `getAssets` — Get All DEX Assets

Returns the full list of all assets available on the Ston.fi DEX, each containing token metadata, price, liquidity tags, and optional wallet balance when not wallet-scoped.

```ts
import { StonApiClient, AssetKind } from "@ston-fi/api";

const client = new StonApiClient();

const assets = await client.getAssets();

// Filter to only real jettons (not TON/wTON wrappers)
const jettons = assets.filter((a) => a.kind === AssetKind.Jetton);

// Find USDT by symbol
const usdt = assets.find((a) => a.symbol === "USD₮");
console.log(usdt?.contractAddress);  // EQ...
console.log(usdt?.dexPriceUsd);      // "1.0001"
console.log(usdt?.tags);             // ["asset:essential", "asset:popular", ...]
```
```

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

### Fetch Yield Farms and Details

Source: https://context7.com/ston-fi/api/llms.txt

Retrieve all yield farming opportunities, specific farms, or farms associated with a particular pool. Use `getFarms` to get all farms (including v2 pool farms) and filter for active farms with APY. Use `getFarmsByPool` for farms of a specific pool and `getFarm` for details of a single farm.

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

const client = new StonApiClient();

// All farms (including v2 pool farms)
const farms = await client.getFarms({ dexV2: true });

// Active farms with APY
const activeFarms = farms.filter((f) => f.status === "active" && f.apy);
activeFarms.forEach((f) => {
  console.log(f.minterAddress);
  console.log(f.apy);               // APY string e.g. "0.3421" = 34.21%
  console.log(f.lockedTotalLp);
  console.log(f.lockedTotalLpUsd);
  f.rewards.forEach((r) => {
    console.log(r.rewardRate24h, r.remainingRewards);
  });
});

// Farms for a specific pool
const poolFarms = await client.getFarmsByPool("EQ...poolAddress");

// Single farm details
const farm = await client.getFarm("EQ...minterAddress");
console.log(farm.version);           // "3"
console.log(farm.minStakeDurationS); // minimum staking duration in seconds
```

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

### Get Single Asset by Address with StonApiClient

Source: https://context7.com/ston-fi/api/llms.txt

Fetch metadata for a specific asset using its contract address. Useful for retrieving details like symbol, kind, decimals, and price for a known token.

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

const client = new StonApiClient();

const TON_ADDRESS = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";

const asset = await client.getAsset(TON_ADDRESS);

console.log(asset.symbol);        // "TON"
console.log(asset.kind);          // "Ton"
console.log(asset.decimals);      // 9
console.log(asset.dexPriceUsd);   // "5.42"
console.log(asset.popularityIndex); // 1000
```

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

### Get Wallet Operations by Type and Period

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

Fetches operations for a specific wallet address within a given time frame. Optionally filter by operation type. Requires wallet address and date range; 'opType' is optional.

```javascript
const operations = await client.getWalletOperations({
  since: new Date("2024-06-01T12:00:00"),
  until: new Date("2024-08-06T21:00:00"),
  walletAddress: "UQ...",
  opType: OperationType.Swap, // optional; Only operations with the specified types. All operations if the opType is not specified
});
```

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

### 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.
```

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

### 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",
});
```

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

### 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();
```

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

### Simulate Reverse Swap (Buy Token)

Source: https://context7.com/ston-fi/api/llms.txt

Use this to calculate the required input amount for buying a specific quantity of a target token. Ensure correct token decimals are used for `askUnits`.

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

const client = new StonApiClient();

const TON  = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";
const USDT = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";

// Buy exactly 10 USDT, how much TON do I need?
const sim = await client.simulateReverseSwap({
  offerAddress: TON,
  askAddress: USDT,
  askUnits: "10000000",  // 10 USDT (6 decimals)
  slippageTolerance: "0.01", // 1% 
});

console.log(sim.offerUnits);     // TON units required to buy 10 USDT
console.log(sim.swapRate);       // exchange rate
console.log(sim.priceImpact);    // price impact fraction
```

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

### 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.
```

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

### `simulateLiquidityProvision` — Simulate Adding Liquidity

Source: https://context7.com/ston-fi/api/llms.txt

Simulates adding liquidity to a pool, supporting initial pool creation, balanced deposits, and arbitrary-ratio deposits.

```APIDOC
## `simulateLiquidityProvision` — Simulate Adding Liquidity

Simulate three types of liquidity provision: creating a new pool, balanced deposit to existing pool, or arbitrary-ratio deposit with internal swap.

### Method
POST (assumed, based on simulation nature)

### Endpoint
`/simulateLiquidityProvision`

### Parameters
#### Request Body
- **provisionType** (string) - Required - Type of liquidity provision: `Initial`, `Balanced`, or `Arbitrary`.
- **poolAddress** (string) - Optional - The address of the existing pool (required for `Balanced` and `Arbitrary` types).
- **tokenA** (string) - Required - Address of the first token in the pair.
- **tokenB** (string) - Required - Address of the second token in the pair.
- **tokenAUnits** (string) - Required - Amount of `tokenA` to provide, in its smallest units.
- **tokenBUnits** (string) - Optional - Amount of `tokenB` to provide, in its smallest units. Required to be "0" for single-sided `Arbitrary` deposits.
- **slippageTolerance** (string) - Required - The maximum acceptable price slippage, expressed as a fraction (e.g., "0.01" for 1%).

### Request Example (Initial Provision)
```ts
{
  "provisionType": "Initial",
  "tokenA": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
  "tokenB": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "tokenAUnits": "5000000000",
  "tokenBUnits": "25000000",
  "slippageTolerance": "0.01"
}
```

### Request Example (Balanced Provision)
```ts
{
  "provisionType": "Balanced",
  "poolAddress": "EQC_-t0nCnmFEeKOxHbhbXXmGiGdMCHBPXqAM9MHLkiagK8",
  "tokenA": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
  "tokenB": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "tokenAUnits": "1000000000",
  "slippageTolerance": "0.01"
}
```

### Request Example (Arbitrary Provision - Single Side)
```ts
{
  "provisionType": "Arbitrary",
  "poolAddress": "EQC_-t0nCnmFEeKOxHbhbXXmGiGdMCHBPXqAM9MHLkiagK8",
  "tokenA": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
  "tokenB": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "tokenAUnits": "2000000000",
  "tokenBUnits": "0",
  "slippageTolerance": "0.01"
}
```

### Response
#### Success Response (200)
- **estimatedLpUnits** (string) - The estimated amount of LP tokens to be minted.
- **tokenBUnits** (string) - (For Balanced/Arbitrary) The auto-calculated amount of `tokenB` needed.
- **priceImpact** (string) - The estimated price impact of the provision.
- **minLpUnits** (string) - (For Arbitrary) The minimum LP tokens guaranteed.
```

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

### 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.
```

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

### 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 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.
```

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

### simulateSwap

Source: https://context7.com/ston-fi/api/llms.txt

Simulate a direct swap of one token for another, returning expected output, fees, price impact, and gas parameters.

```APIDOC
## `simulateSwap` — Simulate a Direct Swap

Simulate selling a known amount of one token for another, returning the expected output, fees, price impact, gas parameters, and sandwich-resistant recommended values.

### Method
`client.simulateSwap(params: SimulateSwapParams): Promise<SimulateSwapResult>`

### Parameters
#### `SimulateSwapParams`
- **offerAddress** (string) - Required - The address of the token being offered.
- **offerUnits** (string) - Required - The amount of the offer token in raw units.
- **askAddress** (string) - Required - The address of the token being asked for.
- **slippageTolerance** (string) - Required - The maximum acceptable slippage (e.g., "0.005" for 0.5%).
- **dexV2** (boolean) - Optional - Use DEX v2 for simulation.

### Response
#### Success Response
- **SimulateSwapResult**: An object containing simulation details.
  - **askUnits** (string): Expected amount of the ask token.
  - **minAskUnits** (string): Minimum acceptable amount of the ask token with slippage.
  - **recommendedMinAskUnits** (string): Sandwich-safe minimum ask units.
  - **priceImpact** (string): The price impact of the swap.
  - **feeUnits** (string): The fee in offer token units.
  - **gasParams** (object): Gas parameters for the transaction.
    - **forwardGas** (string): TON gas required for forwarding.
  - **router** (object): Information about the router.
    - **address** (string): The address of the router.

### Request Example
```ts
const sim = await client.simulateSwap({
  offerAddress: TON,
  offerUnits: "1000000000",  // 1 TON in nanotons
  askAddress: STON,
  slippageTolerance: "0.005", // 0.5%
  dexV2: true,
});
```

### Response Example
```json
{
  "askUnits": "...",
  "minAskUnits": "...",
  "recommendedMinAskUnits": "...",
  "priceImpact": "0.0012",
  "feeUnits": "...",
  "gasParams": {
    "forwardGas": "..."
  },
  "router": {
    "address": "..."
  }
}
```
```

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

### 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.
```

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

### 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",
});
```

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

### 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.
```

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

### 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.
```

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

### 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.
```

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

### 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",
});
```

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

### Simulate Adding Liquidity

Source: https://context7.com/ston-fi/api/llms.txt

Simulates adding liquidity to a pool. Supports initial pool creation, balanced deposits to existing pools, and arbitrary-ratio deposits. `tokenBUnits` is auto-calculated for balanced deposits.

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

const client = new StonApiClient();
const TON  = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";
const USDT = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
const POOL = "EQC_-t0nCnmFEeKOxHbhbXXmGiGdMCHBPXqAM9MHLkiagK8";

// 1. Create a brand-new pool with initial liquidity
const newPool = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Initial,
  tokenA: TON,
  tokenB: USDT,
  tokenAUnits: "5000000000",  // 5 TON
  tokenBUnits: "25000000",    // 25 USDT
  slippageTolerance: "0.01",
});
console.log(newPool.estimatedLpUnits);  // LP tokens to be minted

// 2. Add to existing pool at current ratio (provide only tokenA amount)
const balanced = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Balanced,
  poolAddress: POOL,
  tokenA: TON,
  tokenB: USDT,
  tokenAUnits: "1000000000",  // 1 TON
  slippageTolerance: "0.01",
});
console.log(balanced.tokenBUnits);    // auto-calculated USDT needed
console.log(balanced.priceImpact);    // "0.0005"

// 3. Single-sided deposit (100% tokenA, 0 tokenB)
const singleSide = await client.simulateLiquidityProvision({
  provisionType: LiquidityProvisionType.Arbitrary,
  poolAddress: POOL,
  tokenA: TON,
  tokenB: USDT,
  tokenAUnits: "2000000000",
  tokenBUnits: "0",           // explicit zero required
  slippageTolerance: "0.01",
});
console.log(singleSide.estimatedLpUnits);
console.log(singleSide.minLpUnits);
```

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

### Simulate Single-Side Arbitrary Liquidity Provision

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

Simulates adding liquidity with a single token, effectively a 100:0 ratio, using the 'Arbitrary' provision type. Requires explicit zero value for the unused token.

```typescript
const arbitrarySinglesideLiquidityProvision =
  await client.simulateLiquidityProvision({
    provisionType: LiquidityProvisionType.Arbitrary,
    tokenA: "EQ...",
    tokenB: "EQ...",
    poolAddress: "EQ...",
    slippageTolerance: "0.001",
    tokenAUnits: "1000",
    tokenBUnits: "0", // require explicit zero value
  });
```

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

### `simulateReverseSwap` — Simulate a Reverse (Buy) Swap

Source: https://context7.com/ston-fi/api/llms.txt

Simulates buying a specific amount of a target token and calculates the required input amount. Useful for determining the cost of a trade before execution.

```APIDOC
## `simulateReverseSwap` — Simulate a Reverse (Buy) Swap

Simulate buying an exact amount of a target token, calculating the required input amount.

### Method
POST (assumed, based on simulation nature)

### Endpoint
`/simulateReverseSwap`

### Parameters
#### Request Body
- **offerAddress** (string) - Required - The address of the token you are offering (e.g., TON).
- **askAddress** (string) - Required - The address of the token you want to buy (e.g., USDT).
- **askUnits** (string) - Required - The exact amount of the ask token to buy, in its smallest units (e.g., "10000000" for 10 USDT with 6 decimals).
- **slippageTolerance** (string) - Required - The maximum acceptable price slippage, expressed as a fraction (e.g., "0.01" for 1%).

### Request Example
```ts
{
  "offerAddress": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
  "askAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
  "askUnits": "10000000",
  "slippageTolerance": "0.01"
}
```

### Response
#### Success Response (200)
- **offerUnits** (string) - The amount of the offer token required for the swap.
- **swapRate** (string) - The calculated exchange rate for the swap.
- **priceImpact** (string) - The estimated price impact of the swap as a fraction.
```

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

### Simulate Direct Swap

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

Simulates a direct swap between two assets (sell asset for another).

```APIDOC
## Simulate Direct Swap

### Description
Simulates a direct swap between two assets (sell asset for another).

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

### Parameters
#### Request Body
- **params** (object) - Required - An object containing swap simulation parameters. The exact fields depend on the simulation logic.
```

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

### Import Core API Enums

Source: https://context7.com/ston-fi/api/llms.txt

Import enums for filtering assets, categorizing asset kinds, specifying liquidity provision types, operation types, and stake NFT statuses.

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

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

### Simulate Direct Swap

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

Simulates a direct swap transaction, where one asset is sold for another. Requires detailed swap parameters.

```typescript
const swapDirectSimulation = await client.simulateSwap({
  /** */
});
```