Skip to main content

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Installation

Set up the OMY SDK in your project — dependencies, environment variables, TypeScript config, and what to vendor where. Five minutes start to finish.

Prerequisites​

  • Node 18+ (we test on 20)
  • TypeScript 5+ (the SDK is plain TypeScript, no build step needed)
  • A TON wallet for gas + signing
  • Optionally: a TonConnect-compatible wallet if you want UI-driven transaction signing (Tonkeeper, Tonhub, OpenMask)

Get the SDK​

The SDK ships as a single vendored file until mainnet. Two reasons:

  1. Audit pinning — we want the on-chain opcodes pinned to the audit-cleared version, with no risk of an npm dependency upgrade silently shifting them.
  2. Zero surprises — you can read every line. The whole file is ~250 lines.
terminal
mkdir -p src/omy
curl -L https://raw.githubusercontent.com/Omy-network/omy/main/sdk/index.ts \
 -o src/omy/index.ts

You now have src/omy/index.ts in your project. Import directly:

import {buildMeta, buildCreateAssertion, parseOracleResult} from './omy';

Dependencies​

The SDK relies on @ton/core for cell encoding. To send messages, you also need @ton/ton (HTTP RPC client) or a TonConnect adapter.

npm install @ton/core @ton/ton
# Optional: TonConnect UI for wallet flows
npm install @tonconnect/ui
 
yarn add @ton/core @ton/ton
yarn add @tonconnect/ui
 
pnpm add @ton/core @ton/ton
pnpm add @tonconnect/ui

:::info Why these versions OMY SDK is tested against @ton/core ^0.60 and @ton/ton ^15. Older versions probably work but are not part of our CI matrix. Newer versions are forward-compatible — @ton/core has been stable since 2024. :::

Environment variables​

A clean integration pattern is to keep contract addresses in environment variables, not hard-coded in source:

.env
TON_NETWORK=mainnet
TONOMY_FACTORY=...
TONOMY_RESOLVER=...
USDT_MINTER=EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Load them in your application:

src/config.ts
import {Address} from '@ton/core';

export const TONOMY_FACTORY = Address.parse(process.env.TONOMY_FACTORY!);
export const TONOMY_RESOLVER = Address.parse(process.env.TONOMY_RESOLVER!);
export const USDT_MINTER = Address.parse(process.env.USDT_MINTER!);

TypeScript configuration​

Recommended tsconfig.json settings — these match the SDK's source:

tsconfig.json
{
 "compilerOptions": {
 "target": "ES2022",
 "module": "ESNext",
 "moduleResolution": "Bundler",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true,
 "resolveJsonModule": true,
 "isolatedModules": true,
 "lib": ["ES2022", "DOM"]
 }
}

The SDK uses bigint extensively (jetton amounts, question IDs, identifiers). Make sure your target supports it (ES2020+ is fine).

Verify your setup​

A 5-line script that prints the factory's monetization config:

scripts/check.ts
import {TonClient} from '@ton/ton';
import {Address} from '@ton/core';

const client = new TonClient({endpoint: process.env.TON_RPC_ENDPOINT!});
const factory = Address.parse(process.env.TONOMY_FACTORY!);

const {stack} = await client.runMethod(factory, 'protocolFee');
console.log('Factory protocolFee:', stack.readBigNumber().toString(), 'nano');

Run it; you should see a positive protocolFee value (Phase A target = 2 USDT).

IDE setup​

The SDK is a single .ts file — every IDE auto-completes against it. No plugins needed. Recommended for .tolk consumer contracts:

  • VS Code: install the TON Language Pack for Tolk/FunC syntax highlighting and basic IntelliSense.
  • JetBrains (WebStorm, IntelliJ): the TON plugin from the marketplace adds similar support.

Project structure (suggested)​

A clean integration layout:

your-project/
├── src/
│ ├── omy/
│ │ └── index.ts ← vendored SDK
│ ├── oracle/
│ │ ├── create.ts ← your CreateAssertion wrapper
│ │ ├── propose.ts ← your propose flow
│ │ └── listen.ts ← your OracleResult handler (off-chain)
│ ├── consumer/
│ │ └── my-contract.tolk ← your Tolk consumer
│ └── config.ts
├── tests/
│ └── oracle.test.ts ← see Testing page
├── .env
├── package.json
└── tsconfig.json

You're not required to follow this — the SDK has no opinion on file layout — but separating the integration surface (src/oracle/) from the rest of your app keeps things tidy as the codebase grows.

Next​

import {DocCards, DocCard} from '@site/src/components/docs/DocCards';