/blockscout-openapi-skill

name: blockscout-openapi-skill
description: Operate Blockscout explorer reads through UXC with a curated OpenAPI schema, instance-specific host selection, and read-first guardrails.

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

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