@tegroton/tegro-finance

Production-ready TypeScript SDK for the Tegro Finance DEX — an AMM on The Open Network (TON). It ships two integration modes:

API mode — a thin, typed HTTP client over the public Tegro Finance API (read pools/assets, quote, and have the backend prepare transactions).
On-chain mode — build swap & liquidity transactions entirely client-side with TegroFinanceRouter, with no dependency on our backend (the STON.fi-grade path). Every message body is verified byte-for-byte against the production contracts.

Surface at a glance:

Read — getPools(), getAssets(), getTokenData(), getPoolsForWallet().
Quote — simulateSwap(), simulateReverseSwap(), simulateProvideLiquidity().
Build (API) — buildSwap(), buildProvideLiquidity(), buildRemoveLiquidity(), buildCreatePool() → a ready-to-sign TON Connect message list.
Build (on-chain) — TegroFinanceRouter.getSwapTxParams(), getProvideLiquidityTxParams(), getRemoveLiquidityTxParams(), getCreatePoolTxParams().
Helpers — toUnits / fromUnits (BigInt-exact), applySlippage, toTonConnectMessages.

Non-custodial by design. Every state change is authorized by the user's wallet via TON Connect. The backend returns a prepared message payload; this SDK maps it to the wallet's sendTransaction shape and passes the BOC through untouched. The SDK never holds, sees, or transmits a private key.

Status: verified against the live tegro.finance API on 2026-06-09 (read, quote, and error paths exercised end-to-end).

Why this exists

Integrating a TON AMM means juggling smallest-unit math, slippage flooring, the swap/liquidity request shapes, and the exact object tonConnectUI.sendTransaction() wants. Everyone writes the same glue. This package is that glue — typed, tested, MIT-licensed — so your app can quote a swap and hand a transaction to the wallet in a dozen lines.

Install

npm install @tegroton/tegro-finance
# or
pnpm add @tegroton/tegro-finance

Node.js ≥ 18 required (uses global fetch and AbortController). Works in the browser too. TON Connect is an optional peer dependency — you only need it on the frontend that actually signs.

Quick start

Read pools and tokens

import { TegroFinanceClient } from "@tegroton/tegro-finance";

const client = new TegroFinanceClient(); // defaults to https://api.tegro.finance

const pools = await client.getPools();
const assets = await client.getAssets(); // { [contractAddress]: Asset }

console.log(`${pools.length} pools, ${Object.keys(assets).length} tokens`);

Quote a swap

import { TegroFinanceClient, toUnits, fromUnits, TON_NATIVE_ADDRESS } from "@tegroton/tegro-finance";

const client = new TegroFinanceClient();
const assets = await client.getAssets();
const tgr = Object.values(assets).find((a) => a.symbol === "TGR")!;

const quote = await client.simulateSwap({
  offerAddress: TON_NATIVE_ADDRESS,
  askAddress: tgr.contract_address,
  units: toUnits("1", 9), // 1 TON in nanotons
  slippageTolerance: 0.01, // 1%
});

console.log(`1 TON → ~${fromUnits(quote.ask_units, tgr.decimals)} TGR`);
console.log(`price impact ${(quote.price_impact * 100).toFixed(3)}%`);

Build a swap and let the wallet sign it (TON Connect)

import {
  TegroFinanceClient,
  toUnits,
  applySlippage,
  toTonConnectMessages,
  TON_NATIVE_ADDRESS,
} from "@tegroton/tegro-finance";
import { useTonConnectUI, useTonAddress } from "@tonconnect/ui-react";

const client = new TegroFinanceClient();
const [tonConnectUI] = useTonConnectUI();
const userAddress = useTonAddress();

const offerUnits = toUnits("1", 9);
const quote = await client.simulateSwap({
  offerAddress: TON_NATIVE_ADDRESS,
  askAddress: tgrAddress,
  units: offerUnits,
  slippageTolerance: 0.01,
});

const tx = await client.buildSwap({
  userWalletAddress: userAddress,
  offerJettonAddress: TON_NATIVE_ADDRESS,
  offerAmount: offerUnits,
  askJettonAddress: tgrAddress,
  minAskAmount: applySlippage(quote.ask_units, 0.01), // floor it yourself
});

// The ONLY place a signature happens — the SDK never sees a key.
await tonConnectUI.sendTransaction(toTonConnectMessages(tx));

On-chain mode — build without our backend

If you don't want a dependency on the Tegro API for transaction building, use TegroFinanceRouter. It assembles the exact same message the backend would (verified byte-for-byte against the production contracts) using only @ton/core and a jetton-wallet resolver over any TON RPC:

import { TegroFinanceRouter, tonApiResolver, cachingResolver, applySlippage } from "@tegroton/tegro-finance";

const router = new TegroFinanceRouter({
  routerAddress: "EQAbKJUWn1oWVPkvp78vkmt0E7gA929rIbP33XAISzWTelct", // read from /api/v1/pools
  proxyTonAddress: "EQDzeU94K3aDdAfqB-NLcaCfTwUMzbpFmlrTpwM_xpQRrtgs", // the router's pTON wallet master
  resolver: cachingResolver(tonApiResolver()), // or your own @ton/ton-based resolver
});

const tx = await router.getSwapTxParams({
  userWalletAddress: userAddress,
  offerJettonAddress: TON_NATIVE_ADDRESS,
  offerAmount: toUnits("1", 9),
  askJettonAddress: tgrAddress,
  minAskAmount: applySlippage(expectedOut, 0.01),
});

await tonConnectUI.sendTransaction(tx); // already TON Connect-shaped

getProvideLiquidityTxParams, getCreatePoolTxParams, getRemoveLiquidityTxParams and getUnlockPoolTxParams work the same way. Resolve routerAddress and the pool/pTON addresses from /api/v1/pools — never hardcode them long-term.

Full runnable examples: examples/list-pools.ts, examples/quote-and-swap.ts, examples/tonconnect-react.tsx.

Liquid staking — stake TON, get stgTON

Stake TON into the liquid-staking pool and receive stgTON, a token whose rate appreciates against TON. Exit by unstaking (burns stgTON → a 72-hour withdrawal voucher) and claiming once it matures. Same non-custodial model: every state change returns a TON Connect message the wallet signs.

import { TegroFinanceStakingClient, toTonConnectMessages, toUnits } from "@tegroton/tegro-finance";

const staking = new TegroFinanceStakingClient();

// Read (open, no wallet): pick the active pool and read its live rate.
const pools = await staking.getPools(); // apy is a PERCENT (16.97 = 16.97%)
const master = pools.find((p) => p.is_active)!.out_asset.contract_address;
const { price } = await staking.getPoolData(master); // stgTON→TON rate, 1e9 fixed point

// Stake (auth): in a browser the TON Connect session cookie travels automatically.
const tx = await staking.buildStake({ masterAddress: master, offerAmount: toUnits("5", 9) });
await tonConnectUI.sendTransaction(toTonConnectMessages(tx));

// Exit: unstake → wait 72h → claim a matured voucher.
await staking.buildUnstake({ masterAddress: master, sharesAmount: toUnits("5", 9) });
const pending = await staking.getWithdrawals(master); // [{ voucher_address, claim_after, claimable }]
const ready = pending.find((w) => w.claimable);
if (ready) await staking.buildClaim({ masterAddress: master, voucherAddress: ready.voucher_address });

On a server (no browser cookie) pass the session explicitly: new TegroFinanceStakingClient({ sessionToken: "<token from TON Connect auth>" }). Runnable: examples/staking.ts (npm run example:staking).

Authenticating a wallet (TON Connect) for staking

buildStake / buildUnstake / buildClaim / getWithdrawals need a wallet session. Open one from a TON Connect ton_proof:

import { TegroFinanceAuthClient, TegroFinanceStakingClient, tonProofToLoginRequest } from "@tegroton/tegro-finance";

const auth = new TegroFinanceAuthClient();

// 1. Get a challenge and hand it to TON Connect BEFORE the user connects.
const payload = await auth.getPayload();
tonConnectUI.setConnectRequestParameters({ state: "ready", value: { tonProof: payload } });

// 2. After the user connects, map the signed proof and log in.
const { token } = await auth.login(tonProofToLoginRequest(wallet, { affiliateAddress }));

// 3a. Browser, same origin as tegro.finance → the session cookie is set; just use the client.
const staking = new TegroFinanceStakingClient();
// 3b. Server-side (or a Mini App on your own domain, proxied through your backend):
const stakingServer = new TegroFinanceStakingClient({ sessionToken: token });

The proof is not domain-locked, so a Mini App on any origin can authenticate against a Tegro-issued payload. The session lasts 48h (auto-refreshes past half-life; auth.refreshToken() to extend). The challenge payload is valid for 20 min and the proof timestamp window is 5 min.

Cross-origin note. The session is a cookie named tegro-dex, scoped to tegro.finance and currently SameSite=Lax, and tegro.finance's CORS allow-list does not include third-party origins. So a browser dApp on another domain cannot call the authenticated endpoints directly — run them from your server with { sessionToken } (a browser can't set the cookie header cross-origin), or ask Tegro to allow-list your origin and set SameSite=None; Secure. Runnable: examples/auth.ts (npm run example:auth).

Core concepts (read this once)

Units are integers in the smallest denomination

The API speaks "units" — 10**decimals of a token (nanotons for TON). Convert with the BigInt-exact helpers; never use floating-point math on money:

toUnits("1.5", 9)        // → 1500000000n
fromUnits(1500000000n, 9) // → "1.5"

toUnits rejects more fractional digits than the token has decimals instead of silently truncating. Outgoing amounts accept bigint | number | string and are serialized as real JSON integers, so values above 2**53 keep full precision on the wire.

Slippage is your floor, computed locally

applySlippage(quote.ask_units, 0.01) // tolerate 1% less; rounds toward zero

Pass the result as minAskAmount / minLpOut. It rounds the floor down, so a worse-than-tolerated trade can never slip through.

Fees are hundredths of a percent

lp_fee: 20 means 0.20%. Divide by 100 for a percentage.

The wallet signs, not the SDK

buildSwap / buildProvideLiquidity / buildRemoveLiquidity / buildCreatePool / buildUnlockPool return TransactionData ({ valid_until, messages[] }). Feed it through toTonConnectMessages() and hand the result to the wallet. The payload BOC is opaque — pass it through unchanged.

API reference

`new TegroFinanceClient(options?)`

type TegroFinanceClientOptions = {
  apiBase?: string;     // default "https://api.tegro.finance" ("https://tegro.finance" also works)
  fetch?: typeof fetch; // inject for tests / proxies / retry wrappers
  timeoutMs?: number;   // per-request timeout, default 15000 (0 disables)
};

Read

Method	Endpoint	Returns
`getPools()`	`GET /api/v1/pools`	`Pool[]`
`getPoolsForToken(addr)`	`GET /api/v1/pools/{addr}`	`Pool[]`
`getPoolsForWallet(addr)`	`GET /api/v1/wallet/{addr}/get_pools`	`Pool[]` (with `lp_balance`)
`getPoolsPairs()`	`GET /api/v1/pools-pairs`	`Pair[]`
`getPoolsPairsForToken(addr)`	`GET /api/v1/pools-pairs/for/{addr}`	`Pair[]`
`getAssets()`	`GET /api/v1/assets`	`AssetMap`
`getAssetList()`	(derived)	`Asset[]`
`getTokenData(addr)`	`GET /api/v1/tokens/{addr}/data`	`TokenData`
`tokenLogoUrl(addr)`	(URL builder)	`string`

Quote

Method	Endpoint	Returns
`simulateSwap(p)`	`POST /api/v1/swap/simulate`	`SwapSimulation`
`simulateReverseSwap(p)`	`POST /api/v1/reverse_swap/simulate`	`SwapSimulation`
`simulateProvideLiquidity(p)`	`POST /api/v1/dex/liquidity/provide/simulate`	`ProvideLiquiditySimulation`

Quote methods throw TegroFinanceDexError (with .code: 21 pool-not-found, 22 insufficient-liquidity, 23 wrong-action) when the API returns an error envelope.

Build (→ TON Connect message list)

Method	Endpoint
`buildSwap(p)`	`POST /api/v1/swap`
`buildProvideLiquidity(p)`	`POST /api/v1/dex/liquidity/provide`
`buildCompleteProvideLiquidity(p)`	`POST /api/v1/dex/liquidity/provide_complete`
`buildCompleteProvideLiquidityActivate(p)`	`POST /api/v1/dex/liquidity/provide_complete_activate`
`buildRemoveLiquidity(p)`	`POST /api/v1/dex/liquidity/remove`
`buildCreatePool(p)`	`POST /api/v1/dex/liquidity/create`
`buildUnlockPool(p)`	`POST /api/v1/dex/pool/unlock`

On-chain (`new TegroFinanceRouter({ routerAddress, proxyTonAddress, resolver })`)

Builds the same transactions client-side — no backend call for tx construction. Each method returns a TON Connect request ({ validUntil, messages }).

Method	Builds
`getSwapTxParams(p)`	swap (TON↔jetton, jetton↔jetton)
`getProvideLiquidityTxParams(p)`	add liquidity (one message per non-zero side)
`getCreatePoolTxParams(p)`	create a pool (two-sided provide on a new pair)
`getRemoveLiquidityTxParams(p)`	burn LP at the user's LP wallet
`getUnlockPoolTxParams(p)`	admin `update_pool_status` (pool unlock)

Resolvers: tonApiResolver(opts?) (over tonapi.io), cachingResolver(inner), or any object implementing JettonWalletResolver. Low-level cell builders (buildSwapBody, buildJettonTransferBody, buildPtonTonTransferBody, buildProvideLiquidityBody, buildBurnBody, buildUpdatePoolStatusBody) and the OpCodes / Gas constants are exported too.

`new TegroFinanceStakingClient(options?)`

Liquid staking (stgTON). Same non-custodial model as the DEX client.

type TegroFinanceStakingClientOptions = {
  apiBase?: string;        // default "https://tegro.finance" — the session cookie's origin
  sessionToken?: string;   // server-side cookie auth (browser uses credentials:"include")
  credentials?: "omit" | "same-origin" | "include"; // default "include"
  fetch?: typeof fetch;
  timeoutMs?: number;      // default 15000
};

Method	Endpoint	Auth	Returns
`getPools()`	`GET /api/v1/liquid-staking/pools`	—	`StakingPool[]` (`apy` is a percent)
`getPoolData(master)`	`GET …/pool/{master}/data`	—	`StakingPoolData` (`price` = stgTON→TON rate)
`getWithdrawals(master)`	`GET …/pool/{master}/withdrawals`	cookie	`StakingWithdrawal[]`
`buildStake(p)`	`POST …/pool/{master}/stake`	cookie	`TransactionData`
`buildUnstake(p)`	`POST …/pool/{master}/unstake`	cookie	`TransactionData`
`buildClaim(p)`	`POST …/pool/{master}/claim`	cookie	`TransactionData`

setSessionToken(token \| null) updates the cookie after auth. Authenticated calls throw TegroFinanceStakingAuthError on 401/403. Rate helpers stgTonToTon(stgUnits, price) / tonToStgTon(tonUnits, price) convert at a pool's price (display estimates — they exclude the 0.5% redeem fee and gas; the contract is authoritative).

Helpers

toUnits(amount, decimals): bigint
fromUnits(units, decimals): string
toBigIntUnits(value): bigint
applySlippage(expectedUnits, tolerance): bigint
toTonConnectMessages(tx, validForSecs?): { validUntil, messages }

Errors

TegroFinanceApiError — transport failure, timeout, or non-2xx HTTP. Carries .status and .raw.
TegroFinanceDexError — a simulate endpoint returned {type:"error", code, message}. Carries .code.
TegroFinanceStakingAuthError — an authenticated staking endpoint returned 401/403; re-authenticate the wallet (or pass sessionToken).

A note on precision

Outgoing amounts are exact (BigInt → unquoted JSON integers). Incoming numeric fields (ask_units, fee_units, reserves, …) are typed as number because the upstream encodes them as JSON numbers — values above 2**53 may lose precision. For the realistic nanoton ranges the app trades in this is non-issue; if you need exact reads of very large amounts, fetch the raw response and parse those fields as BigInt yourself.

Tests

npm test          # vitest, network mocked
npx tsc --noEmit  # type check

The suite (40 tests) covers amount math (round-trips, truncation rejection, unsafe-integer guards), request shaping, BigInt-on-the-wire serialization, the DEX-error envelope, the TON Connect mapping, the on-chain Router routing, and byte-for-byte cell-hash equality of every on-chain body against the production backend (pytoniq_core).

Roadmap / non-goals

✅ Implemented

Read: pools, pairs, assets, token data, wallet positions
Quote: swap, reverse swap, provide-liquidity
Build (API): swap, provide / complete / activate, remove, create pool, unlock pool
Build (on-chain): client-side swap / provide / remove / create / unlock, verified byte-for-byte against the production contracts
BigInt-exact units + slippage helpers
TON Connect message adapter
One runtime dep (@ton/core); the HTTP/quote layer is dependency-free

🚧 Not yet (PRs welcome)

IDO / launchpad endpoints
Multi-hop route helper
A lossless BigInt response parser

❌ Out of scope

No key management, no signing — that's the wallet's job, by design.
No database, no order tracking — bring your own.
No on-chain indexing — read the API or your own indexer.
Staking lives in a separate project, not this SDK.

Security

If you find a vulnerability, do not open a public issue. Use GitHub Private Vulnerability Reporting. Full policy in SECURITY.md.

Contributing

PRs welcome — the SDK is intentionally minimal. See CONTRIBUTING.md. New runtime dependencies are a hard sell; tests for new behavior are mandatory.

Changelog

Versioned by Semantic Versioning. See CHANGELOG.md. Releases are tagged v<MAJOR>.<MINOR>.<PATCH> and trigger an automatic npm publish.

Links

🔁 Tegro Finance DEX — https://tegro.finance
📖 Docs — https://docs.tegro.finance
💬 Community — https://t.me/TegroFinance
🐙 Source — https://github.com/TegroTON/tegro-finance-sdk

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github		.github
examples		examples
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
renovate.json		renovate.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@tegroton/tegro-finance

Why this exists

Install

Quick start

Read pools and tokens

Quote a swap

Build a swap and let the wallet sign it (TON Connect)

On-chain mode — build without our backend

Liquid staking — stake TON, get stgTON

Authenticating a wallet (TON Connect) for staking

Core concepts (read this once)

Units are integers in the smallest denomination

Slippage is your floor, computed locally

Fees are hundredths of a percent

The wallet signs, not the SDK

API reference

new TegroFinanceClient(options?)

Read

Quote

Build (→ TON Connect message list)

On-chain (new TegroFinanceRouter({ routerAddress, proxyTonAddress, resolver }))

new TegroFinanceStakingClient(options?)

Helpers

Errors

A note on precision

Tests

Roadmap / non-goals

See also

Security

Contributing

Changelog

Links

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`new TegroFinanceClient(options?)`

On-chain (`new TegroFinanceRouter({ routerAddress, proxyTonAddress, resolver })`)

`new TegroFinanceStakingClient(options?)`