# 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

```sh
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`:

```sh
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:

```sh
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.

---

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.