Somnia Markets

Explorer lookups from the CLI and MCP

Look up an address, transaction, block, token, event logs or search results on the Somnia Explorer from the somnia CLI, its MCP server, or the SDK.

The Somnia Explorer serves a Blockscout-compatible REST API at /api/v2. The somnia CLI (npx @somnia-chain/cli), its MCP server (somnia mcp) and the SDK read six kinds of lookup from it: address, transaction, block, token, event logs and search. All three give the same answer: the Explorer's own JSON, with every field it sends, under Blockscout's names. Amounts are decimal strings in raw units (wei for the native token), so tools written for Blockscout read them unchanged.

Network	Explorer API
`--network mainnet` (the default)	`https://new.explorer.somnia.network/api/v2`
`--network testnet` (Shannon)	`https://explorer.testnet.somnia.network/api/v2`

--explorer-url <root> points a command at another Explorer. SOMNIA_NETWORK sets the default network, as for every other command.

Lookups

What	CLI command	MCP tool	Explorer API
Address: native balance, contract or account, verified, creator, token	`somnia explorer address <address>`	`explorer_address`	`GET /api/v2/addresses/{address}`
Transaction: status, block, sender, recipient, value, fee, token transfers	`somnia explorer tx <hash>`	`explorer_transaction`	`GET /api/v2/transactions/{hash}`
Block by number or hash	`somnia explorer block <number\|hash>`	`explorer_block`	`GET /api/v2/blocks/{number or hash}`
Token: name, symbol, type, decimals, supply, holders	`somnia explorer token <address>`	`explorer_token`	`GET /api/v2/tokens/{address}`
Logs a transaction emitted	`somnia explorer logs --tx <hash>`	`explorer_logs` (`tx`)	`GET /api/v2/transactions/{hash}/logs`
Logs a contract emitted, newest first	`somnia explorer logs --address <address>`	`explorer_logs` (`address`)	`GET /api/v2/addresses/{address}/logs`
Search for an address, hash, block number, token or contract name	`somnia explorer search <text>`	`explorer_search`	`GET /api/v2/search?q=`

CLI

somnia explorer tx 0x0266cdc7da71f43ff77c52303df5ce5aec13bdb24977067a3d96d689f74e4833
somnia explorer address 0x28BEc7E30E6faee657a03e19Bf1128AaD7632A00 --json
somnia explorer block 456746071 --network mainnet
somnia explorer token 0x28BEc7E30E6faee657a03e19Bf1128AaD7632A00
somnia explorer logs --address 0x5E5205CF39E766118C01636bED000A54D93163E6
somnia explorer search USDC

At a terminal a command prints labelled fields. In a pipe, or with --json, it prints the Explorer's answer as JSON. A lookup by key that the Explorer has no record of (an unknown transaction, block or token) prints error: the mainnet Explorer has no transaction 0x… on stderr and exits 1. So does an Explorer that cannot answer; the error names the status and the Explorer's message.

explorer logs prints { "items": [...], "nextPage": "..." }. To read the next page, pass nextPage to --page. On the last page, nextPage is null:

somnia explorer logs --address $CONTRACT --page 'block_number=456746252&index=14&items_count=50'

MCP

somnia mcp serves the six lookups as read-only tools, next to its other read tools. A tool takes the arguments and flags of its command under the same names (explorer_block takes block; explorer_logs takes tx or address, and page), plus an optional network. Each result is the command's JSON followed by the command line that prints the same thing:

claude mcp add somnia -- npx -y @somnia-chain/cli mcp
claude mcp add somnia-testnet -- npx -y @somnia-chain/cli mcp --network testnet

--network and --explorer-url on somnia mcp set the defaults for calls that name no network. A call cannot set an endpoint URL.

SDK

The CLI reads through the Effect SDK's explorer module (@somnia-chain/sdk/explorer), which is not yet published to npm. Each lookup is an Effect that needs the ExplorerApi service, from Explorer.layer({ url }) over an Effect HttpClient:

Method	Returns
`getAddressInfo(address)`	the address, or `null`
`getTransaction(hash)`	the transaction, or `null` when the Explorer has none
`getBlock(numberOrHash)`	the block, or `null`
`getToken(address)`	the token, or `null` when the address is no token
`getTransactionLogs(hash, { page })`	`{ items, nextPage }`, or `null` when the Explorer has no such transaction
`getAddressLogs(address, { page })`	`{ items, nextPage }`
`listSearchResults(query)`	the hits, each with its `type`

explorerUrls maps chain ids 5031 and 50312 to their Explorer. The decoded types keep every field of the answer and decode its amounts to bigint. A failure is one of three errors: ExplorerInputError (a malformed address, hash, block or empty query, refused before any request), ExplorerRequestError (no answer, or an error status; it has the status and the Explorer's message) and ExplorerResponseError (an answer of another shape).

Limits on testnet

The testnet Explorer has no token index yet. On testnet, explorer token answers that it knows no token, and explorer search by name fails with a 404. A search by address, hash or block number reads the chain and works on both networks.

Edit this page