Developers
API, MCP & SDK
Every programmatic way into Somnia: the JSON-RPC API for the chain, the Explorer APIs, the Somnia CLI and MCP server, and the SDKs for markets and accounts.
Every programmatic way into Somnia.
This page is for developers and agents connecting to Somnia from code. It lists the endpoint for each network, the Explorer's APIs, the Somnia CLI and MCP server, and the SDKs, and links each one's reference. Everything the explorer shows is reachable this way.
Endpoints
Somnia exposes an RPC API compatible with the Ethereum JSON-RPC specification, so standard tooling (viem, ethers, Foundry, Hardhat) works unchanged. Each RPC host also serves WebSocket JSON-RPC at /ws, such as wss://api.infra.mainnet.somnia.network/ws.
| Network | Chain ID | JSON-RPC | Explorer API |
|---|---|---|---|
| Global L1, mainnet | 5031 | https://api.infra.mainnet.somnia.network |
https://explorer.somnia.network/api |
| Global L1, testnet | 50312 | https://api.infra.testnet.somnia.network |
https://explorer.testnet.somnia.network/api |
| Tokyo Subchain, mainnet | 50321 | https://api.tokyo.infra.mainnet.somnia.network |
https://explorer.somnia.network/tokyo/api |
| Tokyo Subchain, testnet | 50383 | https://api.hideki.infra.testnet.somnia.network |
https://explorer.testnet.somnia.network/tokyo/api |
See the JSON-RPC API reference for every method, and Somnia Dedicated RPC for private, low-latency nodes reserved for your traffic (coming soon).
Explorer APIs
Each Explorer API root serves Blockscout's and Etherscan's APIs, with the same paths and response shapes, so most tools and code written for those work against it. A request the Explorer can't answer, such as NFT instances, gets a 501 that says so; the reference lists which. The APIs need no key and are open to any origin.
- REST: Blockscout's v2 API under
/api/v2, such asGET https://explorer.somnia.network/api/v2/stats. - Etherscan-compatible:
/api?module=…&action=…, also used to verify contracts withhardhat verifyandforge verify-contract(see Verifying via explorer). - JSON-RPC:
POST /api/eth-rpc, answered by the chain's own node.
The Explorer API reference lists every endpoint, and the testnet Explorer has its own.
Somnia CLI and MCP server
The Somnia CLI reads spot, binary and perp markets, SomniaLend, oracle prices and the Explorer from the command line, and signs writes with your own key. It is scriptable and CI-friendly, and its --help is written for agents as well as people. The Venue Kit is its somnia venue commands, which register a venue, create its markets and copy a front end for it.
somnia mcp, part of the CLI, gives AI agents read tools for markets, order books, positions, oracle prices and the Explorer, and finds the CLI command for anything else. It never signs or sends a transaction. Add it to Claude Code with:
claude mcp add somnia -- npx -y @somnia-chain/cli mcp
See Somnia MCP server for Codex, Cursor and other clients. For the docs themselves, point your agent at llms.txt, and at the Explorer's llms.txt for its pages and APIs.
SDKs
- Markets SDK:
@somnia-chain/markets-sdk, for live order books, account views and trading on spot, perpetual and event markets, and for creating and configuring venues. See the TypeScript SDK docs. - Accounts SDK:
@somnia-chain/accounts-sdk, for smart accounts, session keys and acting without a signature. See the Accounts SDK docs.
See it in use
- Somnia Explorer. Its Blockscout and Etherscan APIs answer from the same data its pages show.
/api/v2/statsgives the chain's totals as JSON. - A Venue Kit front end. The app that
somnia venue initcopies reads order books and market status from the chain over JSON-RPC.
Use it from the CLI and MCP
somnia read --network testnet # chain ID and latest block over JSON-RPC
somnia explorer address $ADDRESS --network mainnet # an address through the Explorer's API
somnia explorer tx $HASH --network testnet # a transaction, with its token transfers
The MCP server gives agents the same Explorer lookups as its explorer_address, explorer_transaction, explorer_block, explorer_token, explorer_logs and explorer_search tools; it has no tool for a raw JSON-RPC read like somnia read. Both take a network preset for each chain in the table: --network mainnet, testnet, tokyo or tokyo-testnet (CLI 0.2.0 or newer for the Tokyo two), such as somnia explorer tx $HASH --network tokyo. --rpc-url and --explorer-url point them at other endpoints; given to somnia mcp, they apply to the whole server, whatever network a tool call names. For anything the CLI doesn't cover, use the Markets SDK or your usual library, such as viem or ethers.