Blockscout Explorer API Skill#

Use this skill to run Blockscout explorer operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, auth, and error-handling guidance.

Prerequisites#

• uxc is installed and available in PATH.
• Network access to a Blockscout deployment that exposes /api/v2.
• Access to the curated OpenAPI schema URL:
  • https://raw.githubusercontent.com/holon-run/uxc/main/skills/blockscout-openapi-skill/references/blockscout-v2.openapi.json
• A target Blockscout instance. Examples in this skill use https://eth.blockscout.com/api/v2.

Scope#

This skill covers a read-first explorer surface:

• address summary lookup
• address token balances
• address transaction history
• token metadata
• token holder reads
• transaction detail lookup
• block detail lookup

This skill does not cover:

• Blockscout GraphQL
• raw JSON-RPC proxying
• write operations or admin/configuration flows
• custom authenticated gateways beyond what the caller explicitly binds

Authentication#

Public Blockscout instances usually allow explorer reads without auth.

If you are targeting a self-hosted or gateway-protected instance, configure auth separately with standard uxc auth bindings for that host. This skill does not assume any default credential.

Core Workflow#

1. Use the fixed link command by default:
   • command -v blockscout-openapi-cli
   • If missing, create it: uxc link blockscout-openapi-cli https://eth.blockscout.com/api/v2 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/blockscout-openapi-skill/references/blockscout-v2.openapi.json
   • blockscout-openapi-cli -h
2. Inspect operation schema first:
   • blockscout-openapi-cli get:/addresses/{address_hash} -h
   • blockscout-openapi-cli get:/tokens/{address_hash} -h
   • blockscout-openapi-cli get:/transactions/{hash} -h
3. Prefer narrow lookup validation before larger history reads:
   • blockscout-openapi-cli get:/blocks/{block_number_or_hash} block_number_or_hash=latest
   • blockscout-openapi-cli get:/addresses/{address_hash} address_hash=0xd8da6bf26964af9d7eed9e03e53415d37aa96045
   • blockscout-openapi-cli get:/tokens/{address_hash} address_hash=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
4. Execute with key/value parameters:
   • blockscout-openapi-cli get:/addresses/{address_hash}/transactions address_hash=0xd8da6bf26964af9d7eed9e03e53415d37aa96045
   • blockscout-openapi-cli get:/tokens/{address_hash}/holders address_hash=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

Operation Groups#

Address Reads#

• get:/addresses/{address_hash}
• get:/addresses/{address_hash}/token-balances
• get:/addresses/{address_hash}/transactions

Token, Transaction, And Block Reads#

• get:/tokens/{address_hash}
• get:/tokens/{address_hash}/holders
• get:/transactions/{hash}
• get:/blocks/{block_number_or_hash}

Multi-Instance Use#

To target a different Blockscout deployment, keep the same schema and relink the command to another host that serves /api/v2:

bash

uxc link blockscout-openapi-cli https://optimism.blockscout.com/api/v2 \
  --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/blockscout-openapi-skill/references/blockscout-v2.openapi.json

Guardrails#

• Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Treat this v1 skill as read-only. Do not imply transaction broadcast or contract write support.
• This schema is designed for Blockscout deployments that expose the explorer REST surface at /api/v2. If host help fails, check the deployment path before assuming a protocol mismatch.
• Pagination and filter options vary across deployments. Start with host help and operation help on the target instance before building large crawls.
• blockscout-openapi-cli <operation> ... is equivalent to uxc <blockscout_api_v2_host> --schema-url <blockscout_openapi_schema> <operation> ....

References#

• Usage patterns: references/usage-patterns.md
• Curated OpenAPI schema: references/blockscout-v2.openapi.json
• Blockscout API docs: https://docs.blockscout.com/devs/apis-redirect