Skill: jolestar/blocknative-openapi-skill (version 1.0.0)

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

path: agents/openai.yaml
content: interface:
  display_name: "Blocknative Gas Platform"
  short_description: "Operate Blocknative gas price and fee intelligence reads via UXC + curated OpenAPI schema"
  default_prompt: "Use $blocknative-openapi-skill to discover and execute Blocknative gas intelligence read-only operations through UXC with Authorization header auth and polling guardrails."


path: references/blocknative-gas.openapi.json
content: {
  "openapi": "3.0.3",
  "info": {
    "title": "Blocknative Gas Platform",
    "version": "1.0.0",
    "description": "Curated Blocknative gas intelligence operations for UXC."
  },
  "servers": [
    {
      "url": "https://api.blocknative.com"
    }
  ],
  "paths": {
    "/chains": {
      "get": {
        "operationId": "getChains",
        "summary": "List supported chains",
        "responses": {
          "200": {
            "description": "Supported chains",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Chain"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/gasprices/blockprices": {
      "get": {
        "operationId": "getGasPriceBlockPrices",
        "summary": "Get gas price confidence estimates",
        "parameters": [
          {
            "name": "chainid",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "system",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "network",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "confidenceLevels",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated confidence levels such as 70,90,99"
          }
        ],
        "responses": {
          "200": {
            "description": "Gas price block estimates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlockPricesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/gasprices/basefee-estimates": {
      "get": {
        "operationId": "getBaseFeeEstimates",
        "summary": "Get base fee and blob fee estimates",
        "responses": {
          "200": {
            "description": "Base fee estimates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseFeeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/gasprices/distribution": {
      "get": {
        "operationId": "getGasDistribution",
        "summary": "Get pending gas distribution",
        "parameters": [
          {
            "name": "chainid",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Gas distribution",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistributionResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AuthorizationHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    },
    "schemas": {
      "Chain": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "arch": {
            "type": "string"
          },
          "chainId": {
            "type": "integer"
          },
          "label": {
            "type": "string"
          },
          "system": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EstimatedPrice": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "confidence": {
            "type": "number"
          },
          "price": {
            "type": "number"
          },
          "maxPriorityFeePerGas": {
            "type": [
              "number",
              "null"
            ]
          },
          "maxFeePerGas": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "BlockPrice": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "blockNumber": {
            "type": "integer"
          },
          "estimatedTransactionCount": {
            "type": "integer"
          },
          "baseFeePerGas": {
            "type": [
              "number",
              "null"
            ]
          },
          "blobBaseFeePerGas": {
            "type": [
              "number",
              "null"
            ]
          },
          "estimatedPrices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EstimatedPrice"
            }
          }
        }
      },
      "BlockPricesResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "system": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "maxPrice": {
            "type": "number"
          },
          "currentBlockNumber": {
            "type": "integer"
          },
          "msSinceLastBlock": {
            "type": "integer"
          },
          "blockPrices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockPrice"
            }
          }
        }
      },
      "BaseFeeResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "system": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "currentBlockNumber": {
            "type": "integer"
          },
          "msSinceLastBlock": {
            "type": "integer"
          },
          "baseFeePerGas": {
            "type": "number"
          },
          "blobBaseFeePerGas": {
            "type": [
              "number",
              "null"
            ]
          },
          "estimatedBaseFees": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "DistributionResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "system": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "maxPrice": {
            "type": "number"
          },
          "currentBlockNumber": {
            "type": "integer"
          },
          "msSinceLastBlock": {
            "type": "integer"
          },
          "topNDistribution": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "security": [
    {
      "AuthorizationHeader": []
    }
  ]
}


path: references/usage-patterns.md
content: # Blocknative Gas Platform Skill - Usage Patterns

## Link Setup

```bash
command -v blocknative-openapi-cli
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
```

## Auth Setup

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

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

## Read Examples

```bash
# Discover supported chains and their feature flags
blocknative-openapi-cli get:/chains

# Read gas price confidence intervals for Ethereum mainnet
blocknative-openapi-cli get:/gasprices/blockprices \
  chainid=1 \
  confidenceLevels=70,90,99

# Read gas prices by system + network instead of chainid
blocknative-openapi-cli get:/gasprices/blockprices \
  system=story \
  network=mainnet

# Read Ethereum base fee and blob fee predictions
blocknative-openapi-cli get:/gasprices/basefee-estimates

# Read current pending gas distribution for Ethereum mainnet
blocknative-openapi-cli get:/gasprices/distribution \
  chainid=1
```

## Error Handling Pattern

```bash
# Keep error inspection at the UXC envelope level before debugging provider-specific fields
blocknative-openapi-cli get:/gasprices/basefee-estimates | jq '{ok, error, data}'

# If auth is missing or invalid, inspect .error first before assuming the endpoint is unavailable
blocknative-openapi-cli get:/gasprices/distribution chainid=1 | jq '.error'
```

## Fallback Equivalence

- `blocknative-openapi-cli <operation> ...` is equivalent to
  `uxc https://api.blocknative.com --schema-url <blocknative_openapi_schema> <operation> ...`.


path: scripts/validate.sh
content: #!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
SKILL_DIR="${ROOT_DIR}/skills/blocknative-openapi-skill"
SKILL_FILE="${SKILL_DIR}/SKILL.md"
OPENAI_FILE="${SKILL_DIR}/agents/openai.yaml"
USAGE_FILE="${SKILL_DIR}/references/usage-patterns.md"
SCHEMA_FILE="${SKILL_DIR}/references/blocknative-gas.openapi.json"

fail() {
  printf '[validate] error: %s\n' "$*" >&2
  exit 1
}

need_cmd() {
  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
}

need_cmd jq
need_cmd rg

for file in "${SKILL_FILE}" "${OPENAI_FILE}" "${USAGE_FILE}" "${SCHEMA_FILE}"; do
  [[ -f "${file}" ]] || fail "missing required file: ${file}"
done

jq -e '.openapi and .paths and .components' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'invalid OpenAPI schema JSON or missing .openapi/.paths/.components'
jq -e '.paths["/chains"] and .paths["/gasprices/blockprices"] and .paths["/gasprices/basefee-estimates"]' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'OpenAPI schema missing expected Blocknative paths'
jq -e '.paths["/gasprices/distribution"].get and .paths["/gasprices/blockprices"].get' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'OpenAPI schema must expose expected GET operations'

rg -q '^name:\s*blocknative-openapi-skill\s*$' "${SKILL_FILE}" || fail 'invalid skill name'
rg -q '^description:\s*.+' "${SKILL_FILE}" || fail 'missing description'

rg -q 'command -v blocknative-openapi-cli' "${SKILL_FILE}" || fail 'missing link-first command check'
rg -q 'uxc link blocknative-openapi-cli https://api.blocknative.com --schema-url ' "${SKILL_FILE}" || fail 'missing fixed link create command with schema-url'
rg -F -q 'blocknative-openapi-cli get:/gasprices/basefee-estimates -h' "${SKILL_FILE}" || fail 'missing operation-level help example'
rg -q -- '--api-key-header Authorization' "${SKILL_FILE}" || fail 'missing api key setup'
rg -q 'uxc auth binding match https://api.blocknative.com' "${SKILL_FILE}" || fail 'missing binding match check'
rg -q 'once per second' "${SKILL_FILE}" || fail 'missing polling guardrail'

if rg -q -- "--args\\s+'\\{" "${SKILL_FILE}" "${USAGE_FILE}"; then
  fail 'found banned legacy JSON argument pattern'
fi

rg -q '^\s*display_name:\s*"Blocknative Gas Platform"\s*$' "${OPENAI_FILE}" || fail 'missing display_name'
rg -q '^\s*short_description:\s*".+"\s*$' "${OPENAI_FILE}" || fail 'missing short_description'
rg -q '^\s*default_prompt:\s*".*\$blocknative-openapi-skill.*"\s*$' "${OPENAI_FILE}" || fail 'default_prompt must mention $blocknative-openapi-skill'

echo "skills/blocknative-openapi-skill validation passed"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)