STON.fi

https://docs.ston.fi/
Admin
STON.fi is a leading decentralized automated market maker (AMM) exchange on the TON blockchain...
Tokens:98,534
Snippets:863
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://docs.ston.fi/developer-section/quickstart/swap

Install project dependencies and start the Vite development server to view your React app. This command also verifies the setup.

```bash
pnpm install
pnpm dev
```

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

### Install project dependencies

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Install the required SDKs, UI libraries, and build tools for the project.

```bash
pnpm add @ston-fi/omniston-sdk-react @tonconnect/ui-react @ton/core @ston-fi/api
```

```bash
pnpm add tailwindcss @tailwindcss/vite
```

```bash
pnpm add vite-plugin-node-polyfills
```

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

### Install Omniston SDKs

Source: https://docs.ston.fi/developer-section/omniston/sdk

Installation commands for Node.js and React environments.

```bash
npm install @ston-fi/omniston-sdk
```

```bash
npm install @ston-fi/omniston-sdk-react
```

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

### Start Development Server

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Use this command to start the local development server for the React application.

```bash
pnpm dev
```

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

### Installation

Source: https://docs.ston.fi/developer-section/omniston/sdk/nodejs

Install the Omniston SDK using your preferred package manager.

```APIDOC
## Installation

### Via NPM

```sh
npm install @ston-fi/omniston-sdk
```

### Via YARN

```sh
yarn add @ston-fi/omniston-sdk
```

### Via PNPM

```sh
pnpm install @ston-fi/omniston-sdk
```
```

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

### Install STON.fi SDK

Source: https://docs.ston.fi/developer-section/dex/api/reference

Install the official TypeScript SDK via npm.

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

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

### Omniston SDK for React

Source: https://docs.ston.fi/developer-section

Getting started guide for integrating the Omniston SDK in React for building responsive DeFi interfaces with cross-DEX swapping.

```APIDOC
## Getting Started with Omniston SDK in React

### Description
This guide explains how to get started with the Omniston SDK in React, enabling the creation of responsive DeFi interfaces with cross-DEX swapping capabilities.

### Method
N/A (Integration Guide)

### Endpoint
`/developer-section/omniston/sdk/react.md`

### Parameters
N/A

### Request Example
(Refer to the guide for React code examples)

### Response
N/A
```

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

### Install Node.js SDK

Source: https://docs.ston.fi/developer-section/omniston/swap/overview

Install the Ston.fi Node.js SDK using npm. This is recommended for backend services or bots.

```bash
# Node.js
npm install @ston-fi/omniston-sdk
```

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

### Install React SDK

Source: https://docs.ston.fi/developer-section/omniston/swap/overview

Install the Ston.fi React SDK using npm. This is recommended for building frontend applications.

```bash
# React
npm install @ston-fi/omniston-sdk-react
```

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

### Complete SDK Migration Example

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v0.4-to-v0.5

This example demonstrates the complete migration to the latest STON.fi SDK, incorporating constructor updates, method renaming, and the use of the SDK-provided pTON address.

```typescript
import TonWeb from 'tonweb';
import { DEX, pTON } from '@ston-fi/sdk';

const router = new DEX.v1.Router({
  tonApiClient: new TonWeb.HttpProvider(),
});

const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
  offerAmount: new TonWeb.utils.BN('1000000000'),
  proxyTonAddress: pTON.v1.address,
  minAskAmount: new TonWeb.utils.BN('1'),
  queryId: 12345,
});
```

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

### pTON Operations with Router

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v0.5-to-v1

Example demonstrating how to use the `pTON.v1()` instance when getting swap transaction parameters for TON to Jetton. Ensure to replace placeholder values with actual addresses and amounts.

```typescript
import { TonClient } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";

const client = new TonClient({
  endpoint: "https://ton-api.ston.fi/jsonRPC",
});

const router = client.open(new DEX.v1.Router());

const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
    userWalletAddress: "", // ! replace with your address
    offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    offerAmount: BigInt("1000000000"),
    proxyTon: new pTON.v1(),
    minAskAmount: BigInt("1"),
    queryId: 12345,
  });
```

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

### Clone and Run Demo Locally

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Commands to clone the repository and start the local development server.

```bash
git clone https://github.com/mrruby/omniston-swap-app.git
cd omniston-swap-app
pnpm install
pnpm dev
```

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

### Install STON.fi and TonConnect Packages

Source: https://docs.ston.fi/developer-section/quickstart/swap

Install the required STON.fi SDK, API, and TonConnect UI packages for your React project.

```bash
pnpm add @ston-fi/sdk @ston-fi/api @tonconnect/ui-react
```

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

### Install Omniston SDK React via NPM

Source: https://docs.ston.fi/developer-section/omniston/sdk/react

Use this command to install the package using NPM.

```sh
npm install @ston-fi/omniston-sdk-react
```

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

### Install TON package

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Command to install the required @ton/ton package for trade tracking.

```bash
pnpm add @ton/ton
```

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

### Install Omniston SDK

Source: https://docs.ston.fi/developer-section/omniston/sdk/nodejs

Commands to install the package using common Node.js package managers.

```sh
npm install @ston-fi/omniston-sdk
```

```sh
yarn add @ston-fi/omniston-sdk
```

```sh
pnpm install @ston-fi/omniston-sdk
```

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

### Install Omniston SDK React via PNPM

Source: https://docs.ston.fi/developer-section/omniston/sdk/react

Use this command to install the package using PNPM.

```sh
pnpm install @ston-fi/omniston-sdk-react
```

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

### Install Omniston SDK React via YARN

Source: https://docs.ston.fi/developer-section/omniston/sdk/react

Use this command to install the package using YARN.

```sh
yarn add @ston-fi/omniston-sdk-react
```

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

### Install STON.fi and TonConnect Packages

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Installs the necessary STON.fi SDK, API, TonConnect UI, and TON library packages for your React project.

```bash
pnpm add @ston-fi/sdk @ston-fi/api @tonconnect/ui-react @ton/ton
```

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

### v2 Swap Jetton to Jetton Transaction Parameters with CPI Pool and Utilities

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v1-to-v2

This example shows how to get swap parameters in v2 for a CPI pool, explicitly specifying the pool type and using the `toUnits` utility function for amounts.

```typescript
// Specify pool type explicitly
const router = new DEX.v1.Router.CPI(routerAddress);
const params = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: wallet,
  offerJettonAddress: tokenA,
  askJettonAddress: tokenB,
  offerAmount: toUnits(1, 9), // Use utility function
  minAskAmount: toUnits(0.9, 9)
});
```

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

### Configure Widget Referral Settings

Source: https://docs.ston.fi/developer-section/widget/widget

Example configuration object for setting referral addresses and fees within the widget constructor.

```javascript
      'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
      'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO',
    ],
    referrerAddress: 'EQB_yourReferralWalletXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    referrerFeeBps: 50, // 0.5% within the documented referral range
  },
});
```

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

### Install pnpm

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Installs pnpm globally if not already present. Use any package manager (npm, yarn, pnpm, or bun) to set up your React project.

```bash
npm install -g pnpm
```

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

### Example Connection Request

Source: https://docs.ston.fi/developer-section/omniston/resolvers/guide

A sample JSON-formatted connection request for the gRPC API.

```json
{
  "connect": {
    "payload": "CPKnlt2xYxIwRVFDWFNzMnhaMmRoazlUQXh6R3pYcmEyRWJHX1MyU3F5TjhUZmk2Zko4MkVZaVZq",
    "public_key": "TAPsnPvWhlOvxEK19rONv4sueMeQzOzlrrIFUOKsi34=",
    "signature": "us7nMd9wmUOkuPk0otg6dvUojZwj8VcyXU6HD13BDQhVrzV8sKgyXtKze+9+j9FC1Ghxkx7Jo5FIDeE8ljbADQjyp5bdsWMSMEVRQ1hTczJ4WjJkaGs5VEF4ekd6WHJhMkViR19TMlNxeU44VGZpNmZKODJFWWlWag=="
  },
  "seqno": 1
}
```

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

### Initialize wallet and Omniston hooks

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Setup the wallet address and Omniston instance within the application component.

```tsx
function App() {  
  // ... existing state variables ...
  const walletAddress = useTonAddress();
  const [tonConnect] = useTonConnectUI();
  const omniston = useOmniston();
```

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

### Install STON.fi Widget Loader via pnpm

Source: https://docs.ston.fi/developer-section/widget/widget

Install the STON.fi widget loader package using pnpm. This package fetches the latest widget bundle at runtime.

```sh
pnpm add @ston-fi/omniston-widget-loader
```

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

### Retrieve Swap Status JSON-RPC Examples

Source: https://docs.ston.fi/developer-section/omniston/swap/overview

Examples of JSON-RPC responses for different stages of a swap operation, including awaiting transfer, transferring, and settled trade status.

```json
{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 4374307320472544,
    "result": {
      "status": {
        "awaiting_transfer": {}
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "transferring": {}
      }
    }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "trade_settled": {
          "result": 1,
          "routes": [
            {
              "steps": [
                {
                  "chunks": [
                    {
                      "target_address": {
                        "blockchain": 607,
                        "address": "EQACpXPHyLueReUMCmStesRXA77IK_ZAhHnLKAsQ5MjMUliK"
                      },
                      "bid_units": "1000000",
                      "expected_ask_units": "3379",
                      "actual_ask_units": "3378",
                      "result": 1,
                      "protocol": "StonFiV1",
                      "tx_hash": "97c06867d0e891369fa0f621e0b7d549c888af8f34e4bde6752d580c6da508c2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}
```

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

### Install Tailwind CSS and Vite Plugins

Source: https://docs.ston.fi/developer-section/quickstart/swap

Install Tailwind CSS, its Vite plugin, and the Node.js polyfills plugin for Vite. These are necessary for styling and Node.js API compatibility.

```bash
pnpm add tailwindcss @tailwindcss/vite
```

```bash
pnpm add vite-plugin-node-polyfills
```

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

### Install STON.fi Widget Loader via yarn

Source: https://docs.ston.fi/developer-section/widget/widget

Install the STON.fi widget loader package using yarn. This package fetches the latest widget bundle at runtime.

```sh
yarn add @ston-fi/omniston-widget-loader
```

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

### Install STON.fi Widget Loader via npm

Source: https://docs.ston.fi/developer-section/widget/widget

Install the STON.fi widget loader package using npm. This package fetches the latest widget bundle at runtime.

```sh
npm install @ston-fi/omniston-widget-loader
```

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

### How to Become an Omniston Resolver

Source: https://docs.ston.fi/developer-section

A step-by-step guide on how to integrate Omniston resolvers to implement smart routing for optimal swap execution.

```APIDOC
## How to Become an Omniston Resolver

### Description
This is a step-by-step guide for integrating Omniston resolvers. By following this guide, you can implement smart routing capabilities for optimal swap execution within the Omniston ecosystem.

### Method
N/A (Integration Guide)

### Endpoint
`/developer-section/omniston/resolvers/guide.md`

### Parameters
N/A

### Request Example
(Refer to the guide for integration steps and code examples)

### Response
N/A
```

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

### Create Project Directory and Navigate

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Use these bash commands to create a new project directory and navigate into it. Place the appropriate AI guide file (e.g., GEMINI.md, CLAUDE.md, AGENTS.md) in this directory.

```bash
mkdir my-omniston-app
cd my-omniston-app
# Place the renamed file here (GEMINI.md, CLAUDE.md, or AGENTS.md)
```

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

### Omniston SDK for Node.js

Source: https://docs.ston.fi/developer-section

Getting started guide for integrating the Omniston SDK in Node.js for server-side automated trading and bots.

```APIDOC
## Getting Started with Omniston SDK in Node.js

### Description
This guide covers getting started with the Omniston SDK in Node.js, focusing on server-side integration for automated trading and bot development.

### Method
N/A (Integration Guide)

### Endpoint
`/developer-section/omniston/sdk/nodejs.md`

### Parameters
N/A

### Request Example
(Refer to the guide for Node.js code examples)

### Response
N/A
```

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

### Omniston SDK React Integration

Source: https://docs.ston.fi/developer-section

Getting started with Omniston SDK in React for building responsive DeFi interfaces. Facilitates cross-DEX swapping.

```typescript
import { Omniswap } from "@ston-fi/omniston";
import { useTonConnectUI } from "@tonconnect/ui";
import { useState, useEffect } from "react";

function SwapComponent() {
    const [tonConnectUI, _] = useTonConnectUI();
    const [omniswap, setOmniswap] = useState<Omniswap | null>(null);
    const [fromToken, setFromToken] = useState("TON");
    const [toToken, setToToken] = useState("jUSDT");
    const [amount, setAmount] = useState("1000000"); // 1 TON in nano
    const [bestRoute, setBestRoute] = useState<any>(null);

    useEffect(() => {
        const instance = new Omniswap();
        setOmniswap(instance);
    }, []);

    useEffect(() => {
        if (omniswap) {
            omniswap.getBestRoute(fromToken, toToken, amount).then(setBestRoute);
        }
    }, [omniswap, fromToken, toToken, amount]);

    const handleSwap = async () => {
        if (!omniswap || !bestRoute) return;

        try {
            const result = await omniswap.swap(
                tonConnectUI,
                fromToken,
                toToken,
                amount,
                bestRoute
            );
            console.log("Swap result:", result);
        } catch (error) {
            console.error("Swap failed:", error);
        }
    };

    return (
        <div>
            {/* UI elements for token selection, amount input, etc. */}
            <button onClick={handleSwap} disabled={!bestRoute}>Swap</button>
        </div>
    );
}

export default SwapComponent;
```

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

### Omniston SDK Node.js Integration

Source: https://docs.ston.fi/developer-section

Getting started with Omniston SDK in Node.js for server-side integration. Enables automated trading and bot development.

```typescript
import { Omniswap } from "@ston-fi/omniston";

const omniswap = new Omniswap({
    // Optional: specify TON Center API endpoint
    // tonCenterApi: "https://toncenter.com/api/v2/jsonRPC",
    // Optional: specify TON Center API key
    // tonCenterApiKey: "YOUR_API_KEY",
});

async function main() {
    const fromToken = "TON";
    const toToken = "jUSDT";
    const amount = "1000000"; // 1 TON in nano

    const bestRoute = await omniswap.getBestRoute(fromToken, toToken, amount);

    console.log("Best route:", bestRoute);

    // To send a transaction, you need a sender (e.g., from TonConnect or TonWeb)
    // const sender = ...;
    // const result = await omniswap.swap(sender, fromToken, toToken, amount, bestRoute);
    // console.log("Swap result:", result);
}

main();
```

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

### Get Jetton to TON Swap Transaction Parameters (v1)

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v0.5-to-v1

Example of retrieving transaction parameters for a Jetton to TON swap using the updated SDK method `getSwapJettonToTonTxParams`.

```typescript
const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  offerAmount: BigInt('1000000000'),
  proxyTonAddress: pTON.v1.address,
  minAskAmount: BigInt('1'),
  queryId: 12345,
});
```

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

### v2 Pool Data Retrieval for CPI Pools

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v1-to-v2

In v2, you must specify the pool type when retrieving pool data. This example shows how to get data for a CPI pool.

```typescript
// Specify pool type
const pool = new DEX.v1.Pool.CPI(poolAddress);
const poolData = await pool.getPoolData();
```

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

### Run Gemini CLI

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Initiate the Gemini CLI tool from the project directory.

```bash
gemini
```

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

### Create React App with Vite

Source: https://docs.ston.fi/developer-section/quickstart/swap

Create a new React project using Vite. This command initializes a project with the React template.

```bash
pnpm create vite --template react
```

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

### Create React App with Vite

Source: https://docs.ston.fi/developer-section/quickstart/omniston

Initialize a new React project using Vite with TypeScript template. Navigate into the project directory afterwards.

```bash
pnpm create vite --template react-ts
```

```bash
cd omniston-swap-app
```

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

### Check pnpm Version

Source: https://docs.ston.fi/developer-section/quickstart/swap

Verify if pnpm is installed on your system. If not, install it globally using npm.

```bash
pnpm --version
```

```bash
npm install -g pnpm
```

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

### Initializing and Mounting the STON.fi Widget

Source: https://docs.ston.fi/developer-section/widget/widget

Configure and mount the STON.fi widget using its loader. This example demonstrates standalone TON Connect configuration with a manifest URL.

```typescript
import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();
const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://YOUR_APP_HOST/tonconnect-manifest.json',
    },
  },
});

widget.mount(document.querySelector("#omniston-widget-container"));
```

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

### POST /v1/swap/simulate

Source: https://docs.ston.fi/developer-section/dex/api/reference

Simulate a token swap before execution to calculate expected output, fees, and gas costs.

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

### Description
Simulate a token swap before execution. Calculates expected output, fees, and gas costs.

### Method
POST

### Endpoint
/v1/swap/simulate
```

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

### Main Command Entry Point

Source: https://docs.ston.fi/developer-section/quickstart/python

This is the main entry point for the Omniston Python CLI. It handles wallet initialization, balance checks, quote requests, and swap execution. Ensure your .env and swap_config.json are set up before running.

```python
MIN_INIT_BALANCE_TON = Decimal("0.25")

def main() -> None:
    load_env()
    config = load_config()

    print("Omniston Python Quickstart")
    print("==========================")

    wallet = ensure_wallet()
    print(f"Wallet: {wallet.address_bounceable}")

    balance = fetch_balance(wallet.address_hex) or Decimal("0")
    print(f"Balance: {format_amount(balance, 9)} TON")

    if balance < MIN_INIT_BALANCE_TON:
        need = format_amount(MIN_INIT_BALANCE_TON, 9)
        print(f"Please fund your wallet with at least {need} TON, then re-run this script.")
        print(f"Send TON to: {wallet.address_bounceable}")
        return

    if not ensure_wallet_deployed(wallet):
        return

    if not prompt_yes_no("Request a quote now?", default=True):
        print("Quote skipped.")
        return

    try:
        quote = request_quote(config, wallet)
    except Exception as exc:
        print(f"Quote request failed: {exc}")
        return

    received, summary = describe_quote(quote, config)
    if received <= Decimal("0"):
        print("Quote returned zero output; aborting.")
        return

    if not prompt_yes_no(f"Swap {summary}?", default=False):
        print("Swap cancelled.")
        return

    print(f"Executing swap: {summary}")
    execute_swap(quote, wallet)


if __name__ == "__main__":
    main()

```

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

### Create Project Directory for AI Implementation

Source: https://docs.ston.fi/developer-section/quickstart/python

Use this bash command to create a new directory for your project and navigate into it. Place the appropriate agent guide file (CLAUDE.md or AGENTS.md) in this directory before running the AI agent.

```bash
mkdir my-omniston-swap
cd my-omniston-swap
# Place CLAUDE.md (for Claude Code) or AGENTS.md (for other agents) here
```

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

### Create Python Virtual Environment

Source: https://docs.ston.fi/developer-section/quickstart/python

Initializes a Python virtual environment for project dependencies. Activate it using the provided command for your OS.

```bash
python3 -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\\Scripts\\Activate.ps1  # Windows PowerShell
```

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

### v1 Swap Jetton to Jetton Transaction Parameters

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v1-to-v2

This example demonstrates how to obtain transaction parameters for swapping jettons in v1 using the `Router` class.

```typescript
const router = new DEX.v1.Router(routerAddress);
const params = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: wallet,
  offerJettonAddress: tokenA,
  askJettonAddress: tokenB,
  offerAmount: 1000000000n,
  minAskAmount: 900000000n
});
```

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

### Initialize STON.fi SDK

Source: https://docs.ston.fi/developer-section/dex/api/reference

Initialize the DEX client and fetch assets using the TypeScript SDK.

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

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

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

### Install Python Dependencies

Source: https://docs.ston.fi/developer-section/quickstart/python

Installs necessary Python packages including `python-dotenv`, `tonsdk`, and `websockets` by referencing `requirements.txt`.

```text
python-dotenv>=1.0,<2
tonsdk>=1.0.13
websockets>=11,<13
```

```bash
pip install -r requirements.txt
```

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

### Create an Instance

Source: https://docs.ston.fi/developer-section/omniston/sdk/nodejs

Instantiate the Omniston SDK, providing the API URL. You can use the production or sandbox environment.

```APIDOC
## Create an Instance

Create an Omniston instance, specifying the API URL.

```ts
import { Omniston } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({
  apiUrl: "wss://omni-ws.ston.fi",
});
```

The constructor takes the following parameters:

| Name     | Type                     | Description                                                                                                                                  |
| -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `ApiClient | undefined` | Optional. Provide this if you want to override the default API client. By default, this will be an `ApiClient` using `ReconnectingTransport` |
| `apiUrl` | `URL | string`          | Omniston WebSocket API URL.                                                                                                                  |

#### Sandbox example (testing)

If you are developing or testing your integration, use the public sandbox environment instead of production.

```ts
import { Omniston } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({
  apiUrl: "wss://omni-ws-sandbox.ston.fi",
});
```

> Sandbox is intended for development and integration testing only. Do not use sandbox in production applications.
```

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

### Create Project Workspace

Source: https://docs.ston.fi/developer-section/quickstart/python

Sets up the directory structure for the Omniston Python project.

```bash
mkdir omniston-python
cd omniston-python
```

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

### Omniston Swap Protocol Guide

Source: https://docs.ston.fi/developer-section

A comprehensive guide to the Omniston Swap Protocol for integrating cross-DEX swapping into TON applications.

```APIDOC
## Omniston Swap Protocol Guide

### Description
This is a complete guide to the Omniston Swap Protocol, detailing how to integrate cross-DEX swapping capabilities into your TON applications.

### Method
N/A (Protocol Guide)

### Endpoint
`/developer-section/omniston/swap.md`

### Parameters
N/A

### Request Example
(Refer to the guide for integration examples)

### Response
N/A
```

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

### Toncenter GET Request

Source: https://docs.ston.fi/developer-section/quickstart/python

Performs a GET request to the Toncenter API. Appends API key if available and handles URL encoding.

```python
def toncenter_get(endpoint: str, params: Dict[str, object]) -> Dict[str, object]:
    query = dict(params)
    if TONCENTER_API_KEY:
        query.setdefault("api_key", TONCENTER_API_KEY)
    url = f"{TONCENTER_API_URL.rstrip('/')}/{endpoint}"
    if query:
        url = f"{url}?{urllib.parse.urlencode(query)}"
    request = urllib.request.Request(url, headers={"Accept": "application/json"})
    with urllib.request.urlopen(request, timeout=15) as response:
        return json.loads(response.read().decode("utf-8"))
```

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

### Destroy Farm NFT Example

Source: https://docs.ston.fi/developer-section

SDK example for destroying farm NFTs. Use this to clean up unstaked farming positions and recover storage fees.

```typescript
import { Address, Sender, SenderArguments } from "@ton/core";
import { Farm } from "./Farm";

export class FarmHelper {
    constructor(private farm: Farm) {}

    async destroy(sender: Sender, collection: Address, id: string | number) {
        const message: SenderArguments = {
            to: collection,
            value: "0.01" + Tone.from("ton"),
            body: this.farm.destroy(
                collection,
                BigInt(id)
            ),
        };
        await sender.send(message);
    }
}
```

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

### Rejected Quote Error Message Example

Source: https://docs.ston.fi/developer-section/omniston/swap/grpc

Example of an error message received when an invalid 'extraVersion' is used in a quote request. Always use 'extraVersion = 1'.

```text
Invalid extra version for step 0: 3
```

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

### Install Tailwind CSS and Vite Polyfills

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Installs Tailwind CSS for styling and a Vite plugin to polyfill Node.js modules like 'buffer', which are required by TON libraries.

```bash
pnpm add tailwindcss @tailwindcss/vite vite-plugin-node-polyfills
```

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

### Configure TON Center API Key

Source: https://docs.ston.fi/developer-section/quickstart/python

After the AI implementation is complete, create a .env file in your project's root directory and add your TON Center API key. This step is crucial and must be done manually as AI agents cannot access personal API credentials.

```bash
TONCENTER_API_KEY=your_api_key_here
```

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

### Initialize and Use DEX Router (v2)

Source: https://docs.ston.fi/developer-section/dex/sdk

Initialize the DEX router for version 2 of the SDK. This requires a TON API client. Use this to build swap transactions.

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

// Initialize DEX
const dex = new DEX.v2.Router({
  tonApiClient: client
});

// Perform a swap
const swapParams = {
  // ... swap parameters
};

const swap = await dex.buildSwapTransaction(swapParams);
```

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

### Update Router Initialization

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v0.4-to-v0.5

Transition from revision-based initialization to versioned domain object access.

```diff
- import { DEX, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

+ import { DEX, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

-  const router = new Router(provider, {
-   revision: ROUTER_REVISION.V1,
+  const router = new Dex.v1.Router(provider, {
    address: ROUTER_REVISION_ADDRESS.V1,
  });
```

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

### Omniston Referral Fees Guide

Source: https://docs.ston.fi/developer-section

Guide to Omniston referral fees, explaining how to earn commissions from DEX v1, v2, DeDust, Toncoin, and Escrow swap volumes.

```APIDOC
## Omniston Referral Fees Guide

### Description
This guide details the Omniston referral fees system. It explains how users and developers can earn commissions from swap volumes across various DEXs including DEX v1, v2, DeDust, Toncoin, and Escrow.

### Method
N/A (Informational Guide)

### Endpoint
`/developer-section/omniston/referral-fees.md`

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

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

### Migrate v0.4 Jetton to TON Swap Example

Source: https://docs.ston.fi/developer-section/dex/sdk/migration/v0.4-to-v0.5

Initial v0.4 implementation of a Jetton to TON swap using the Router contract.

```ts
import TonWeb from 'tonweb';
import { Router, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

const WALLET_ADDRESS = ''; // ! replace with your address
const JETTON0 = 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO'; // STON
const PROXY_TON = 'EQCM3B12QK1e4yZSf8GtBRT0aLMNyEsBc_DhVfRRtOEffLez'; // ProxyTON

const provider = new TonWeb.HttpProvider();

const router = new Router(provider, {
  revision: ROUTER_REVISION.V1,
  address: ROUTER_REVISION_ADDRESS.V1,
});

const tonToJettonTxParams = await router.buildSwapJettonTxParams({
  userWalletAddress: WALLET_ADDRESS,
  offerJettonAddress: JETTON0,
  offerAmount: new TonWeb.utils.BN('1000000000'),
  askJettonAddress: PROXY_TON,
  minAskAmount: new TonWeb.utils.BN('1'),
  queryId: 12345,
});
```

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

### Create React + Vite Project

Source: https://docs.ston.fi/developer-section/quickstart/liquidity

Creates a new React project with Vite and TypeScript. Navigate into the project directory afterwards.

```bash
pnpm create vite --template react-ts
cd stonfi-liquidity-app
```

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

### Get Swap Ton to Jetton Transaction Parameters

Source: https://docs.ston.fi/developer-section/dex/sdk/v2/swap

Use this to get transaction parameters for swapping TON to a specific Jetton on the testnet. Ensure you have set up the necessary contracts and liquidity pools beforehand.

```typescript
import { TonClient, toNano } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";

const client = new TonClient({
  endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create("kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v") // CPI Router v2.1.0 (testnet)
);

const proxyTon = pTON.v2_1.create("kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px"); // pTON v2.1.0 (testnet)

const txParams = await router.getSwapTonToJettonTxParams({
  userWalletAddress: "<your testnet wallet>",
  proxyTon,
  offerAmount: toNano("1"),
  askJettonAddress: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // TesREED jetton (testnet)
  minAskAmount: "1",
});
```

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

### GET /v1/pools

Source: https://docs.ston.fi/developer-section/dex/api/reference

Endpoints for interacting with liquidity pools.

```APIDOC
## GET /v1/pools

### Description
List all liquidity pools.

### Method
GET

### Endpoint
/v1/pools

## GET /v1/pools/{address}

### Description
Get specific pool details.

### Method
GET

### Endpoint
/v1/pools/{address}

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

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

### GET get_jetton_data

Source: https://docs.ston.fi/developer-section/dex/smart-contracts/v2/pool

Retrieves standard Jetton data from the contract.

```APIDOC
## GET get_jetton_data

### Description
Returns standard jetton data following the TonWeb JettonMinter interface.

### Method
GET

### Endpoint
get_jetton_data()
```
Tokens:
Raw