Skip to main content
The Ostium SDK is the current TypeScript client for reading Ostium market data, building mode-correct transactions, and submitting trading actions. Current package: @ostium/builder-sdk@0.9.0. See the Changelog for what it adds and the three behaviour changes to know about before upgrading.

​
Install

​
Core SDK surfaces

  • client creation methods for each execution mode
  • build-only transaction helpers for client-side signing
  • SDK-managed write methods for direct submission
  • read methods backed by the subgraph and builder API
  • live streams for prices, positions, and low-latency account confirmations
  • pre-trade previews for order and close tickets, derived from the same math the contracts run
  • a subscribable store that keeps pairs, prices and positions current for you
Client construction is lazy: factories no longer pre-fetch the full pair list from the subgraph. Read methods populate market metadata on first use. Gasless submit-capable factories accept an optional known safeAddress to skip the smart-account derivation call during construction.

​
Method index

​
Client creation

  • createSelfAndSelf
  • createSelfAndGasless
  • createDelegatedAndSelf
  • createDelegatedAndGasless
  • createReadOnly
See Client Configuration for every parameter these factories accept.

​
Previews and limits

  • previewOpenTrade
  • previewCloseTrade
  • getMaxCollateral
  • getOnboardingStatus
  • getVaultBalance
Everything an order or close ticket needs before a trade is signed: execution price after spread, fees, resulting liquidation price, what a Max button should fill in, and what still stands between a trader and their first trade.

​
Live state

  • createStore
  • PAIR_SNAPSHOT
  • selectPosition, selectPositionsForPair, selectPrice, selectPair, selectPairMeta, selectMarkets, selectPositionsNearLiquidation, memoSelector
createStore() holds pairs, live prices and positions in one subscribable object and keeps them current. Its getState/subscribe pair matches React’s useSyncExternalStore.

​
Standalone math

  • liquidationPrice
  • pnl
  • rolloverFee
Pure functions over plain numbers, for bots and backtesters. See Math helpers.

​
Helpers

  • canBuildTransactions
  • canSubmitTransactions
  • getTraderAddress
  • isReadOnly
  • getSmartAccountAddress
  • checkUsdcAllowance
  • getBalances
  • extractOrderIdFromReceipt

​
Utilities and constants

  • parseUsdc
  • parsePrice
  • parseLeverage
  • MIN_OPEN_SIZE_USD
  • MIN_COLLATERAL_USD
  • MAX_COLLATERAL_USD

​
Read methods

  • getPairs
  • getAllPrices
  • getOpenPositions
  • getOpenOrders
  • getOrders
  • getBuilderOrders
  • getFills
  • getFillsByTime
  • getSimSlippage
  • getSimOrderbook
  • getCandles
  • getVaultBalance
  • streamPrices
  • streamPositionUpdates
  • streamAccountUpdates

​
Transaction builders

  • getSetupGaslessDelegationTx
  • getApproveUsdcTx
  • getSetDelegateTx
  • getRemoveDelegateTx
  • getOpenTradeTx
  • getCloseTradeTx
  • getCancelOrderTx
  • getModifyOrderTx
  • getUpdateCollateralTx

​
Write methods

  • approveUsdc
  • setupGaslessDelegation
  • setDelegate
  • removeDelegate
  • openTrade
  • closeTrade
  • modifyOrder
  • updateCollateral
  • cancelOrder

​
Build vs submit

Every write action now has two SDK surfaces:
  • get*Tx() returns unsigned transaction data for wallet-driven or Safe-driven client applications
  • the write method (openTrade, closeTrade, approveUsdc, and so on) signs and submits through the configured mode when the client was created with credentials
For example:
In gasless build-only modes, the same get*Tx() methods return a Safe-style request instead of an EOA request.

​
Guides

If you want implementation examples instead of method reference, use the guides section:

​
Examples

Three runnable programs ship with the package: See Examples for what each one covers and how to run it. The same page lists the llms.txt and Claude skill files shipped for AI coding agents.

​
Error handling

See Errors for the exported OstiumError, OstiumSubgraphError, OstiumSubmissionPendingError, and their error codes.

​
Changelog

See Changelog for the versioned SDK changes, including the 0.8.0 preview and gasless-submission work and the 0.9.0 store, rollover and reconnect additions.