openapi.yaml

openapi: 3.1.0
info:
  title: Blockchain Lab Open Data API
  version: 1.1.0
  description: 'Free, static, CORS-enabled JSON datasets for blockchain builders:
    chains, DeFi TVL, stablecoins, yields, bridges, DEX volumes, fees, L2 metrics
    (L2BEAT), security incidents, OFAC-sanctioned addresses, public RPC health, hackathons,
    events, whitepapers, glossary, grants, EIPs/ERCs/BIPs. Versioned (/v1, semver
    schema_version, JSON Schema per dataset). Rebuilt nightly from public sources.
    Built by Blockchain Lab — https://blockchainlab.com'
  contact:
    name: Blockchain Lab
    url: https://blockchainlab.com/?utm_source=github&utm_medium=openapi&utm_campaign=blockchainlab-api
  license:
    name: Code MIT; data belongs to each named source
    url: https://github.com/Blockchains/blockchainlab-api/blob/main/LICENSE
servers:
- url: https://blockchains.github.io/blockchainlab-api
paths:
  /v1/index.json:
    get:
      summary: Dataset catalogue
      operationId: getIndex
      tags:
      - meta
      responses:
        '200':
          description: List of datasets with counts, sources and generation time
          content:
            application/json:
              schema:
                type: object
  /v1/bips.json:
    get:
      summary: Bitcoin Improvement Proposals index parsed from bitcoin/bips.
      operationId: getBips
      tags:
      - datasets
      description: 'Source: github.com/bitcoin/bips (https://github.com/bitcoin/bips).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/bips.schema.json
  /v1/bridges.json:
    get:
      summary: Cross-chain and canonical bridges ranked by TVL (DefiLlama bridge categories).
      operationId: getBridges
      tags:
      - datasets
      description: 'Source: DefiLlama protocols (bridge categories) (https://api.llama.fi/protocols).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/bridges.schema.json
  /v1/chains.json:
    get:
      summary: 'EVM chain registry: chain IDs, native currency, public RPC endpoints
        and explorers.'
      operationId: getChains
      tags:
      - datasets
      description: 'Source: chainid.network (ethereum-lists/chains) (https://chainid.network/chains.json).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/chains.schema.json
  /v1/chains-tvl.json:
    get:
      summary: DeFi TVL by chain (USD). Snapshot from DefiLlama.
      operationId: getChainsTvl
      tags:
      - datasets
      description: 'Source: DefiLlama (https://api.llama.fi/v2/chains). Rebuilt nightly
        by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/chains-tvl.schema.json
  /v1/dex-volumes.json:
    get:
      summary: DEX trading volume by protocol (top 300 by 24h). Snapshot from DefiLlama.
      operationId: getDexVolumes
      tags:
      - datasets
      description: 'Source: DefiLlama overview/dexs (https://api.llama.fi/overview/dexs).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/dex-volumes.schema.json
  /v1/eips.json:
    get:
      summary: EIPS index (number, title, status, type, category) parsed from ethereum/EIPs.
      operationId: getEips
      tags:
      - datasets
      description: 'Source: github.com/ethereum/EIPs (https://github.com/ethereum/EIPs/tree/master/EIPS).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/eips.schema.json
  /v1/ercs.json:
    get:
      summary: ERCS index (number, title, status, type, category) parsed from ethereum/ERCs.
      operationId: getErcs
      tags:
      - datasets
      description: 'Source: github.com/ethereum/ERCs (https://github.com/ethereum/ERCs/tree/master/ERCS).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/ercs.schema.json
  /v1/events.json:
    get:
      summary: Upcoming blockchain events from the Blockchain Lab feeds.
      operationId: getEvents
      tags:
      - datasets
      description: 'Source: Blockchains/blockchainlab-feeds (ethglobal.com/events;
        devpost.com (blockchain hackathons)) (https://raw.githubusercontent.com/Blockchains/blockchainlab-feeds/main/feeds/events/latest.json).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/events.schema.json
  /v1/fees.json:
    get:
      summary: Protocol fees by protocol (top 300 by 24h). Snapshot from DefiLlama.
      operationId: getFees
      tags:
      - datasets
      description: 'Source: DefiLlama overview/fees (https://api.llama.fi/overview/fees).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/fees.schema.json
  /v1/glossary.json:
    get:
      summary: Plain-language blockchain glossary from blockchainlab.com (concepts,
        protocol profiles, failure classes, stack layers).
      operationId: getGlossary
      tags:
      - datasets
      description: 'Source: blockchainlab.com/learn/glossary (https://blockchainlab.com/learn/glossary).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/glossary.schema.json
  /v1/grants.json:
    get:
      summary: Directory of blockchain ecosystem grant / funding programmes with official
        links. Curated by Blockchain Lab; link status re-checked nightly. No amounts
        are listed — read each programme's own page.
      operationId: getGrants
      tags:
      - datasets
      description: 'Source: Official programme pages (curated) (https://github.com/Blockchains/blockchainlab-api/blob/main/data/grants.json).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/grants.schema.json
  /v1/hackathons.json:
    get:
      summary: Open and upcoming blockchain hackathons (Devpost, ETHGlobal).
      operationId: getHackathons
      tags:
      - datasets
      description: 'Source: Blockchains/blockchainlab-feeds (devpost.com/api/hackathons
        (theme Blockchain, open+upcoming); ethglobal.com/events (future hackathons);
        X posts (leads only)) (https://raw.githubusercontent.com/Blockchains/blockchainlab-feeds/main/feeds/hackathons/latest.json).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/hackathons.schema.json
  /v1/l2-metrics.json:
    get:
      summary: 'Ethereum L2/L3 scaling projects: stage, category, stack, risk summary
        and Total Value Secured breakdown. From L2BEAT.'
      operationId: getL2Metrics
      tags:
      - datasets
      description: 'Source: L2BEAT public API (https://l2beat.com/api/scaling/summary).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/l2-metrics.schema.json
  /v1/protocols.json:
    get:
      summary: Top 500 DeFi protocols by TVL (USD), excluding CEXs. Snapshot from
        DefiLlama; not investment advice.
      operationId: getProtocols
      tags:
      - datasets
      description: 'Source: DefiLlama (https://api.llama.fi/protocols). Rebuilt nightly
        by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/protocols.schema.json
  /v1/rpc-health.json:
    get:
      summary: 'Health of popular free public RPC endpoints (EVM chains, Solana, Bitcoin):
        reachability, latency, block lag vs best endpoint, chain-ID check. Probed
        from a GitHub Actions runner (US) at build time.'
      operationId: getRpcHealth
      tags:
      - datasets
      description: 'Source: Blockchain Lab probe (GitHub Actions) (https://github.com/Blockchains/blockchainlab-api/blob/main/scripts/build.mjs).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/rpc-health.schema.json
  /v1/sanctioned-addresses.json:
    get:
      summary: Digital currency addresses on the US Treasury OFAC SDN list, per asset.
        Extracted daily from the official SDN XML by github.com/0xB10C. Compliance
        screening aid only — verify against the official list.
      operationId: getSanctionedAddresses
      tags:
      - datasets
      description: 'Source: OFAC SDN list via 0xB10C/ofac-sanctioned-digital-currency-addresses
        (https://github.com/0xB10C/ofac-sanctioned-digital-currency-addresses/tree/lists).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/sanctioned-addresses.schema.json
  /v1/security-incidents.json:
    get:
      summary: 'Public record of crypto hacks and exploits: date, protocol, technique,
        classification, amount lost/returned. From DefiLlama''s hacks database.'
      operationId: getSecurityIncidents
      tags:
      - datasets
      description: 'Source: DefiLlama hacks (https://api.llama.fi/hacks). Rebuilt
        nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/security-incidents.schema.json
  /v1/stablecoins.json:
    get:
      summary: Stablecoins by circulating supply with price, peg mechanism and 1d/7d/30d
        supply change. Snapshot from DefiLlama.
      operationId: getStablecoins
      tags:
      - datasets
      description: 'Source: DefiLlama stablecoins (https://stablecoins.llama.fi/stablecoins?includePrices=true).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/stablecoins.schema.json
  /v1/whitepapers.json:
    get:
      summary: Blockchain Lab research corpus — whitepaper metadata (no paper text).
        Original sources linked.
      operationId: getWhitepapers
      tags:
      - datasets
      description: 'Source: Blockchain Lab /api/v1/papers (https://blockchainlab.com/api/v1/papers).
        Rebuilt nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/whitepapers.schema.json
  /v1/yields.json:
    get:
      summary: Top 500 DeFi yield pools by TVL (>= $10m) with APY, base/reward split,
        IL risk. Snapshot from DefiLlama; APYs change constantly and are not advice.
      operationId: getYields
      tags:
      - datasets
      description: 'Source: DefiLlama yields (https://yields.llama.fi/pools). Rebuilt
        nightly by GitHub Actions.'
      responses:
        '200':
          description: Dataset envelope
          content:
            application/json:
              schema:
                $ref: https://blockchains.github.io/blockchainlab-api/v1/schemas/yields.schema.json
components:
  schemas:
    Envelope:
      type: object
      required:
      - dataset
      - generated_at
      - source
      - source_url
      - data
      properties:
        dataset:
          type: string
        description:
          type: string
        generated_at:
          type: string
          format: date-time
        source:
          type: string
        source_url:
          type: string
          format: uri
        built_by:
          type: string
        licence_note:
          type: string
        count:
          type: integer
        data:
          type: array
          items:
            type: object