Skip to main content

​
Changelog

All notable changes to @ostium/builder-sdk will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

​
[0.7.0] - 2026-07-29

​
Changed

  • Gasless key-mode factories (createSelfAndGasless, createDelegatedAndGasless) accept an optional safeAddress. Use the smart-account address from a previous client.getSmartAccountAddress() call to skip the counterfactual-address derivation eth_call and make gasless construction network-free. The address is deterministic per key and chain.
  • Client construction no longer blocks on a subgraph pair-list fetch. Pair metadata loads lazily on first use, so build-only consumers and price streams can start without waiting for a full pair cache.
  • streamPrices(pairIds) can be called immediately after client creation. If the pair list is still loading, the stream connects and applies the pair filter once pair metadata resolves.

​
Fixed

  • OpenOrder.idx from getOpenOrders() now carries the on-chain limit slot index, not the subgraph’s global order id. Pass this value directly to cancelOrder({ type: CancelOrderType.Limit }) and modifyOrder().
  • Fill.oid and Order.oid are now documented and normalized as the on-chain keeper order id, formatted as a base-10 numeric string for both fast-overlay and subgraph-indexed entries.
  • extractOrderIdFromReceipt() now decodes order ids from the current MarketOpenOrderInitiated, MarketCloseOrderInitiated, and MarketCloseOrderInitiatedV2 events, while still supporting older PriceRequested receipts.
  • Fast-overlay trades in streamAccountUpdates() seed their rollover baseline from the pair’s rollover accumulator at the open block, keeping streamed PnL and liquidation estimates aligned with indexed positions.
  • OstiumPriceStream.subscribe() and .unsubscribe() no longer drop filter messages while the socket is still connecting; pending filter changes are sent on open.
  • The account-updates WebSocket retries reconnection indefinitely with a 2-second delay instead of stopping after viem’s default retry limit.

​
[0.6.0] - 2026-07-23

​
Changed

  • BREAKING: Migrated the default builder API endpoints from https://builder.ostium.io to https://builder.prod.bedrock.ostium.io (subgraph, Pimlico sponsor, prices/OHLC, and WebSocket stream). builder.ostium.io is being deprecated; clients relying on the old default must upgrade. Consumers passing explicit URLs should update them accordingly.

​
Fixed

  • Ghost positions in streamAccountUpdates(): a trade closed before its open was ever observed indexed, whose MarketCloseExecutedV2 event was missed (e.g. during a WebSocket reconnect), previously lingered in the emitted snapshot forever. Three complementary fixes:
    • The account snapshot query now also fetches recently executed close/liquidation orders (15-minute lookback) and tombstones matching overlay entries, so the subgraph poll can clear a ghost even with a dead event socket.
    • New missed-event backfill: each poll sweeps MarketOpenExecuted / MarketCloseExecutedV2 logs over HTTP from the last swept block, so events dropped during a WebSocket flap surface within roughly one poll interval instead of being lost.
    • executed overlay entries are no longer exempt from the overlay TTL; an executed trade the subgraph never confirms within the TTL now expires instead of ghosting indefinitely.

​
[0.5.0] - 2026-07-13

​
Changed

  • streamAccountUpdates() now fetches the account snapshot for all subscribed traders in one batched subgraph query per poll instead of one query per trader. If the shared 1000-row window saturates (any entity set returns a full page), the poll transparently falls back to per-user queries so a busy account still cannot starve the others.
  • Default pollIntervalMs raised from 700 to 3000. Sub-second open/close confirmations come from the Alchemy event watchers (which also trigger an immediate poll), so the timer poll only paces reconciliation of changes with no watcher (limit fills, partial closes, TP/SL edits, liquidations). Pass pollIntervalMs to restore a faster cadence.
  • The per-poll Alchemy eth_blockNumber call is now served from a 30-second cache. Combined with the changes above, a 20-user stream drops from ~1,700 subgraph requests/minute to ~20, and steady-state Alchemy HTTP calls drop ~15×.

​
[0.4.1] - 2026-06-14

​
Added

  • streamAccountUpdates() now accepts user as an address array, allowing one or more trader addresses on a single stream (one WebSocket, one poll loop, one price feed). Emitted snapshots are keyed by normalized trader address with { positions, orders, limits } per trader.
  • OstiumAccountUpdatesStream.users getter returning the subscribed trader addresses.
  • Optional user argument to OstiumAccountUpdatesStream.addOptimisticOpen(params, submission?, user?) to attribute an optimistic open to a specific subscribed address. Required when streaming multiple addresses; defaults to the sole subscribed address otherwise.

​
[0.4.0] - 2026-06-11

​
Added

  • Added this changelog.
  • Added sets pagination support to getCandles().
  • Added getOrders() filters for global orders, builder address, status, pair ids, and execution time (start / end as Unix seconds UTC, inclusive bounds on executedAt).
  • Added getBuilderOrders(builder, params?) — fetches builder-tagged open orders plus sibling close/TP/SL orders on the same positions. limit caps phase-1 results only; phase-2 siblings are appended without a cap.
  • Added builder to returned Fill and Order objects.
  • Added ntl (USD notional) to returned Fill and Order objects.
  • Added trader to returned Fill, Order, Position, and OpenOrder objects.
  • Added timestamp (execution time, Unix seconds UTC — subgraph executedAt) to returned Fill and Order objects.
  • Added MIN_OPEN_SIZE_USD for the fixed $5 minimum open size.
  • Added per-trade optional builder.address / builder.feeBps overrides on openTrade(); omitted fields fall back to client config.
  • Added openFee and closeFee (bps) to Pair — openFee is takerFeeP / 10_000 plus the configured builder fee; closeFee is always 0 as there’s no closing fees on Ostium currently.
  • Added streamAccountUpdates() for low-latency account confirmations using subgraph polling, Alchemy contract-log overlays, and live price repricing for open-trade PnL.
  • Added optimistic market-open overlays to streamAccountUpdates(), receipt orderId extraction via extractOrderIdFromReceipt(), and attachOrderId() reconciliation for lower-latency confirmations.
  • Added alchemyApiKey as a client option for account confirmation streams.
  • Added account update snapshots with SDK-formatted Order, OpenOrder, and PairPosition values.
  • Added schedule (market hours — timezone, openingHours, alwaysOpen) to Pair returned by getPairs(), and to PriceData / PriceTick from the live price feed.
  • Added background SDK usage attribution: submissions that target the Trading contract report their transaction hash to the builder API (POST /v1/trade) as a fire-and-forget request that never blocks or affects trading calls.

​
Changed

  • Updated the default mainnet subgraph URL to https://builder.ostium.io/v1/subgraph/gn.

​
Fixed

  • Removed the SDK-side openTrade() maximum leverage cap so contract-side validation is authoritative.
  • Removed the internal minimum-open-size config override path.

​
[0.3.1]

  • Current published package version when this changelog was introduced.