• Reading the docs…
Start trading

SDK

Reference bot

A Telegram bot that trades a Privium account from a trade key, built on the SDK and open source in backend/bot. Each user links the trade key and view their account issued on Account under Trade keys, and the bot buys, sells, cancels and reads balances and fills for them. No command moves funds out: a trade key cannot (Privium inside a terminal or bot).

Commands#

Command What it does
/link <tradeKey> <view> Connects the account. The bot stores both sealed and deletes the message from the chat.
/balances The account’s balances, read through the view.
/buy <BASE/QUOTE> <size> [limit] A buy for the next Crossing; at market without a limit.
/sell <BASE/QUOTE> <size> [limit] A sell, the same way.
/orders Open orders with their numbers.
/cancel <number> Cancels an open order.
/fills The last fills. Each fill is also sent as it lands.
/unlink Forgets the account in the bot. Revoking the key on Account retires it everywhere.

The bot answers only in private chats. A trade past the key’s cap, or outside its scope, comes back as intake’s refusal in words.

Run it#

Run
TELEGRAM_BOT_TOKEN=<from @BotFather> BOT_SEAL_KEY=<64 hex characters> npx tsx bot/src/main.ts
Variable Meaning
TELEGRAM_BOT_TOKEN The bot’s token from @BotFather.
BOT_SEAL_KEY 32 bytes of hex. Linked keys are stored AES-256-GCM sealed under it, each bound to its Telegram user.
BOT_STORE_FILE Where the sealed keys live. Default linked.json.
PRIVIUM_API_URL The API, https://api.privium.io by default.
BOT_INTEGRATOR_ID, BOT_INTEGRATOR_BPS The operator’s integrator id, privium.integratorId on the operator’s own account, and its rate, up to 100 bps. The fee reaches the operator’s Privium account in the same Commit as each fill (Integrator fees).

How it works#

src/bot.ts is the whole behaviour apart from Telegram: createBot({ apiUrl, store, notify, integrator }) returns handle(user, text). Each linked user gets one Privium.connect({ apiUrl, tradeKey, view, integrator }) instance, and the bot watches its fills with watchFills, which the enclave seals to the trade key’s own reply key. src/main.ts is the Telegram transport, polling getUpdates, and src/store.ts holds the sealed file store. Another terminal or bot follows the same shape: one instance per linked key, and the integrator option set once.