blocknative-openapi-skill

name	blocknative-openapi-skill
description	Operate Blocknative gas intelligence APIs through UXC with a curated OpenAPI schema, API-key auth, and read-first guardrails.

Blocknative Gas Platform Skill

Use this skill to run Blocknative gas intelligence 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 https://api.blocknative.com.
• Access to the curated OpenAPI schema URL:
  • https://raw.githubusercontent.com/holon-run/uxc/main/skills/blocknative-openapi-skill/references/blocknative-gas.openapi.json
• A Blocknative API key for the full v1 surface.

Scope

This skill covers a read-first Blocknative gas intelligence surface:

• supported chain discovery
• gas price confidence estimates
• base fee and blob fee prediction
• pending gas distribution analysis

This skill does not cover:

• write operations
• transaction submission
• mempool event streaming
• broader Blocknative product areas outside the selected gas platform endpoints

Authentication

Blocknative uses Authorization header auth. Some discovery and gas reads can work without a key, but this skill standardizes on authenticated requests because basefee-estimates and distribution require a valid API key.

Configure one API-key credential and bind it to api.blocknative.com:

uxc auth credential set blocknative \
  --auth-type api_key \
  --api-key-header Authorization \
  --secret-env BLOCKNATIVE_API_KEY

uxc auth binding add \
  --id blocknative \
  --host api.blocknative.com \
  --scheme https \
  --credential blocknative \
  --priority 100

Validate the active mapping when auth looks wrong:

uxc auth binding match https://api.blocknative.com

Core Workflow

1. Use the fixed link command by default:

   • command -v blocknative-openapi-cli
   • If missing, create it: uxc link blocknative-openapi-cli https://api.blocknative.com --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/blocknative-openapi-skill/references/blocknative-gas.openapi.json
   • blocknative-openapi-cli -h

2. Inspect operation schema first:

   • blocknative-openapi-cli get:/chains -h
   • blocknative-openapi-cli get:/gasprices/blockprices -h
   • blocknative-openapi-cli get:/gasprices/basefee-estimates -h

3. Prefer narrow validation before broader polling:

   • blocknative-openapi-cli get:/chains
   • blocknative-openapi-cli get:/gasprices/blockprices chainid=1
   • blocknative-openapi-cli get:/gasprices/basefee-estimates

4. Execute with key/value parameters:

   • blocknative-openapi-cli get:/gasprices/blockprices chainid=1 confidenceLevels=70,90,99
   • blocknative-openapi-cli get:/gasprices/blockprices system=story network=mainnet
   • blocknative-openapi-cli get:/gasprices/distribution chainid=1

Operation Groups

Discovery

• get:/chains

Gas Intelligence

• get:/gasprices/blockprices
• get:/gasprices/basefee-estimates
• get:/gasprices/distribution

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 sending or execution support.
• blockprices can be polled without auth on some plans, but basefee-estimates and distribution require a valid key. Standardize on auth so mixed workflows do not fail mid-run.
• These endpoints update at most once per second on paid plans and more slowly on free plans. For automation, start around one poll every 5 to 10 seconds and only tighten that interval when you specifically need fresher paid-plan data.
• distribution is Ethereum-mainnet focused in the current docs. Do not assume multi-chain coverage there just because blockprices supports many chains.
• Keep confidenceLevels narrow and explicit when you do not need the full default ladder.
• blocknative-openapi-cli <operation> ... is equivalent to uxc https://api.blocknative.com --schema-url <blocknative_openapi_schema> <operation> ....

References

• Usage patterns: references/usage-patterns.md
• Curated OpenAPI schema: references/blocknative-gas.openapi.json
• Blocknative Gas Price API docs: https://docs.blocknative.com/gas-prediction/gas-platform
• Blocknative Base Fee API docs: https://docs.blocknative.com/gas-prediction/prediction-api-base-fee-and-blob-fee
• Blocknative Gas Distribution API docs: https://docs.blocknative.com/gas-prediction/gas-distribution-api