cross-explorer

CROSS Chain Explorer

Supported surface: explorer data lookup only.

A distributable skill that lets Claude drive the CROSS Chain block-explorer surface — the Blockscout v2 API hosted at https://www.crossscan.io (mainnet, chainId 612055) and https://testnet.crossscan.io (testnet, chainId 612044), with deep links into the https://explorer.crosstoken.io UI. Execution is plain HTTPS GET/POST via Node's built-in fetch — no signer, no viem, no browser automation, zero npm dependencies.

Scope (v0.1): read-only only. Nine subcommands cover the entire user-facing explorer surface — chain stats, latest blocks/txs, block detail, tx detail (with optional log/transfer/internal/state expansion), address profile, verified-contract source, ERC-20/721/1155 token metadata, free-form search, and a deterministic offline URL parser. Every script emits a single JSON envelope on stdout; no decorative prose.

Deeper protocol details (chain registry, Blockscout v2 endpoint surface, fixture hashes, rate-limit measurements, derivation provenance) live in references/cross-explorer.md. Read it only when needed — it stays out of context otherwise.

---

1. Activation

Activate when the user wants to:

• Read chain-wide stats (gas prices, total blocks, total transactions, total addresses, transactions today)
• Pull the latest blocks + transactions (front-page feed; default 6 of each)
• Fetch a block by height or hash, optionally with the in-block transaction list
• Inspect a transaction — receipt + value + fee + sender + recipient — and optionally expand logs, token-transfers, internal-transactions, or state-changes
• Profile an address — coin balance, contract flag, verified flag, optional counters / transactions / token-balances
• Pull the verified source of a contract (ABI + Solidity source, with a 100 KB inline cap)
• Resolve token metadata (name / symbol / decimals / type / total supply / holders count) for ERC-20, ERC-721, ERC-1155, optionally with --holders or --transfers listings
• Run a free-form search through the Blockscout typed search index
• Parse a pasted explorer.crosstoken.io/{chainId}/... or crossscan.io/... URL into {network, chainId, kind, id} offline (no network call), so a downstream subcommand can be picked deterministically

Trigger phrases

Korean (≥ 6):

• "CROSS 체인 익스플로러" / "크로쓰 익스플로러 열어줘"
• "크로쓰 트랜잭션 조회" / "트랜잭션 0x... 분석"
• "블록 정보 알려줘" / "최근 블록 보여줘"
• "주소 잔액 조회" / "이 주소 트랜잭션 목록"
• "스캔 가스 가격" / "체인 통계"
• "컨트랙트 검증된 소스" / "verified source 보여줘"
• "토큰 홀더 목록" / "ERC20 메타데이터"
• "크로쓰 검색" / "crossscan 에서 검색"

English (≥ 6):

• "CROSS chain explorer" / "open crossscan for CROSS"
• "look up tx on crossscan" / "decode tx logs"
• "address balance on CROSS" / "recent transactions for 0x..."
• "block info" / "recent blocks" / "latest blocks and transactions"
• "chain stats" / "gas price on CROSS chain"
• "fetch verified source" / "contract ABI on crossscan"
• "token metadata" / "token holders list"
• "search on crossscan" / "resolve this explorer URL"

URL-paste fast path

When the user pastes a URL whose host is explorer.crosstoken.io, www.crossscan.io, crossscan.io, or testnet.crossscan.io, always run parse-url.mjs first. It is offline and deterministic; the resulting {network, kind, id} decides which downstream subcommand to invoke (tx | block | address | token).

Examples:

• https://explorer.crosstoken.io/612055/tx/0xb4faf72fd... → tx.mjs 0xb4faf72fd...
• https://explorer.crosstoken.io/612055/block/32388665 → block.mjs 32388665
• https://www.crossscan.io/address/0x0A57…aecD → address.mjs 0x0A57…aecD
• https://testnet.crossscan.io/token/0x1c37…a85C → token.mjs --network testnet 0x1c37…a85C

---

2. Prerequisites — verify before doing anything else

Run this check first. Stop and report on the first failure.

node --version          # require >= 20 (uses built-in fetch + WHATWG URL)

npm install is not required — the skill ships zero runtime dependencies (package.json#dependencies is {}). The install.sh wrapper does run npm install --silent for parity with sibling skills, but it is a no-op and a failure there does not block any subcommand.

SKILL_DIR="$HOME/.claude/skills/cross-explorer"
[ -d "$SKILL_DIR" ] || { echo "skill not installed; run install.sh"; exit 1; }

---

3. Credential resolution — none required

This read-only skill has no signing path, no wallet execution path, and no credential input. There is no wallet-address setup step and .env.example deliberately omits credential placeholders.

The only env vars the skill ever touches:

Variable	Default	Purpose
EXPLORER_NETWORK	mainnet	Selects mainnet (612055) or testnet (612044)
MAINNET_BASE_URL	https://www.crossscan.io	Override for self-hosted Blockscout mainnet mirror
TESTNET_BASE_URL	https://testnet.crossscan.io	Override for self-hosted Blockscout testnet mirror
DEBUG	unset	Set to 1 for verbose stderr; stdout stays a clean JSON envelope

If a caller supplies unrelated wallet secret env vars to a script in this skill, the script silently ignores them. There is no code path that reads wallet secrets.

---

4. Execution

All subcommands run via Bash and emit a single JSON envelope on stdout (no decorative prose). Parse the envelope and report the relevant fields back. Stderr stays empty unless DEBUG=1.

cd "$HOME/.claude/skills/cross-explorer"
node scripts/<subcommand>.mjs [args...] [--network mainnet|testnet]

All scripts accept --network mainnet|testnet to override EXPLORER_NETWORK. The resolved {network, chainId, baseUrl} is echoed in every envelope (success or error) so the caller can never confuse mainnet vs testnet results.

NL → subcommand map

User says (KR / EN)	Subcommand
"체인 통계" / "stats on CROSS"	node scripts/stats.mjs
"최근 블록 / 트랜잭션" / "latest blocks and txs"	node scripts/latest.mjs
"블록 32388665" / "block 32388665"	node scripts/block.mjs 32388665
"블록 32388665 + 트랜잭션 목록" / "block 32388665 with txs"	node scripts/block.mjs 32388665 --with-txs
"트랜잭션 0xb4faf...72fd" / "tx 0xb4faf...72fd"	node scripts/tx.mjs 0xb4faf72fd...
"트랜잭션 로그 디코드" / "decode tx logs"	node scripts/tx.mjs 0xb4faf72fd... --include logs,transfers
"주소 0x0A57…aecD" / "address 0x0A57…aecD"	node scripts/address.mjs 0x0A57aecD --counters
"주소 트랜잭션" / "address recent txs"	node scripts/address.mjs 0x0A57…aecD --txs 25
"컨트랙트 verified source" / "contract source"	node scripts/contract.mjs 0x0A57…aecD
"토큰 메타데이터" / "token info"	node scripts/token.mjs 0x1c37…a85C
"토큰 홀더" / "token holders"	node scripts/token.mjs 0x1c37…a85C --holders
"검색 USDT" / "search USDT"	node scripts/search.mjs USDT
"이 URL 분석해줘" / "parse this explorer URL"	node scripts/parse-url.mjs <url>

Subcommand reference

Each block ships with at least one runnable example using mainnet fixtures verified in Phase 1 (see references/cross-explorer.md).

stats — chain-wide statistics

GET /api/v2/stats. Read-only.

node scripts/stats.mjs
node scripts/stats.mjs --network testnet

Returns summary.{averageBlockTime, gasPrices.{slow,average,fast}, totalBlocks, totalTransactions, transactionsToday, totalAddresses, gasUsedToday} plus a health block ({status:"ok"} or {status:"degraded", reason}).

latest — front-page feed

GET /api/v2/main-page/blocks + GET /api/v2/main-page/transactions in parallel. Default 6 of each (cap 6).

node scripts/latest.mjs
node scripts/latest.mjs --limit 6

Returns summary.{blocks[], transactions[]} with per-row explorerLink deep links into explorer.crosstoken.io.

block — block detail

GET /api/v2/blocks/{heightOrHash}. Accepts decimal height (32388665), 0x-hex height (0x1ee9b39), or 32-byte hash. With --with-txs, also pulls /api/v2/blocks/{id}/transactions (capped at 50).

node scripts/block.mjs 32388665
node scripts/block.mjs 32388665 --with-txs

Returns summary.{height, hash, timestamp, transactionsCount, gasUsed, gasLimit, miner}.

tx — transaction detail

GET /api/v2/transactions/{hash}. With --include logs,transfers,internal,state (any subset, comma-separated), expands the corresponding sub-resource.

node scripts/tx.mjs 0xb4faf72fd...
node scripts/tx.mjs 0xb4faf72fd... --include logs,transfers
node scripts/tx.mjs 0xb4faf72fd... --include logs,transfers,internal,state

Returns summary.{hash, status, blockNumber, from, to, valueWei, valueHuman, gasUsed, feeWei} plus an includes map for each requested expansion.

address — address profile

GET /api/v2/addresses/{addr}. Optional sidecar fetches:

• --counters → /addresses/{addr}/counters
• --txs N → /addresses/{addr}/transactions (cap N ≤ 200; default 25)
• --filter to|from → narrows the tx feed
• --tokens → /addresses/{addr}/token-balances

node scripts/address.mjs 0x0A57aecD --counters
node scripts/address.mjs 0x0A57aecD --txs 25 --filter to
node scripts/address.mjs 0x0A57aecD --tokens

Returns summary.{hash, coinBalanceWei, isContract, isVerified, name, creatorAddressHash, creationTransactionHash} plus optional counters, transactions[], tokens[].

contract — verified-contract source + ABI

GET /api/v2/smart-contracts/{addr}. 404 → not_verified (frozen error code; treat as "EOA or unverified contract — try address instead"). source_code is capped at 100 KB inline; the full body still appears under raw when smaller, otherwise truncated:true with truncationReason.

node scripts/contract.mjs 0x0A57aecD

Returns summary.{address, name, compilerVersion, optimizationEnabled, evmVersion, licenseType, abi, sourceCode}.

token — ERC-20/721/1155 metadata

GET /api/v2/tokens/{addr}. 404 → not_a_token. Optional sidecars:

• --holders [N] → /tokens/{addr}/holders (cap N ≤ 200; default 25)
• --transfers [N] → /tokens/{addr}/transfers (cap N ≤ 200; default 25)

node scripts/token.mjs 0x1c37a85C
node scripts/token.mjs 0x1c37a85C --holders --transfers

Returns summary.{address, name, symbol, decimals, type, totalSupply, holdersCount}.

search — free-form Blockscout search

GET /api/v2/search?q=…. Returns the typed item list (each item has a .type ∈ {token, address, block, transaction, label, metadata_tag, contract}); the script attaches an explorerLink to each item that maps to a known kind.

node scripts/search.mjs USDT
node scripts/search.mjs 0x0A57aecD

Returns summary.{q, count, kinds[]} plus results[].

parse-url — offline URL classifier

No network call. Classifies a pasted URL into {network, chainId, kind, id} so a downstream subcommand can be selected deterministically. Accepts explorer.crosstoken.io/{chainId}/{kind}/{id}, https://www.crossscan.io/{kind}/{id} (mainnet), or https://testnet.crossscan.io/{kind}/{id} (testnet implied).

node scripts/parse-url.mjs https://explorer.crosstoken.io/612055/tx/0xb4faf72fd...
node scripts/parse-url.mjs https://www.crossscan.io/block/32388665

Bad URLs exit 2 with {ok:false, error:"bad_url", hint:"..."}.

---

5. Output envelope contract

Every successful response MUST match this shape:

{
  "ok": true,
  "command": "tx",
  "network": "mainnet",
  "chainId": 612055,
  "baseUrl": "https://www.crossscan.io",
  "explorerLink": "https://explorer.crosstoken.io/612055/tx/0xb4faf...",
  "summary": { /* curated flat fields per command */ },
  "raw": { /* upstream Blockscout v2 body, unchanged */ },
  "truncated": false,
  "fetchedAt": "2026-05-04T02:30:00.000Z"
}

Errors MUST match this shape:

{
  "ok": false,
  "command": "tx",
  "error": "bad_input",
  "hint": "expected 0x-prefixed 32-byte hash",
  "network": "mainnet",
  "chainId": 612055,
  "baseUrl": "https://www.crossscan.io",
  "fetchedAt": "2026-05-04T02:30:00.000Z"
}

Exit codes:

• 0 — success (ok:true)
• 2 — handled error (any frozen error code other than rate_limited)
• 4 — rate_limited after retries

raw echoes the upstream body unchanged so the caller can dig into fields the curated summary does not surface. raw_input (the giant calldata blob on tx detail) is dropped from raw to keep envelopes under the 2 MB budget; when that drop or any other byte cap fires, truncated:true with truncationReason.

---

6. Frozen error codes (v0.1)

These codes are frozen for v0.1. New codes may be added in later versions, but existing ones must not be repurposed.

Code	Meaning	Typical cause
bad_input	CLI argument failed validation	Missing hash / address / height; bad --network; cap exceeded
bad_url	parse-url could not classify the URL	Unknown host, missing path segments, non-numeric chainId
not_found	Upstream returned 404 for a generic resource	Unknown block height / tx hash
not_verified	Contract endpoint returned 404	Address is an EOA or an unverified contract — try address instead
not_a_token	Token endpoint returned 404	Address is an EOA or non-token contract — try address instead
rate_limited	429 after retries	Burst exceeded upstream quota; envelope carries retry_after_seconds
page_too_large	Caller asked for more rows than the cap	Use --holders 200 / --transfers 200 / --txs 200 ceilings
upstream_error	5xx or generic upstream failure	Blockscout outage, network blip; envelope carries upstreamStatus and upstreamBody (truncated)
timeout	Local 10 s timeout fired	Slow upstream; safe to retry once

---

7. Network selector behavior

--network precedence (highest wins):

1. --network mainnet or --network=mainnet on the command line
2. EXPLORER_NETWORK env var
3. Default mainnet

Resolution:

Network	chainId	API base (default)	Override env	UI host
mainnet	612055	https://www.crossscan.io	MAINNET_BASE_URL	https://explorer.crosstoken.io
testnet	612044	https://testnet.crossscan.io	TESTNET_BASE_URL	https://explorer.crosstoken.io

Guarantee: every envelope (success or error) echoes {network, chainId, baseUrl}. Mixing networks across calls inside one envelope is forbidden; the caller is responsible for keeping the --network flag consistent across a multi-step task.

---

8. Reference docs

Deeper protocol details — chain registry, Blockscout v2 endpoint surface (every endpoint with empirical status code), pagination cursor shape, fixture hashes (block 32388665, tx 0xb4faf...72fd, contract 0x0A57…aecD, token 0x1c37…a85C), rate-limit measurements, derivation provenance — live in references/cross-explorer.md. Lazy-load it only when an endpoint returns an unfamiliar shape or you are extending the scripts.

The companion design docs (PLAN, REQUIREMENTS, RISKS, ARCHITECTURE) live under the repo's top-level docs/ directory.

---

9. Distribution

This skill folder is the unit of distribution. Recipients:

1. Copy the whole cross-explorer/ folder into ~/.claude/skills/, or run bash install.sh from the repo root to symlink it.
2. No npm install required — dependencies is {}. The wrapper still runs npm install --silent for toolchain parity; failures there are non-fatal.
3. No .env required — read-only skill, no credentials. The optional .env.example only documents the network selector and base-URL overrides.
4. Try it from Claude Code:
   • "chain stats on CROSS"
   • "block 32388665 with txs"
   • "resolve this URL: https://explorer.crosstoken.io/612055/tx/0x..."

Cross-link: deeper details live in references/cross-explorer.md. Lazy-load on demand.