Networks and endpoints

This page lists the Somnia networks and the endpoint and address values that go into a configuration. The SDK accepts a viem Chain. The address constants come from the SDK root entry.

The RPC endpoint chooses a server, not a shared socket. Each configured owner creates its own connection even when endpoint URLs match. Node uses a managed ws connection by default; browser defaults use native/global/isows selection. For an application-specific RPC constructor, pass rpcWebSocketConstructor to the root. Its configuration contract covers selection, ownership and migration from implicit Node globals.

Chains

Use the chain definitions that @somnia-chain/markets-sdk/chains exports. Each one carries its WebSocket URL, so wsRpcUrl is optional with them. Do not define these networks by hand: a hand-written definition keeps old endpoints when a network moves, as Hideki did at its 2026-09-17 regenesis. viem's own somnia and somniaTestnet describe the mainnet and Shannon networks but carry no WebSocket URL. If you use them, set wsRpcUrl.

import { hidekiTestnet, somniaMainnet, somniaShannon } from "@somnia-chain/markets-sdk/chains";

Shannon also serves https://dream-rpc.somnia.network and wss://dream-rpc.somnia.network/ws as secondary RPC URLs for the same network.

Hideki Testnet also serves https://api.hideki2.infra.testnet.somnia.network and wss://api.hideki2.infra.testnet.somnia.network/ws for the same network.

Block time is the time between ledger blocks, the value of blockTime. Somnia Tokyo and Hideki Testnet also commit transactions in 10 ms consensus blocks, but the RPC serves only the ledger blocks. See Somnia Tokyo and Hideki Testnet block time.

Block explorers: https://explorer.somnia.network (mainnet) and https://shannon-explorer.somnia.network (Shannon). Somnia Tokyo, Hideki Testnet, and local carry no explorer.

Multicall3: mainnet 0x5e44F178E8cF9B2F5409B6f18ce936aB817C5a11, Shannon 0x841b8199E6d3Db3C6f264f6C2bd8848b3cA64223, and Somnia Tokyo and Hideki Testnet 0xcA11bde05977b3631167028862bE2a173976CA11 (the canonical address, which each genesis predeploys). Local carries none.

Somnia Tokyo has five spot pools and sixteen perp markets, all quoted in USDso, and the binary-markets core. SOMNIA_TOKYO_ADDRESSES carries the binary-markets core, perpPoolFactory, marginBank, priceFeedScheduler and the shared operator permissions registry. Its indexer is https://tokyo-prd.smk.somnia.host/v1/graphql. Use its chain definition for chain reads and for the bridge from Somnia mainnet. Somnia Tokyo launched as Hideki Mainnet. Its launch endpoints, https://api.hideki.infra.mainnet.somnia.network and wss://api.hideki.infra.mainnet.somnia.network/ws, serve the same chain and keep working. So do the launch names of its send and session hosts, send.hideki.infra.mainnet.somnia.network and session.hideki.infra.mainnet.somnia.network.

Send and session endpoints

A chain definition can name two send-only endpoints beside rpcUrls.default: rpcUrls.send and rpcUrls.session. Each one reaches a validator directly, with no RPC node in between. A validator keeps no history, so it cannot serve receipts, blocks, logs or state reads. The SDK therefore sends only the methods below to these endpoints, and reads from the default endpoint. In @somnia-chain/markets-sdk/chains, Somnia Tokyo and Hideki Testnet name them. The SDK treats the same entries in your own chain definition in the same way.

The SDK sends eth_sendRawTransaction, eth_sendRawTransactionSync and realtime_sendRawTransaction to send, and somnia_sendSessionTransaction and somnia_getSessionAddress to session.

By default, the SDK sends over each entry's WebSocket URL. A socket stays open while it is idle, so after its first call, a call costs one round trip and no new handshake. A session usually sends many transactions, so the one handshake pays off quickly. The send socket opens on the first send. The session calls go out on one socket for each session. Its URL carries the session address as the affinity query parameter, in lowercase hex, as somnia_getSessionAddress returns it, for example wss://session.hideki.infra.testnet.somnia.network/ws?affinity=0xd56d…cc51. The endpoint chooses the validator from that key. Every client of one session therefore reaches the node that holds the session's nonce sequence. Another client that shares the session must send the same key: a checksummed address reaches another validator. A session socket opens on its session's first call. An instance keeps at most 16 session sockets. To open another, it closes the least recently used socket that has no call in flight.

An entry without a WebSocket URL is used over its HTTP URL. There, a session call carries the key in the x-affinity-id header, which reaches the same validator as the affinity parameter. An HTTP request has an 8-second deadline and no retries.

The SDK uses these endpoints only when wsRpcUrl is unset or equals the chain's default WebSocket URL. With any other wsRpcUrl, every request goes to that URL, so a fork or a private node never broadcasts to the public network. To read from your own node and still send to the validators, put your node in the chain's rpcUrls.default and keep the send and session entries.

Somnia Markets deployments

The mainnet and Shannon testnet constants share the protocol contracts (binaryModule, binaryPoolBeacon, binaryPoolImpl, marketsCore, oracleHub, binarySettlement, clobFactory, collateralRouter, marketCreatorFactory) and differ in collateral, marketCreator, lend, perpPoolFactory, marginBank, and priceFeedScheduler.

The Hideki preset omits collateralRouter and lend. Hideki has no wSTT, Permit2, or SomniaLend deployment, so the corresponding helpers report not-configured.

The Hideki indexer is development-grade. It runs in the development environment and has no alerting, so a stall can go unnoticed. It indexes the Hideki binary, perp and spot markets, except the HBTT/USDso spot pool. Omit indexerUrl for chain-only reads and writes; supply one for indexed discovery and history. Indexed reads without a configured URL fail with NotConfiguredError; requests to an unreachable indexer fail with IndexerError.

The Tokyo indexer is a production deployment. It indexes the five spot pools, the sixteen perp markets and the binary-markets core. Tokyo has no binary venue yet, so the indexer lists no binary markets there.

The Shannon, Hideki and Tokyo presets set perpPoolFactory and a candidate marginBank. These values come from the canonical perp deployment records. With Multicall and a modern factory, discovery takes at most two serial rounds when every pool names the candidate bank. Each pool's own bank controls its registration gate. Unknown or different banks use authoritative fallback reads. loadMarkets therefore lists their perps from the chain, also when the binding has no indexerUrl. The mainnet preset has neither perp field because its deployment is deferred.

Addresses change with deployments. The constants in the installed SDK version are the source of truth; the values above are the ones current at the time of writing.

Testnet tokens

Hideki has its own token addresses. Send USDso and STT to Hideki from Shannon through the bridge. USDso on Hideki cannot be minted.

Price feed

These are separate deployments. Each one indexes the PriceFeedScheduler on its own chain. Use the feed that matches the chain the client runs on. A mainnet client that uses the testnet feed reads prices from chain 50312. Tokyo's scheduler has the same address as mainnet's, so only the endpoint tells the two feeds apart.

The mainnet feed carries fewer symbols than the testnet feed. Code written for the testnet asset list can therefore fail on mainnet. Read the feed catalog to learn which bases exist. A base the feed does not carry returns no rows. It does not raise an error.

The PriceFeedScheduler contract is at 0x7ccAE31E45693475be1e4BAa2360D6997eB2D32B on Shannon, and at 0x1998C88D54a240b8C671493f27f58eC416b81D7F on mainnet and on Hideki. It holds every price under a symbol name, and the perp pools' oracles read it. The Shannon and Hideki address constants set it as priceFeedScheduler. The mainnet constant does not, because mainnet has no perps manifest yet.

Peer dependencies

The package is published on the public npm registry from version 0.20.0. The chain transport uses the platform WebSocket where there is one, and the ws package on Node.js 20, which has none.