Bot Integration with STON.fi SDK (TON)

STON.fi SDK Integration Bot (TON)

TON — not EVM-compatible blockchain, and bot development approaches here fundamentally different. STON.fi — largest DEX on TON with AMM architecture. Integration with it via official SDK enables automated trading on this market, but requires understanding TON specifics: asynchronous messages, actor model, and fee mechanics different from EVM.

How TON differs from EVM in trading bot context

Asynchronous transaction model

In Ethereum transaction either executes or reverts — all synchronously in one block. In TON contracts communicate via asynchronous messages. After sending swap-message to STON.fi router, you don't know result immediately. Must listen for incoming messages to wallet address (transfer notification from jetton) or poll state via TON API.

This means: bot must have state machine for each operation. Sent swap → waiting for confirmation → if none for N seconds → retry or alert. Simple send-and-forget logic leads to lost transactions.

Jetton transfer notification

STON.fi works with jetton (ERC-20 analog on TON). When swap executed, router sends transfer_notification to recipient address. Bot must parse these messages: decode BoC (Bag of Cells), extract jetton amount and sender. STON.fi SDK provides types for this, but integration requires setting up TON listener.

Integration with STON.fi SDK

Installation and configuration

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

const tonweb = new TonWeb(
  new TonWeb.HttpProvider("https://toncenter.com/api/v2/jsonRPC", {
    apiKey: process.env.TONCENTER_API_KEY
  })
);

const router = tonweb.open(
  new DEX.v1.Router("EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt")
);

STON.fi SDK v2 supports DEX v1 and v2 pools. For new code use v2 router — supports more complex routing scenarios and better API integration.

Getting quotes

const pool = await router.getPool({
  token0: "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",  // TON
  token1: USDT_JETTON_ADDRESS
});

const data = await pool.getData();
// data.reserve0, data.reserve1 — current reserves
// Calculate expected output via AMM formula

SDK provides getExpectedOutputs() for slippage calculation. Important: quotes become stale quickly on active market. For trading bot — cache no longer than 5-10 seconds.

Executing swap

const swapTxParams = await router.buildSwapTonToJettonTxParams({
  userWalletAddress: wallet.address,
  proxyTon: new pTON.v1(),
  offerAmount: new TonWeb.utils.BN("1000000000"),  // 1 TON in nanotons
  askJettonAddress: USDT_JETTON_ADDRESS,
  minAskAmount: expectedOutput.mul(99).div(100),  // 1% slippage tolerance
  queryId: Date.now()  // unique id for tracking
});

await wallet.sendTransfer({
  secretKey: keyPair.secretKey,
  toAddress: swapTxParams.to,
  amount: swapTxParams.gasAmount,
  seqno: await wallet.getSeqno(),
  payload: swapTxParams.payload
});

queryId — critically important parameter for tracking. Included in response messages and allows matching swap request with result in async model.

Building trading bot

Architecture

Price monitor: periodic polling prices via STON.fi API (https://api.ston.fi/v1/pools) or direct on-chain requests. API more convenient — returns normalized data for all pools. On-chain more reliable with unreliable API.

Strategy engine: trading decision logic. For arbitrage bot — comparing STON.fi prices with other TON DEX (DeDust). For trend bot — technical indicators on historical prices from API.

Transaction manager: queue of transactions with retry logic. TON requires correct seqno for wallet — parallel sending causes errors. Send transactions sequentially or via separate sub-wallets.

Result tracker: polling recent wallet transactions via TON API for confirmation of swap execution. https://toncenter.com/api/v2/getTransactions?address=...

Managing gas on TON

TON uses gas model different from Ethereum. For jetton-swap need send sufficient TON for forward fees through message chain: router → jetton wallet → user wallet. STON.fi SDK returns correct gasAmount in buildSwapTxParams — don't underbid it "for savings". If gas insufficient — message simply won't reach, and funds can hang on intermediate contract.

Monitoring and security

Store wallet private key via environment variables, never in code. For production bot — hardware wallet or separate hot wallet with minimum balance for operations.

Telegram notifications via bot API on each transaction: asset, volume, price, gas. On errors — immediate alert with error text.

Timeline estimates

Simple bot for manual swap via STON.fi SDK — 1-2 days. Full-featured trading bot with price monitoring, strategy engine and transaction tracking — 3-5 days. With multi-DEX integration and arbitrage logic — 1-1.5 weeks. Cost calculated after clarifying strategy and requirements.