Configuration

This page lists every field a SomniaMarkets instance accepts, with its type, whether it is required, and its default. Engine fields form ClientConfig; signer fields and rpcWebSocketConstructor belong to the configured root. For the values to put in these fields on each network, see Networks and endpoints.

import { SomniaMarkets } from "@somnia-chain/markets-sdk";

const exchange = new SomniaMarkets(config); // config: SomniaMarketsConfig

SomniaMarketsConfig

SomniaMarketsConfig accepts one chain configuration or a chains list, plus the signer fields privateKey, account, and walletClient, and the optional root RPC constructor.

Counts and indexerHeaders

This section describes how the count methods (countMarkets, countOrders and the others) pick a query. A count first asks Hasura for <Table>_aggregate. Only a privileged role, such as the one an admin secret in indexerHeaders selects, has that field. On the public role Hasura rejects the field, and the count scans at most 10,001 ids instead.

The client remembers that rejection for five minutes. The memory is per client, endpoint, header set and table. In that window a count of the same table sends only the scan. The first counts of a table that run at the same time share one probe. Only Hasura's exact field '<Table>_aggregate' not found in type: 'query_root' error is remembered. Any other failure still throws and is not remembered. stopLive() clears the memory. After a role gains or loses the field, counts use the new permission within five minutes, or at once after stopLive().

RPC constructor selection

Node connections use the SDK-managed ws transport by default. Replacing globalThis.WebSocket or isows on Node does not select an RPC constructor. Price-feed sockets use the same selection and the same explicit constructor. Browsers retain their native/global/isows selection, including replacements installed before or after SDK import. An explicit rpcWebSocketConstructor selects the constructor on either platform, independent of import order.

The selected constructor receives only standard WebSocket arguments. RPC construction calls new Constructor(url). Price-feed construction calls new Constructor(url, "graphql-transport-ws"). A protocol is always the standard second string or string-array argument. The SDK retains the exact returned socket and does not mutate the caller's constructor or prototype. Constructor selection is lazy. Closing the owner during dependency loading prevents construction, and an indexer-only exchange makes no RPC dial.

A supplied constructor is trusted infrastructure. Every created socket belongs to this exchange and must promptly dispose connecting and open work through close(), stop replacement dials and safely observe errors during retirement. Sharing a class between exchanges must not share its created sockets. A standard interface proves the calling convention, not physical disposal. Node 22's native WebSocket does not satisfy this custom disposal obligation; use the managed Node default or a conforming implementation.

Migrating a Node override

Replace global assignment with a per-owner input. AppWebSocket below is your application's conforming constructor; config is its existing exchange config.

// Before
globalThis.WebSocket = AppWebSocket;
const exchange = new SomniaMarkets(config);

// After
const exchange = new SomniaMarkets({
  ...config,
  rpcWebSocketConstructor: AppWebSocket,
});

A compile-checked factory can make that ownership explicit:

import {
  SomniaMarkets,
  type SomniaMarketsConfig,
  type SomniaMarketsWebSocketConstructor,
} from "@somnia-chain/markets-sdk";

function createExchange(config: SomniaMarketsConfig, AppWebSocket: SomniaMarketsWebSocketConstructor) {
  return new SomniaMarkets({ ...config, rpcWebSocketConstructor: AppWebSocket });
}

Modeled operations preserve concrete SDK constructor/member failures by identity; other transport failures become RpcError with the original value as cause. Price watches follow the same rule when a price-feed socket cannot be selected or constructed: watchPrice and watchPrices reject with the constructor's SDK error, or with RpcError for any other thrown value. Root validation rejects a non-function input with InvalidInputError. Unexpected configuration-access failures become InvariantError with their original cause. close() and the engine's stopLive() finish remaining cleanup before reporting the first disposal failure. A disposal failure following an already delivered operation timeout does not replace that timeout; it is retained for owner cleanup. A constructor that violates the disposal obligation cannot receive a physical release guarantee from the SDK. Undecorated viem operations retain their platform operational contract after access.

Signer resolution

A method that writes, or reads data scoped to the caller, resolves the caller's address in this order: walletClient.account.address, then account.address, then account when it is a string, then the address derived from privateKey. When none is set, walletAddress is undefined and every authenticated method throws SignerRequiredError.

setSigner(signer) replaces the signer after construction. Passing {} removes it. Live watches and market data are unaffected.

Signer paths

Lazy connections

The viem chain WebSocket opens on the first chain read, write, or watch. An instance that only performs indexer reads never opens one. The price-feed WebSocket opens on the first watchPrice. close() stops the watches and channels and closes every socket the instance opened, both the price-feed WebSockets and the viem chain transport, so a Node process exits on its own afterwards. Each instance owns its own chain socket, even when several use the same wsRpcUrl, so closing one never affects another.

FixedFees

DEFAULT_FEES is { maxFeePerGas: 60_000_000_000n, maxPriorityFeePerGas: 0n }: a 60 gwei ceiling and no tip.

Gas

Every SDK-signed write uses a fixed gas ceiling of 10,000,000 gas. Gas is never estimated. Unused gas is not charged. The mempool accepts a transaction only when the account holds gas × maxFeePerGas on top of the transaction value: 0.6 STT or SOMI at the defaults. A lower-level write accepts a per-call gas override only when its public parameter type declares one. Unified exchange methods such as createOrder and cancelOrder do not expose that override.

SomniaMarketsAddresses

Every field is optional and typed Address, except lend.

SOMNIA_MAINNET_ADDRESSES, SOMNIA_TESTNET_ADDRESSES and SOMNIA_HIDEKI_TESTNET_ADDRESSES, exported from the root entry, hold the current deployments. SOMNIA_MAINNET_LEND and SOMNIA_TESTNET_LEND hold the SomniaLend addresses and are already included in the mainnet and testnet constants. Hideki has no SomniaLend deployment, so its preset omits lend.

PriceFeedConfig

SOMNIA_TESTNET_PRICE_FEED is { url: "https://price-feed.dev.oracle.somnia.host/v1/graphql", quote: "USDC" }. SOMNIA_MAINNET_PRICE_FEED is { url: "https://price-feed.prd.oracle.somnia.host/v1/graphql", quote: "USDC" }. They index different chains; see networks and endpoints.

Transport constants