ostium-ts-sdk

TypeScript SDK for the Ostium decentralized perpetuals trading platform on Arbitrum.

Features

• Trading — Open, close, and modify positions (TP/SL, collateral, leverage) with market, limit, and stop orders
• Subgraph queries — Fetch open trades, limit orders, order history, pair details, and more
• Live prices — Real-time bid/ask/mid prices and market status
• Trade metrics — PnL, funding fees, rollover fees, liquidation price, and price impact calculations
• Balances — On-chain USDC balance reads
• Testnet faucet — Claim testnet USDC

Installation

bun add ostium-ts-sdk

Quick start

import { OstiumSDK } from "ostium-ts-sdk";

const sdk = new OstiumSDK("mainnet", process.env.PRIVATE_KEY, process.env.RPC_URL);

// List all trading pairs with live prices
const pairs = await sdk.getFormattedPairsDetails();
console.log(pairs);

// Get open trades for the connected wallet
const [trades, address] = await sdk.getOpenTrades();
console.log(`${address} has ${trades.length} open trades`);

// Open a long position: 100 USDC collateral, 10x leverage, pair 0 (e.g. BTC/USD)
const result = await sdk.ostium.performTrade({
  collateral: 100,
  leverage: 10,
  asset_type: 0,
  direction: true, // true = long, false = short
});

// Get trade metrics (PnL, fees, liquidation price)
const metrics = await sdk.getOpenTradeMetrics(0, 0);
console.log(`PnL: ${metrics.pnl_percent}%, Liq price: ${metrics.liquidation_price}`);

Configuration

| Environment variable | Description | |---|---| | PRIVATE_KEY | Wallet private key (hex, with or without 0x prefix) | | RPC_URL | Arbitrum RPC endpoint |

Both can be passed directly to the constructor or read from environment variables automatically.

// Read-only mode (no private key needed for queries)
const sdk = new OstiumSDK("mainnet", undefined, "https://arb1.arbitrum.io/rpc");

// Testnet
const testSdk = new OstiumSDK("testnet", privateKey, rpcUrl);

// Delegation mode (trade on behalf of another address)
const sdk = new OstiumSDK("mainnet", privateKey, rpcUrl, false, true);

SDK modules

Access sub-modules directly from the SDK instance:

| Module | Access | Description | |---|---|---| | Trading | sdk.ostium | Open/close trades, update TP/SL, add/remove collateral, cancel orders, USDC approval | | Subgraph | sdk.subgraph | Query pairs, open trades, limit orders, order history | | Prices | sdk.price | Live bid/ask/mid prices and market status | | Balances | sdk.balance | On-chain USDC balance reads | | Faucet | sdk.faucet | Testnet USDC faucet (testnet only, null on mainnet) |

Trade metrics

Compute a full snapshot of an open trade's current state:

const metrics = await sdk.getOpenTradeMetrics(pairId, tradeIndex);
// metrics: { pnl, pnl_percent, rollover, funding, net_pnl, net_value,
//            liquidation_price, price_impact, is_market_open, bid, mid, ask }

Funding and rollover rates

// Funding rate for a pair (default: 24h period)
const [accLong, accShort, fundingRate, targetRate] =
  await sdk.getFundingRateForPairId(0);

// Rollover rate
const rolloverRate = await sdk.getRolloverRateForPairId(0);

Advanced: formulae exports

For custom calculations, individual formulae are exported:

import {
  GetTakeProfitPrice,
  GetStopLossPrice,
  CurrentTradeProfitP,
  GetCurrentRolloverFee,
  GetTradeFundingFee,
  getTradeLiquidationPrice,
  getTradeMetrics,
} from "ostium-ts-sdk";

Development

bun install          # Install dependencies
bun test             # Run all tests
bun run build        # Compile TypeScript
bun run typecheck    # Type check without emitting

License

See LICENSE for details.