@onrank/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ONRANK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @onrank/sdk
+
+Quote and trade [ONRANK](https://t.me/OnRankBot) coins from your own bot, wallet or terminal. Pure TypeScript:
+the SDK **builds unsigned messages** that the user signs with their wallet (TON Connect or any wallet SDK).
+It never holds a key and never signs.
+
+```bash
+npm i @onrank/sdk @ton/core
+```
+
+## 60-second integration
+
+```ts
+import { OnrankClient, applySlippage } from "@onrank/sdk";
+
+const onrank = new OnrankClient({ toncenterKey: process.env.TONCENTER_KEY }); // key optional
+
+const coin = await onrank.coin(10001);                   // $RANK — or onrank.coins() for the list
+const { quote, minOut, message, market } = await onrank.trade({
+  coin,
+  side: "buy",                                           // or "sell"
+  amount: 5_000_000_000n,                                // buy: nanoTON to swap · sell: coin units (9 decimals)
+  slippageBps: 200,                                      // 2 %
+  owner: userWalletAddress,
+});
+// quote.amountOut = coins you get (buy) / nanoTON you get (sell); minOut = what the contract must at least deliver
+await tonConnectUI.sendTransaction({ validUntil: Math.floor(Date.now() / 1000) + 300, messages: [message] });
+```
+
+`trade()` reads the live curve or pool from toncenter, **checks the contract code hash** against the published
+build, applies the slippage and returns `{ address, amount, payload }`.
+
+## Without the client (no network in the SDK)
+
+```ts
+import { buildCurveBuy, buildSell, quoteCurveBuyForTonIn, quoteCurveSell, decodeCurveData, applySlippage } from "@onrank/sdk";
+
+const state = decodeCurveData(stackFromYourOwnRpc);      // get_curve_data
+const q = quoteCurveBuyForTonIn(state, 5_000_000_000n);  // same integer math as the contract
+const msg = buildCurveBuy({ curve, tonIn: 5_000_000_000n, minOut: applySlippage(q.amountOut, 200) });
+
+const s = quoteCurveSell(state, coinAmount);
+const sell = buildSell({ rewardWallet, owner, coinAmount, minTon: applySlippage(s.amountOut, 200) });
+// rewardWallet = get_wallet_address(owner) on the coin's master (TEP-74)
+```
+
+Pool coins: `quotePoolBuy` / `quotePoolSell` with `decodePoolData(get_pool_data)`, `buildPoolBuy`; selling on a v2
+pool is the same `buildSell` (the master routes it).
+
+## Events
+
+`decodeTradeEvent(topic, body)` decodes `CurveTrade`, `PoolSwap`, `CurveGraduated`, `LaunchCreated` from the
+external out-messages of the contracts; `topicOf(dest)` extracts the topic. See
+[EVENTS.md](https://onrank.lol/integration/EVENTS.md).
+
+## Guarantees
+
+- Message layouts are tested bit-for-bit against the ONRANK app's own builders.
+- Quote formulas are pinned to the on-chain `get_buy_quote` / `get_sell_quote` results of the live $RANK curve.
+- Builders refuse `minOut`/`minTon = 0`: no trade without slippage protection.
+
+Full protocol reference: [onrank.lol/integration/README.md](https://onrank.lol/integration/README.md) · [onrank.lol/developers](https://onrank.lol/developers) · contracts: [onrank-contracts](https://github.com/SOLEIIL/onrank-contracts).
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import { Address, type TupleItem } from "@ton/core";
+import { type LauncherVersion } from "./constants.js";
+import { type TonConnectMessage } from "./messages.js";
+import { type Quote } from "./quotes.js";
+export type ApiCoin = {
+    seq: string;
+    symbol: string | null;
+    name: string | null;
+    master: string;
+    curve: string;
+    pool: string | null;
+    version: LauncherVersion;
+    sellOnly: boolean;
+    hidden?: boolean;
+};
+export type ClientOptions = {
+    /** toncenter v2 base, default https://toncenter.com/api/v2 */
+    toncenter?: string;
+    /** optional toncenter API key (raises the rate limit) */
+    toncenterKey?: string;
+    /** ONRANK API base, default https://onrank.lol */
+    api?: string;
+    fetch?: typeof fetch;
+};
+/** toncenter v2 `runGetMethod` stack → @ton/core TupleItem[] (numbers, cells, slices, null, tuples). */
+export declare function toncenterStackToTuple(stack: unknown[]): TupleItem[];
+export declare class OnrankClient {
+    private readonly tc;
+    private readonly key;
+    private readonly api;
+    private readonly f;
+    constructor(o?: ClientOptions);
+    runGetMethod(address: Address | string, method: string, stack?: Array<["num", string]>): Promise<TupleItem[]>;
+    /** Code hash (base64) of an account, to compare with `CODE_HASH` before trusting an address. */
+    codeHash(address: Address | string): Promise<string | null>;
+    /** Coins listed by the ONRANK API (hidden coins excluded). */
+    coins(): Promise<ApiCoin[]>;
+    coin(seq: string | number): Promise<ApiCoin>;
+    /** The holder's RewardWallet for a coin (TEP-74 `get_wallet_address`). */
+    walletAddress(master: Address | string, owner: Address | string): Promise<Address>;
+    /**
+     * Quote + unsigned message in one call. Reads the live market (curve or pool) from the chain, checks its code hash,
+     * applies `slippageBps` and returns what the user must sign. Never signs. Throws on sell-only coins for buys.
+     */
+    trade(p: {
+        coin: ApiCoin;
+        side: "buy" | "sell";
+        amount: bigint;
+        slippageBps: number;
+        owner: Address | string;
+    }): Promise<{
+        quote: Quote;
+        minOut: bigint;
+        message: TonConnectMessage;
+        market: "curve" | "pool";
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,136 @@
+// Optional network layer: reads on-chain state through toncenter v2 (no key needed for light use) and lists coins
+// through the public ONRANK API. Everything here is read-only; the messages it returns are for the user to sign.
+import { Cell, beginCell } from "@ton/core";
+import { CODE_HASH, MAINNET } from "./constants.js";
+import { decodeCurveData, decodePoolData, parseAddress } from "./decode.js";
+import { applySlippage, buildCurveBuy, buildPoolBuy, buildSell, buildPoolSellV1 } from "./messages.js";
+import { isCurveOpen, quoteCurveBuyForTonIn, quoteCurveSell, quotePoolBuy, quotePoolSell } from "./quotes.js";
+/** toncenter v2 `runGetMethod` stack → @ton/core TupleItem[] (numbers, cells, slices, null, tuples). */
+export function toncenterStackToTuple(stack) {
+    return stack.map((x) => {
+        const [kind, value] = x;
+        if (kind === "num")
+            return { type: "int", value: BigInt(value) };
+        if (kind === "cell" || kind === "slice" || kind === "builder")
+            return { type: kind === "cell" ? "cell" : "slice", cell: Cell.fromBase64(value.bytes) };
+        if (kind === "null")
+            return { type: "null" };
+        if (kind === "list" || kind === "tuple")
+            return { type: "tuple", items: toncenterStackToTuple((value.elements ?? [])) };
+        throw new Error(`unknown stack item ${kind}`);
+    });
+}
+export class OnrankClient {
+    tc;
+    key;
+    api;
+    f;
+    constructor(o = {}) {
+        this.tc = o.toncenter ?? "https://toncenter.com/api/v2";
+        this.key = o.toncenterKey;
+        this.api = o.api ?? MAINNET.api;
+        this.f = o.fetch ?? fetch;
+    }
+    async runGetMethod(address, method, stack = []) {
+        const a = typeof address === "string" ? parseAddress(address) : address;
+        const r = await this.f(`${this.tc}/runGetMethod`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(this.key ? { "X-API-Key": this.key } : {}) },
+            body: JSON.stringify({ address: a.toString(), method, stack }),
+        });
+        const j = (await r.json());
+        if (!j.ok || !j.result)
+            throw new Error(`toncenter: ${j.error ?? r.status}`);
+        if (j.result.exit_code !== 0)
+            throw new Error(`${method}: exit ${j.result.exit_code}`);
+        return toncenterStackToTuple(j.result.stack);
+    }
+    /** Code hash (base64) of an account, to compare with `CODE_HASH` before trusting an address. */
+    async codeHash(address) {
+        const a = typeof address === "string" ? parseAddress(address) : address;
+        const r = await this.f(`${this.tc}/getAddressInformation?address=${encodeURIComponent(a.toString())}`, { headers: this.key ? { "X-API-Key": this.key } : {} });
+        const j = (await r.json());
+        if (!j.ok || !j.result?.code)
+            return null;
+        return Cell.fromBase64(j.result.code).hash().toString("base64");
+    }
+    /** Coins listed by the ONRANK API (hidden coins excluded). */
+    async coins() {
+        const r = await this.f(`${this.api}/api/v1/coins`);
+        if (!r.ok)
+            throw new Error(`api: ${r.status}`);
+        return (await r.json()).items;
+    }
+    async coin(seq) {
+        const r = await this.f(`${this.api}/api/v1/coins/${seq}`);
+        if (!r.ok)
+            throw new Error(`api: ${r.status}`);
+        return (await r.json());
+    }
+    /** The holder's RewardWallet for a coin (TEP-74 `get_wallet_address`). */
+    async walletAddress(master, owner) {
+        const m = typeof master === "string" ? parseAddress(master) : master;
+        const o = typeof owner === "string" ? parseAddress(owner) : owner;
+        const slice = beginCell().storeAddress(o).endCell().toBoc().toString("base64");
+        const r = await this.f(`${this.tc}/runGetMethod`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(this.key ? { "X-API-Key": this.key } : {}) },
+            body: JSON.stringify({ address: m.toString(), method: "get_wallet_address", stack: [["tvm.Slice", slice]] }),
+        });
+        const j = (await r.json());
+        if (!j.ok || !j.result || j.result.exit_code !== 0)
+            throw new Error("get_wallet_address failed");
+        const items = toncenterStackToTuple(j.result.stack);
+        const first = items[0];
+        if (!first || (first.type !== "slice" && first.type !== "cell"))
+            throw new Error("get_wallet_address: unexpected stack");
+        return first.cell.beginParse().loadAddress();
+    }
+    /**
+     * Quote + unsigned message in one call. Reads the live market (curve or pool) from the chain, checks its code hash,
+     * applies `slippageBps` and returns what the user must sign. Never signs. Throws on sell-only coins for buys.
+     */
+    async trade(p) {
+        const owner = typeof p.owner === "string" ? parseAddress(p.owner) : p.owner;
+        const version = p.coin.version ?? 2;
+        if (p.side === "buy" && p.coin.sellOnly)
+            throw new Error("this coin is sell-only");
+        if (p.coin.pool) {
+            const pool = parseAddress(p.coin.pool);
+            if (version === 2) {
+                const h = await this.codeHash(pool);
+                if (h !== CODE_HASH.PoolV2)
+                    throw new Error(`pool code hash mismatch: ${h}`);
+            }
+            const state = decodePoolData(await this.runGetMethod(pool, "get_pool_data"));
+            if (p.side === "buy") {
+                const quote = quotePoolBuy(state, p.amount);
+                const minOut = applySlippage(quote.amountOut, p.slippageBps);
+                return { quote, minOut, market: "pool", message: buildPoolBuy({ pool, tonIn: p.amount, minOut, version }) };
+            }
+            const quote = quotePoolSell(state, p.amount);
+            const minTon = applySlippage(quote.amountOut, p.slippageBps);
+            const rewardWallet = await this.walletAddress(p.coin.master, owner);
+            const message = version === 2 ? buildSell({ rewardWallet, owner, coinAmount: p.amount, minTon, version }) : buildPoolSellV1({ rewardWallet, pool, owner, coinAmount: p.amount, minTon });
+            return { quote, minOut: minTon, market: "pool", message };
+        }
+        const curve = parseAddress(p.coin.curve);
+        if (version === 2) {
+            const h = await this.codeHash(curve);
+            if (h !== CODE_HASH.CurveV2)
+                throw new Error(`curve code hash mismatch: ${h}`);
+        }
+        const state = decodeCurveData(await this.runGetMethod(curve, "get_curve_data"));
+        if (!isCurveOpen(state))
+            throw new Error("curve is not open (graduated or not started): refresh the coin");
+        if (p.side === "buy") {
+            const quote = quoteCurveBuyForTonIn(state, p.amount);
+            const minOut = applySlippage(quote.amountOut, p.slippageBps);
+            return { quote, minOut, market: "curve", message: buildCurveBuy({ curve, tonIn: p.amount, minOut }) };
+        }
+        const quote = quoteCurveSell(state, p.amount);
+        const minTon = applySlippage(quote.amountOut, p.slippageBps);
+        const rewardWallet = await this.walletAddress(p.coin.master, owner);
+        return { quote, minOut: minTon, market: "curve", message: buildSell({ rewardWallet, owner, coinAmount: p.amount, minTon, version }) };
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,82 @@
+/** Opcodes of the messages an integrator sends (launcher v2 contracts; v1 shares them). */
+export declare const Op: {
+    /** Curve: buy with the attached TON minus BUY_GAS. */
+    readonly Buy: 1129644034;
+    /** Pool: buy with the attached TON minus SWAP_GAS. */
+    readonly SwapTonForCoin: 1347354625;
+    /** v1 pool only: forward payload of a TEP-74 transfer to the pool. */
+    readonly SwapCoinForTon: 1347354626;
+    /** TEP-74 transfer (v1 pool sell). */
+    readonly Transfer: 260734629;
+    /** TEP-74 burn on the user's RewardWallet — with a SellIntent payload it is a sale. */
+    readonly Burn: 1499400124;
+    /** Burn custom payload: sell for at least `minTon`. */
+    readonly SellIntent: 1381433368;
+};
+/** Gas the contracts require (nanoTON). Excess is refunded by the contracts; a margin costs nothing. */
+export declare const Gas: {
+    /** Curve.BUY_GAS — deducted from the attached value before the swap. */
+    readonly curveBuy: 150000000n;
+    /** Pool.SWAP_GAS (v1). */
+    readonly poolSwapV1: 200000000n;
+    /** PoolV2.SWAP_GAS. */
+    readonly poolSwapV2: 150000000n;
+    /** RewardWallet.WALLET_BURN_GAS (v1). */
+    readonly walletBurnV1: 120000000n;
+    /** RewardWalletV2.WALLET_BURN_GAS. */
+    readonly walletBurnV2: 160000000n;
+    /** RewardWallet.WALLET_TRANSFER_GAS (v1 pool sell). */
+    readonly walletTransfer: 100000000n;
+    /** v1 pool sell: forward TON so a refused sale can return the coins. */
+    readonly poolSellForward: 150000000n;
+    /** Safety margin added on sells (refunded). */
+    readonly margin: 30000000n;
+};
+/** Exit codes worth showing to a user (contracts/common/errors.tolk). */
+export declare const ExitCode: {
+    readonly NotFromOwner: 402;
+    readonly InsufficientValue: 410;
+    readonly BudgetExceeded: 451;
+    readonly SettleInFlight: 476;
+    readonly CurveNotOpen: 478;
+    readonly SlippageExceeded: 479;
+    readonly BelowMinTrade: 480;
+    readonly PoolEmpty: 491;
+};
+/** Event topics (248-bit value in the external out-message destination). */
+export declare const Topic: {
+    readonly LaunchCreated: 1178722305n;
+    readonly CurveTrade: 1129701377n;
+    readonly CurveGraduated: 1129701378n;
+    readonly PoolSwap: 1347411969n;
+    readonly PoolRefund: 1347411970n;
+    readonly FeeSplit: 1179901953n;
+};
+/** Mainnet core accounts (also served live by GET https://onrank.lol/api/config). */
+export declare const MAINNET: {
+    readonly factory: "EQB18IIqz56m9AAwNpX0Ai61_LNa4yquhT3QRNk4geiLwdhA";
+    readonly pot: "EQCpS9EiKrk0W7pCEybeKiCbzLL1b-CSTeiHHgVGKCQD5Mc1";
+    readonly potRelay: "EQBv-rQifdeTG6AMWw9OEp9x9YLEBGs__tkWj5sy8ulgiOFT";
+    readonly minter: "EQBAUS2t-elNMrkdZtv7Tl1pMZhTJrZqdogyCK-2UxmjjPzu";
+    readonly collection: "EQBKCClSs3RhzCXqQrLf8uyUPUBuCmU4P4YGY51tJyNMYgMe";
+    readonly buyback: "EQBtLFO9DvXI6WV0uraqVWu6qH8o7gQbk6Awfxg7Kj8Z_phO";
+    readonly usdt: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+    readonly api: "https://onrank.lol";
+};
+/** Code hashes (base64) of the deployed v2 contracts — compare before trusting an address. */
+export declare const CODE_HASH: {
+    readonly FactoryV2: "UhyECvtffP/+4hoszJv5w2jH21HAO81k0g4e78RWqBk=";
+    readonly CurveV2: "x1+u3TP0Q7h7k/X9GByNy6WqOCvnJ4KVL1hR7t2tWcM=";
+    readonly PoolV2: "4yPKye3U58+n21m6EC5vdwvii5A10umUOjjR2elP9t8=";
+    readonly RewardMasterV2: "XSZIxXypgXYGEwADqjEcTRTu9mXqu1xb+z7Vu/3fjBw=";
+    readonly RewardWalletV2: "qahjc6e276BatQUKZ9wJ4iuKe6Crnv0FbCXcSR+Kr+A=";
+    readonly FeeSplitterV2: "5cXxuRBVXd5tEU3TKojemQ9zzEEwo1hpLnkjnCiDSO4=";
+    readonly RewardVaultV2: "vzEyUk5gEDQxHIfokjDqvgmuwFsOQnnKwpyBrIVRE/A=";
+    readonly Pot: "lxv0tCBCh1oQk0f5oBU0KCTmebivPtMicSoSp5h4Phw=";
+    readonly PotRelay: "h7MamCDtM7iPXwEquvm5JaSgCAHLgf3EkVq8Y7Zz2tY=";
+    readonly DeskMinter: "QdIxvaBs/3OE7xHOPy4bPP5SzHtMBriVW+TywiLifxA=";
+    readonly DeskCollection: "LHhgnY0QJjXpBWNkpYjjCJK1elxludK0gBHdLq4IYeU=";
+    readonly BuybackVault: "WXP9MVAA2AT/dITksu2ewZGJo9hdBlV7LAeG/s6C9Xo=";
+};
+/** Launcher family of a coin: v1 coins are sell-only and use a different pool sell path. */
+export type LauncherVersion = 1 | 2;

package/dist/constants.js

@@ -0,0 +1,80 @@
+/** Opcodes of the messages an integrator sends (launcher v2 contracts; v1 shares them). */
+export const Op = {
+    /** Curve: buy with the attached TON minus BUY_GAS. */
+    Buy: 0x43550002,
+    /** Pool: buy with the attached TON minus SWAP_GAS. */
+    SwapTonForCoin: 0x504f0001,
+    /** v1 pool only: forward payload of a TEP-74 transfer to the pool. */
+    SwapCoinForTon: 0x504f0002,
+    /** TEP-74 transfer (v1 pool sell). */
+    Transfer: 0x0f8a7ea5,
+    /** TEP-74 burn on the user's RewardWallet — with a SellIntent payload it is a sale. */
+    Burn: 0x595f07bc,
+    /** Burn custom payload: sell for at least `minTon`. */
+    SellIntent: 0x52570018,
+};
+/** Gas the contracts require (nanoTON). Excess is refunded by the contracts; a margin costs nothing. */
+export const Gas = {
+    /** Curve.BUY_GAS — deducted from the attached value before the swap. */
+    curveBuy: 150000000n,
+    /** Pool.SWAP_GAS (v1). */
+    poolSwapV1: 200000000n,
+    /** PoolV2.SWAP_GAS. */
+    poolSwapV2: 150000000n,
+    /** RewardWallet.WALLET_BURN_GAS (v1). */
+    walletBurnV1: 120000000n,
+    /** RewardWalletV2.WALLET_BURN_GAS. */
+    walletBurnV2: 160000000n,
+    /** RewardWallet.WALLET_TRANSFER_GAS (v1 pool sell). */
+    walletTransfer: 100000000n,
+    /** v1 pool sell: forward TON so a refused sale can return the coins. */
+    poolSellForward: 150000000n,
+    /** Safety margin added on sells (refunded). */
+    margin: 30000000n,
+};
+/** Exit codes worth showing to a user (contracts/common/errors.tolk). */
+export const ExitCode = {
+    NotFromOwner: 402,
+    InsufficientValue: 410,
+    BudgetExceeded: 451,
+    SettleInFlight: 476,
+    CurveNotOpen: 478,
+    SlippageExceeded: 479,
+    BelowMinTrade: 480,
+    PoolEmpty: 491,
+};
+/** Event topics (248-bit value in the external out-message destination). */
+export const Topic = {
+    LaunchCreated: 0x4641e001n,
+    CurveTrade: 0x4355e001n,
+    CurveGraduated: 0x4355e002n,
+    PoolSwap: 0x504fe001n,
+    PoolRefund: 0x504fe002n,
+    FeeSplit: 0x4653e001n,
+};
+/** Mainnet core accounts (also served live by GET https://onrank.lol/api/config). */
+export const MAINNET = {
+    factory: "EQB18IIqz56m9AAwNpX0Ai61_LNa4yquhT3QRNk4geiLwdhA",
+    pot: "EQCpS9EiKrk0W7pCEybeKiCbzLL1b-CSTeiHHgVGKCQD5Mc1",
+    potRelay: "EQBv-rQifdeTG6AMWw9OEp9x9YLEBGs__tkWj5sy8ulgiOFT",
+    minter: "EQBAUS2t-elNMrkdZtv7Tl1pMZhTJrZqdogyCK-2UxmjjPzu",
+    collection: "EQBKCClSs3RhzCXqQrLf8uyUPUBuCmU4P4YGY51tJyNMYgMe",
+    buyback: "EQBtLFO9DvXI6WV0uraqVWu6qH8o7gQbk6Awfxg7Kj8Z_phO",
+    usdt: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
+    api: "https://onrank.lol",
+};
+/** Code hashes (base64) of the deployed v2 contracts — compare before trusting an address. */
+export const CODE_HASH = {
+    FactoryV2: "UhyECvtffP/+4hoszJv5w2jH21HAO81k0g4e78RWqBk=",
+    CurveV2: "x1+u3TP0Q7h7k/X9GByNy6WqOCvnJ4KVL1hR7t2tWcM=",
+    PoolV2: "4yPKye3U58+n21m6EC5vdwvii5A10umUOjjR2elP9t8=",
+    RewardMasterV2: "XSZIxXypgXYGEwADqjEcTRTu9mXqu1xb+z7Vu/3fjBw=",
+    RewardWalletV2: "qahjc6e276BatQUKZ9wJ4iuKe6Crnv0FbCXcSR+Kr+A=",
+    FeeSplitterV2: "5cXxuRBVXd5tEU3TKojemQ9zzEEwo1hpLnkjnCiDSO4=",
+    RewardVaultV2: "vzEyUk5gEDQxHIfokjDqvgmuwFsOQnnKwpyBrIVRE/A=",
+    Pot: "lxv0tCBCh1oQk0f5oBU0KCTmebivPtMicSoSp5h4Phw=",
+    PotRelay: "h7MamCDtM7iPXwEquvm5JaSgCAHLgf3EkVq8Y7Zz2tY=",
+    DeskMinter: "QdIxvaBs/3OE7xHOPy4bPP5SzHtMBriVW+TywiLifxA=",
+    DeskCollection: "LHhgnY0QJjXpBWNkpYjjCJK1elxludK0gBHdLq4IYeU=",
+    BuybackVault: "WXP9MVAA2AT/dITksu2ewZGJo9hdBlV7LAeG/s6C9Xo=",
+};

package/dist/decode.d.ts

@@ -0,0 +1,56 @@
+import { Address, Cell, type ExternalAddress, type TupleItem } from "@ton/core";
+import type { CurveState, PoolState } from "./quotes.js";
+/** `get_curve_data` → the six fields the quotes need (roles / params cells are left on the stack). */
+export declare function decodeCurveData(items: TupleItem[]): CurveState;
+/** `get_pool_data`. */
+export declare function decodePoolData(items: TupleItem[]): PoolState;
+/** `get_buy_quote` / `get_sell_quote` → `(amountOut, fee)`. */
+export declare function decodeQuote(items: TupleItem[]): {
+    amountOut: bigint;
+    fee: bigint;
+};
+export type TradeEvent = {
+    kind: "CurveTrade";
+    isBuy: boolean;
+    trader: string;
+    ton: bigint;
+    coin: bigint;
+    fee: bigint;
+    virtualTon: bigint;
+    virtualToken: bigint;
+    realTon: bigint;
+} | {
+    kind: "PoolSwap";
+    isBuy: boolean;
+    trader: string;
+    ton: bigint;
+    coin: bigint;
+    lpFee: bigint;
+    protocolFee: bigint;
+    reserveTon: bigint;
+    reserveCoin: bigint;
+} | {
+    kind: "CurveGraduated";
+    pool: string;
+    liquidityTon: bigint;
+    liquidityCoin: bigint;
+    protocolFee: bigint;
+} | {
+    kind: "LaunchCreated";
+    seq: bigint;
+    creator: string;
+    master: string;
+    vault: string;
+    splitter: string;
+    curve: string;
+    rewardCount: number;
+    firstBuyTon: bigint;
+    codeVersion: number;
+    preminted: bigint;
+};
+/** Topic of an external out-message destination, or null when it is not an ONRANK log. */
+export declare function topicOf(dest: ExternalAddress | null | undefined): bigint | null;
+/** Decodes the trading-relevant events; returns null for other topics. Throws on a malformed body. */
+export declare function decodeTradeEvent(topic: bigint, body: Cell): TradeEvent | null;
+/** Address helper: accepts raw (`0:…`) or friendly forms. */
+export declare function parseAddress(a: string): Address;

package/dist/decode.js

@@ -0,0 +1,68 @@
+// Decoders for get-method results and events. Get-method stacks are `TupleItem[]` as returned by @ton/ton /
+// @ton/core's TupleReader (toncenter v2 `runGetMethod` stacks need the usual num/cell conversion first).
+import { Address, TupleReader } from "@ton/core";
+import { Topic } from "./constants.js";
+function optAddress(r) {
+    const item = r.peek();
+    if (item.type === "null") {
+        r.pop();
+        return null;
+    }
+    return r.readAddress().toString();
+}
+/** `get_curve_data` → the six fields the quotes need (roles / params cells are left on the stack). */
+export function decodeCurveData(items) {
+    const r = new TupleReader(items);
+    return { state: r.readNumber(), virtualTon: r.readBigNumber(), virtualToken: r.readBigNumber(), realTon: r.readBigNumber(), sold: r.readBigNumber(), pool: optAddress(r) };
+}
+/** `get_pool_data`. */
+export function decodePoolData(items) {
+    const r = new TupleReader(items);
+    return { reserveTon: r.readBigNumber(), reserveCoin: r.readBigNumber(), lpFeeBps: r.readNumber(), protocolFeeBps: r.readNumber(), volumeTon: r.readBigNumber(), nonce: r.readBigNumber(), master: r.readAddress().toString(), splitter: r.readAddress().toString() };
+}
+/** `get_buy_quote` / `get_sell_quote` → `(amountOut, fee)`. */
+export function decodeQuote(items) {
+    const r = new TupleReader(items);
+    return { amountOut: r.readBigNumber(), fee: r.readBigNumber() };
+}
+/** Topic of an external out-message destination, or null when it is not an ONRANK log. */
+export function topicOf(dest) {
+    if (!dest || dest.bits !== 256)
+        return null;
+    if (dest.value >> 248n !== 0n)
+        return null;
+    return dest.value;
+}
+/** Decodes the trading-relevant events; returns null for other topics. Throws on a malformed body. */
+export function decodeTradeEvent(topic, body) {
+    const s = body.beginParse();
+    switch (topic) {
+        case Topic.CurveTrade:
+            return { kind: "CurveTrade", isBuy: s.loadBit(), trader: s.loadAddress().toString(), ton: s.loadCoins(), coin: s.loadCoins(), fee: s.loadCoins(), virtualTon: s.loadCoins(), virtualToken: s.loadCoins(), realTon: s.loadCoins() };
+        case Topic.PoolSwap:
+            return { kind: "PoolSwap", isBuy: s.loadBit(), trader: s.loadAddress().toString(), ton: s.loadCoins(), coin: s.loadCoins(), lpFee: s.loadCoins(), protocolFee: s.loadCoins(), reserveTon: s.loadCoins(), reserveCoin: s.loadCoins() };
+        case Topic.CurveGraduated:
+            return { kind: "CurveGraduated", pool: s.loadAddress().toString(), liquidityTon: s.loadCoins(), liquidityCoin: s.loadCoins(), protocolFee: s.loadCoins() };
+        case Topic.LaunchCreated: {
+            const seq = s.loadUintBig(64);
+            const creator = s.loadAddress().toString();
+            const addrs = s.loadRef().beginParse();
+            const master = addrs.loadAddress().toString();
+            const vault = addrs.loadAddress().toString();
+            const more = addrs.loadRef().beginParse();
+            const splitter = more.loadAddress().toString();
+            const curve = more.loadAddress().toString();
+            const rewardCount = s.loadUint(8);
+            const firstBuyTon = s.loadCoins();
+            const codeVersion = s.remainingBits >= 16 ? s.loadUint(16) : 1;
+            const preminted = s.remainingBits >= 4 ? s.loadCoins() : 0n;
+            return { kind: "LaunchCreated", seq, creator, master, vault, splitter, curve, rewardCount, firstBuyTon, codeVersion, preminted };
+        }
+        default:
+            return null;
+    }
+}
+/** Address helper: accepts raw (`0:…`) or friendly forms. */
+export function parseAddress(a) {
+    return a.includes(":") ? Address.parseRaw(a) : Address.parse(a);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./constants.js";
+export * from "./messages.js";
+export * from "./quotes.js";
+export * from "./decode.js";
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// @onrank/sdk — quote and trade ONRANK coins from any product. Pure builders (no keys, no network); the optional
+// `OnrankClient` in ./client.ts adds toncenter reads and the public REST API.
+export * from "./constants.js";
+export * from "./messages.js";
+export * from "./quotes.js";
+export * from "./decode.js";
+export * from "./client.js";

package/dist/messages.d.ts

@@ -0,0 +1,57 @@
+import { Address } from "@ton/core";
+import { type LauncherVersion } from "./constants.js";
+/** What a wallet expects: destination, nanoTON to attach (decimal string), base64 BoC body. */
+export type TonConnectMessage = {
+    address: string;
+    amount: string;
+    payload: string;
+};
+/** Any 64-bit query id; the default is time-based, good enough to tell transactions apart in a wallet history. */
+export declare function defaultQueryId(): bigint;
+/**
+ * Buy on the curve. `tonIn` is what gets swapped; the message attaches `tonIn + Gas.curveBuy`.
+ * `minOut`: minimum coins accepted (quote × (1 − slippage)); the curve refunds everything below it (exit 479).
+ * `recipient` defaults to the signer — leave it unset unless you intentionally buy for someone else.
+ */
+export declare function buildCurveBuy(p: {
+    curve: Address;
+    tonIn: bigint;
+    minOut: bigint;
+    queryId?: bigint;
+    recipient?: Address;
+}): TonConnectMessage;
+/** Buy on the pool after graduation. Attaches `tonIn + SWAP_GAS` (0.15 TON on v2, 0.2 on v1). */
+export declare function buildPoolBuy(p: {
+    pool: Address;
+    tonIn: bigint;
+    minOut: bigint;
+    queryId?: bigint;
+    version?: LauncherVersion;
+}): TonConnectMessage;
+/**
+ * Sell on the curve **or** the v2 pool: a burn on the owner's RewardWallet with a SellIntent. The master routes it to
+ * whichever market is live and pays `owner` in TON; a refused sale re-mints the coins to `owner`.
+ * `rewardWallet` = `get_wallet_address(owner)` on the coin's master. `minTon`: minimum TON accepted.
+ */
+export declare function buildSell(p: {
+    rewardWallet: Address;
+    owner: Address;
+    coinAmount: bigint;
+    minTon: bigint;
+    queryId?: bigint;
+    version?: LauncherVersion;
+}): TonConnectMessage;
+/**
+ * v1 pool sell only (legacy coins): TEP-74 transfer of the coins to the pool with a SwapCoinForTon forward payload.
+ * v2 pools take `buildSell` instead.
+ */
+export declare function buildPoolSellV1(p: {
+    rewardWallet: Address;
+    pool: Address;
+    owner: Address;
+    coinAmount: bigint;
+    minTon: bigint;
+    queryId?: bigint;
+}): TonConnectMessage;
+/** `quote × (10000 − slippageBps) / 10000`, floored — the value to pass as minOut / minTon. */
+export declare function applySlippage(quote: bigint, slippageBps: number): bigint;

package/dist/messages.js

@@ -0,0 +1,74 @@
+// Unsigned messages, ready for TON Connect `sendTransaction({ messages: [msg] })`. Pure functions: no network, no keys.
+// Layouts mirror the contracts (contracts/contracts/launcher-v2/*.tolk) bit for bit.
+import { beginCell } from "@ton/core";
+import { Gas, Op } from "./constants.js";
+const boc = (c) => c.toBoc().toString("base64");
+const msg = (to, amount, body) => ({ address: to.toString({ bounceable: true }), amount: amount.toString(), payload: boc(body) });
+/** Any 64-bit query id; the default is time-based, good enough to tell transactions apart in a wallet history. */
+export function defaultQueryId() {
+    return (BigInt(Date.now()) << 20n) | BigInt(Math.floor(Math.random() * 0xfffff));
+}
+/**
+ * Buy on the curve. `tonIn` is what gets swapped; the message attaches `tonIn + Gas.curveBuy`.
+ * `minOut`: minimum coins accepted (quote × (1 − slippage)); the curve refunds everything below it (exit 479).
+ * `recipient` defaults to the signer — leave it unset unless you intentionally buy for someone else.
+ */
+export function buildCurveBuy(p) {
+    if (p.tonIn <= 0n)
+        throw new Error("tonIn must be > 0");
+    if (p.minOut <= 0n)
+        throw new Error("minOut must be > 0 (never trade without slippage protection)");
+    const body = beginCell().storeUint(Op.Buy, 32).storeUint(p.queryId ?? defaultQueryId(), 64).storeCoins(p.minOut).storeAddress(p.recipient ?? null).endCell();
+    return msg(p.curve, p.tonIn + Gas.curveBuy, body);
+}
+/** Buy on the pool after graduation. Attaches `tonIn + SWAP_GAS` (0.15 TON on v2, 0.2 on v1). */
+export function buildPoolBuy(p) {
+    if (p.tonIn <= 0n)
+        throw new Error("tonIn must be > 0");
+    if (p.minOut <= 0n)
+        throw new Error("minOut must be > 0 (never trade without slippage protection)");
+    const body = beginCell().storeUint(Op.SwapTonForCoin, 32).storeUint(p.queryId ?? defaultQueryId(), 64).storeCoins(p.minOut).endCell();
+    return msg(p.pool, p.tonIn + ((p.version ?? 2) === 2 ? Gas.poolSwapV2 : Gas.poolSwapV1), body);
+}
+/**
+ * Sell on the curve **or** the v2 pool: a burn on the owner's RewardWallet with a SellIntent. The master routes it to
+ * whichever market is live and pays `owner` in TON; a refused sale re-mints the coins to `owner`.
+ * `rewardWallet` = `get_wallet_address(owner)` on the coin's master. `minTon`: minimum TON accepted.
+ */
+export function buildSell(p) {
+    if (p.coinAmount <= 0n)
+        throw new Error("coinAmount must be > 0");
+    if (p.minTon <= 0n)
+        throw new Error("minTon must be > 0 (never trade without slippage protection)");
+    const intent = beginCell().storeUint(Op.SellIntent, 32).storeCoins(p.minTon).endCell();
+    const body = beginCell().storeUint(Op.Burn, 32).storeUint(p.queryId ?? defaultQueryId(), 64).storeCoins(p.coinAmount).storeAddress(p.owner).storeMaybeRef(intent).endCell();
+    return msg(p.rewardWallet, ((p.version ?? 2) === 2 ? Gas.walletBurnV2 : Gas.walletBurnV1) + Gas.margin, body);
+}
+/**
+ * v1 pool sell only (legacy coins): TEP-74 transfer of the coins to the pool with a SwapCoinForTon forward payload.
+ * v2 pools take `buildSell` instead.
+ */
+export function buildPoolSellV1(p) {
+    if (p.coinAmount <= 0n)
+        throw new Error("coinAmount must be > 0");
+    if (p.minTon <= 0n)
+        throw new Error("minTon must be > 0");
+    const swap = beginCell().storeUint(Op.SwapCoinForTon, 32).storeCoins(p.minTon).endCell();
+    const body = beginCell()
+        .storeUint(Op.Transfer, 32)
+        .storeUint(p.queryId ?? defaultQueryId(), 64)
+        .storeCoins(p.coinAmount)
+        .storeAddress(p.pool)
+        .storeAddress(p.owner)
+        .storeMaybeRef(null)
+        .storeCoins(Gas.poolSellForward)
+        .storeMaybeRef(swap)
+        .endCell();
+    return msg(p.rewardWallet, Gas.poolSellForward + Gas.walletTransfer + Gas.margin, body);
+}
+/** `quote × (10000 − slippageBps) / 10000`, floored — the value to pass as minOut / minTon. */
+export function applySlippage(quote, slippageBps) {
+    if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps >= 10_000)
+        throw new Error("slippageBps must be an integer in [0, 10000)");
+    return (quote * BigInt(10_000 - slippageBps)) / 10000n;
+}

package/dist/quotes.d.ts

@@ -0,0 +1,57 @@
+export type Quote = {
+    amountOut: bigint;
+    fee: bigint;
+};
+/** What `get_curve_data` returns (first six fields; roles and params are cells). */
+export type CurveState = {
+    /** 1 = open (trades accepted); anything else: not opened yet or graduated */
+    state: number;
+    virtualTon: bigint;
+    virtualToken: bigint;
+    /** TON really held by the curve (what backs sells) */
+    realTon: bigint;
+    /** coins sold so far (out of `curveSupply`) */
+    sold: bigint;
+    /** set at graduation */
+    pool: string | null;
+};
+/** Curve parameters that the formulas need (Factory defaults on mainnet: feeBps 100, curveSupply 800 M coins). */
+export type CurveParams = {
+    feeBps: number;
+    curveSupply: bigint;
+};
+export declare const MAINNET_CURVE_PARAMS: CurveParams;
+/**
+ * Coins received for `tonAttached` sent to the curve (BUY_GAS is deducted here, like `get_buy_quote`).
+ * Returns amountOut 0 when the attached value does not cover the gas.
+ */
+export declare function quoteCurveBuy(s: CurveState, tonAttached: bigint, params?: CurveParams): Quote;
+/** Same as `quoteCurveBuy` but from the amount you want swapped (the message attaches gas on top). */
+export declare function quoteCurveBuyForTonIn(s: CurveState, tonIn: bigint, params?: CurveParams): Quote;
+/** Net TON received for selling `coinIn` on the curve (`get_sell_quote`). The contract also needs gross ≤ realTon. */
+export declare function quoteCurveSell(s: CurveState, coinIn: bigint, params?: CurveParams): Quote;
+/** Whether the curve can still sell: open and not graduated. */
+export declare function isCurveOpen(s: CurveState): boolean;
+/** What `get_pool_data` returns. */
+export type PoolState = {
+    reserveTon: bigint;
+    reserveCoin: bigint;
+    lpFeeBps: number;
+    protocolFeeBps: number;
+    volumeTon: bigint;
+    nonce: bigint;
+    master: string;
+    splitter: string;
+};
+/** Coins received for `tonIn` (after SWAP_GAS) on the pool (`get_buy_quote`). */
+export declare function quotePoolBuy(p: PoolState, tonIn: bigint): Quote;
+/** Net TON received for `coinIn` on the pool (`get_sell_quote`). */
+export declare function quotePoolSell(p: PoolState, coinIn: bigint): Quote;
+/** Spot price in nanoTON per whole coin (1e9 units), from either market's reserves. */
+export declare function spotPriceNano(s: {
+    virtualTon: bigint;
+    virtualToken: bigint;
+} | {
+    reserveTon: bigint;
+    reserveCoin: bigint;
+}): bigint;

package/dist/quotes.js

@@ -0,0 +1,69 @@
+// Quote formulas copied from the contracts (CurveV2.tolk, PoolV2.tolk). Integer arithmetic on bigint, same rounding.
+// Pin them with the fixtures in test/quotes.test.ts (live get_buy_quote / get_sell_quote results).
+import { Gas } from "./constants.js";
+export const MAINNET_CURVE_PARAMS = { feeBps: 100, curveSupply: 800000000n * 1000000000n };
+const coinOut = (s, tonIn) => (s.virtualToken * tonIn) / (s.virtualTon + tonIn);
+const tonInFor = (s, out) => {
+    const num = s.virtualTon * out;
+    const den = s.virtualToken - out;
+    return (num + den - 1n) / den;
+};
+const tonOut = (s, coinIn) => (s.virtualTon * coinIn) / (s.virtualToken + coinIn);
+const feeOnNet = (net, feeBps) => (net * BigInt(feeBps)) / BigInt(10_000 - feeBps);
+const min = (a, b) => (a < b ? a : b);
+/**
+ * Coins received for `tonAttached` sent to the curve (BUY_GAS is deducted here, like `get_buy_quote`).
+ * Returns amountOut 0 when the attached value does not cover the gas.
+ */
+export function quoteCurveBuy(s, tonAttached, params = MAINNET_CURVE_PARAMS) {
+    if (tonAttached <= Gas.curveBuy)
+        return { amountOut: 0n, fee: 0n };
+    const amountIn = tonAttached - Gas.curveBuy;
+    let fee = (amountIn * BigInt(params.feeBps)) / 10000n;
+    let out = coinOut(s, amountIn - fee);
+    const remaining = params.curveSupply - s.sold;
+    if (out > remaining) {
+        // last lot: the buyer pays exactly what those coins cost, fee included; the rest is refunded by the contract
+        out = remaining;
+        const net = tonInFor(s, out);
+        fee = min(feeOnNet(net, params.feeBps), amountIn - net);
+    }
+    return { amountOut: out, fee };
+}
+/** Same as `quoteCurveBuy` but from the amount you want swapped (the message attaches gas on top). */
+export function quoteCurveBuyForTonIn(s, tonIn, params = MAINNET_CURVE_PARAMS) {
+    return quoteCurveBuy(s, tonIn + Gas.curveBuy, params);
+}
+/** Net TON received for selling `coinIn` on the curve (`get_sell_quote`). The contract also needs gross ≤ realTon. */
+export function quoteCurveSell(s, coinIn, params = MAINNET_CURVE_PARAMS) {
+    const gross = tonOut(s, coinIn);
+    const fee = (gross * BigInt(params.feeBps)) / 10000n;
+    return { amountOut: gross - fee, fee };
+}
+/** Whether the curve can still sell: open and not graduated. */
+export function isCurveOpen(s) {
+    return s.state === 1 && s.pool === null;
+}
+/** Coins received for `tonIn` (after SWAP_GAS) on the pool (`get_buy_quote`). */
+export function quotePoolBuy(p, tonIn) {
+    const lpFee = (tonIn * BigInt(p.lpFeeBps)) / 10000n;
+    const protocolFee = (tonIn * BigInt(p.protocolFeeBps)) / 10000n;
+    const net = tonIn - lpFee - protocolFee;
+    if (p.reserveCoin === 0n)
+        return { amountOut: 0n, fee: lpFee + protocolFee };
+    return { amountOut: (p.reserveCoin * net) / (p.reserveTon + net), fee: lpFee + protocolFee };
+}
+/** Net TON received for `coinIn` on the pool (`get_sell_quote`). */
+export function quotePoolSell(p, coinIn) {
+    if (p.reserveCoin === 0n)
+        return { amountOut: 0n, fee: 0n };
+    const gross = (p.reserveTon * coinIn) / (p.reserveCoin + coinIn);
+    const lpFee = (gross * BigInt(p.lpFeeBps)) / 10000n;
+    const protocolFee = (gross * BigInt(p.protocolFeeBps)) / 10000n;
+    return { amountOut: gross - lpFee - protocolFee, fee: lpFee + protocolFee };
+}
+/** Spot price in nanoTON per whole coin (1e9 units), from either market's reserves. */
+export function spotPriceNano(s) {
+    const [ton, coin] = "virtualTon" in s ? [s.virtualTon, s.virtualToken] : [s.reserveTon, s.reserveCoin];
+    return coin === 0n ? 0n : (ton * 1000000000n) / coin;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@onrank/sdk",
+  "version": "0.1.0",
+  "description": "ONRANK (TON launchpad) integration SDK: on-chain quotes and unsigned TON Connect messages for buying and selling coins on the curve and the pool. No keys, no network required.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@ton/core": ">=0.56.0"
+  },
+  "devDependencies": {
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ton",
+    "onrank",
+    "launchpad",
+    "bonding-curve",
+    "ton-connect",
+    "trading-bot"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SOLEIIL/onrank-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://onrank.lol/developers",
+  "bugs": {
+    "url": "https://github.com/SOLEIIL/onrank-sdk/issues"
+  }
+}