mrruby

Omniston Guide (Python)

This guide will walk you through creating a terminal-based token swap client using the Omniston protocol to swap assets across different DEXes (STON.fi V1, STON.fi V2, DeDust, etc.). Instead of a web UI and TonConnect, we'll use a local TON wallet (created with tonsdk) and submit transactions via Toncenter. The guide is beginner‑friendly and assumes minimal TON experience.

Note: This quickstart intentionally uses a single-file CLI for clarity. You can later modularize or package it (see Advanced Example App).

Note: For reliability when broadcasting transactions, set a TONCENTER_API_KEY (see Configure Assets & Network).

---

mrruby

require('dotenv').config();
const { TonClient, WalletContractV4, Address, internal } = require("@ton/ton");
const { Cell } = require("@ton/core");
const { mnemonicToWalletKey } = require("@ton/crypto");
const { Omniston, Blockchain, SettlementMethod, GaslessSettlement } = require("@ston-fi/omniston-sdk");

class StableAutoSwap {
    constructor() {
        this.tonClient = new TonClient({
            endpoint: 'https://toncenter.com/api/v2/jsonRPC',

mrruby

Note for the agent: When following this guide, implement the entire application (with installation of packages by running pnpm install) as described but DO NOT run the dev server (pnpm dev). After completing the implementation, end the task and inform the user to test the application by running pnpm dev themselves and finish running.

Liquidity Providing Guide (React)

This guide will walk you through creating a basic liquidity provision app using the STON.fi SDK and API in a React project. We'll integrate wallet connectivity with TonConnect (via @tonconnect/ui-react) to allow users to connect their TON wallet and provide liquidity to pools. The guide is beginner-friendly and assumes minimal React experience.

Note: In this demo, we will leverage Tailwind CSS for styling instead of using custom CSS. The setup for Tailwind CSS is already included in the instructions below, so you don't need to set it up separately.

Note: You can use any package manager (npm, yarn, pnpm,

mrruby

Swapping crypto using Privy and Omniston

This guide extends the Getting started with Privy and TON application by adding token swap functionality using Omniston - a protocol that aggregates liquidity from multiple DEXes including STON.fi and DeDust.

Prerequisites

Before starting this guide, ensure you have: - Completed the [Getting started with Privy and TON](./getting-started-with-privy-and-ton.md) guide - A working React app with Privy authentication for TON

mrruby

Getting started with Privy and TON (Vite + React)

This guide demonstrates how to integrate Privy with the TON blockchain in a Vite + React app to enable wallet login as well as message and transaction signing.

Resources

Learn how to use Privy embedded wallets with TON for signing messages and transactions.

mrruby

interface SwapTransaction {
    hash: string;
    utime: number;
    in_msg?: {
        value: string;
        decoded_body?: {
            left_amount?: string;
            right_amount?: string;
            from_user?: string;
            dex_payload?: {

mrruby

Note for the agent: When following this guide, implement the entire application (with installation of packages by running pnpm install) as described but DO NOT run the dev server (pnpm dev). After completing the implementation, end the task and inform the user to test the application by running pnpm dev themselves and finish running.

Omniston Guide (React)

This guide will walk you through creating a basic token swap app using the Omniston protocol to swap assets across different DEXes (STON.fi V1, STON.fi V2, DeDust, etc.). We'll integrate wallet connectivity with TonConnect (via @tonconnect/ui-react) to allow users to connect their TON wallet and perform a swap. The guide is beginner-friendly and assumes minimal React experience.

Note: In this demo, we will leverage Tailwind CSS for styling instead of using custom CSS. The setup for Tailwind CSS is already included in the instructions below, so you don't need to set it up separately.

Note: You can use any package m

mrruby

Below is a minimal end‑to‑end example that shows how you can: 1. Query STON.fi REST endpoints to discover assets. 2. Simulate a swap to get the expected output amount and the router address. 3. Prepare a transaction that your TON wallet (or a head‑less TON client) can sign and broadcast.

Because STON.fi does not yet publish an official Python SDK, everything is done with plain requests and well‑known TON helper libraries.

⸻

1  Prerequisites

mrruby

{
    "url": "https://ton.vote",
    "name": "TON Vote",
    "iconUrl": "https://ton.vote/logo.png"
}

mrruby

import { TonClient, toNano, WalletContractV4, Cell } from "@ton/ton";
import { mnemonicToPrivateKey } from "@ton/crypto";
import { DEX } from "@ston-fi/sdk"; // import the pieces you actually use
import * as dotenv from "dotenv";

async function main() {
    dotenv.config();
    const apiKey = process.env.TONCENTER_API_KEY;
    const mnemonicsString = process.env.MNEMONIC;