# Networks and endpoints


This page lists the Somnia networks and the endpoint and address values that go into a [configuration](./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](./configuration#rpc-constructor-selection)
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`.

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

| SDK export      | Chain id | Name           | Native currency | Block time | HTTP RPC                                          | WebSocket RPC                                      |
| --------------- | -------- | -------------- | --------------- | ---------- | ------------------------------------------------- | -------------------------------------------------- |
| `somniaMainnet` | 5031     | Somnia         | SOMI (18)       | 100 ms     | `https://api.infra.mainnet.somnia.network`        | `wss://api.infra.mainnet.somnia.network/ws`        |
| `somniaShannon` | 50312    | Somnia Testnet | STT (18)        | 100 ms     | `https://api.infra.testnet.somnia.network`        | `wss://api.infra.testnet.somnia.network/ws`        |
| `somniaTokyo`   | 50321    | Somnia Tokyo   | SOMI (18)       | 100 ms     | `https://api.tokyo.infra.mainnet.somnia.network`  | `wss://api.tokyo.infra.mainnet.somnia.network/ws`  |
| `hidekiTestnet` | 50383    | Hideki Testnet | STT (18)        | 100 ms     | `https://api.hideki.infra.testnet.somnia.network` | `wss://api.hideki.infra.testnet.somnia.network/ws` |
| `somniaLocal`   | 31337    | Somnia Local   | STT (18)        | none       | `http://127.0.0.1:8545`                           | `ws://127.0.0.1:8545`                              |

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](../chains#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](../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`.

| Network        | Entry     | URLs                                                                                                          |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| Somnia Tokyo   | `send`    | `https://send.tokyo.infra.mainnet.somnia.network`, `wss://send.tokyo.infra.mainnet.somnia.network/ws`         |
| Somnia Tokyo   | `session` | `https://session.tokyo.infra.mainnet.somnia.network`, `wss://session.tokyo.infra.mainnet.somnia.network/ws`   |
| Hideki Testnet | `send`    | `https://send.hideki.infra.testnet.somnia.network`, `wss://send.hideki.infra.testnet.somnia.network/ws`       |
| Hideki Testnet | `session` | `https://session.hideki.infra.testnet.somnia.network`, `wss://session.hideki.infra.testnet.somnia.network/ws` |

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

| Network                 | Indexer GraphQL                                                        | Address constant                                                           |
| ----------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Mainnet (5031)          | `https://prd.smk.somnia.host/v1/graphql`                               | `SOMNIA_MAINNET_ADDRESSES`                                                 |
| Shannon testnet (50312) | `https://dev.smk.somnia.host/v1/graphql`                               | `SOMNIA_TESTNET_ADDRESSES`                                                 |
| Hideki testnet (50383)  | `https://hideki-dev.smk.somnia.host/v1/graphql` (development-grade)    | `SOMNIA_HIDEKI_TESTNET_ADDRESSES`                                          |
| Somnia Tokyo (50321)    | `https://tokyo-prd.smk.somnia.host/v1/graphql`                         | `SOMNIA_TOKYO_ADDRESSES`                                                   |
| Local anvil (31337)     | `http://localhost:8085/v1/graphql` when started with `demo-clob.sh up` | Resolved from the local manifest through `@somnia-chain/deployments/local` |

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.

| Field                     | Mainnet                                      | Shannon                                                                        | Hideki                                                                         |
| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `collateral` / `testUsdc` | `0x00000022dA000002656c64D9eA6011ea952D008A` | `0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E` (tUSDC, 6 decimals, has `faucet`) | `0x9E9492cC533E8696A3b6afC7df730800DF75148f` (tUSDC, 6 decimals, has `faucet`) |
| `marketCreator`           | `0xfad8eDa4d50e876ba548BeD191Df1e2Af26783dF` | `0xD584e651008538b5C6B1C777cD4fbD54cC19a291`                                   | `0xAd890D6Ac3c659E1Ed0fA72Cf557DB4cA26bdAff`                                   |
| `lend`                    | `SOMNIA_MAINNET_LEND`                        | `SOMNIA_TESTNET_LEND`                                                          | not set                                                                        |

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

| Token | Address on Shannon                           | Decimals | Role                                                | How to obtain                                                         |
| ----- | -------------------------------------------- | -------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| STT   | native                                       | 18       | Gas, and the base of `SOMI/USDso`                   | Faucets listed in [Get testnet funds](../how-to/get-testnet-funds) |
| USDso | `0x9c32f3827a1a99f0cf9b213de8b53ec3d57bb171` | 18       | Quote of the spot pairs and settlement of the perps | Public `mint(address,uint256)`                                        |
| tUSDC | `0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E` | 6        | Collateral of the binary markets                    | `exchange.trader.faucet()`                                            |

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

| Token | Address on Hideki                            | Decimals | Role                                                | How to obtain                                                        |
| ----- | -------------------------------------------- | -------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| STT   | native                                       | 18       | Gas, and the base of the native spot pair           | Bridge from Shannon                                                  |
| USDso | `0xed7993A74dAe1e6656B704A424DcD8711aAf4F72` | 18       | Quote of the spot pairs and settlement of the perps | Bridge from Shannon                                                  |
| tUSDC | `0x9E9492cC533E8696A3b6afC7df730800DF75148f` | 6        | Collateral of the binary markets                    | `faucet(uint256 amount)` on the token, at most 10,000 tUSDC per call |

## Price feed

| Network         | Endpoint                                                                   | Constant                    |
| --------------- | -------------------------------------------------------------------------- | --------------------------- |
| Somnia mainnet  | `https://price-feed.prd.oracle.somnia.host/v1/graphql`, quote `USDC`       | `SOMNIA_MAINNET_PRICE_FEED` |
| Shannon testnet | `https://price-feed.dev.oracle.somnia.host/v1/graphql`, quote `USDC`       | `SOMNIA_TESTNET_PRICE_FEED` |
| Somnia Tokyo    | `https://price-feed.tokyo-prd.oracle.somnia.host/v1/graphql`, quote `USDC` | `SOMNIA_TOKYO_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

| Package                    | Range     | Required                                        |
| -------------------------- | --------- | ----------------------------------------------- |
| `viem`                     | `^2.18.5` | yes                                             |
| `react`                    | `>=18`    | only for `@somnia-chain/markets-sdk/react`      |
| `@somnia-chain/reactivity` | `^0.2.1`  | only for `@somnia-chain/markets-sdk/reactivity` |

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.

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.