Blockworks Projects & Entities API

openapi: 3.2.0
info:
  description: The Blockworks Data API is a unified, read-only REST interface to Blockworks' warehouse-modeled crypto dataset, powered by Messari's research and data infrastructure.
  title: Blockworks Data Projects & Entities API
  version: 0.1.0
servers:
- description: Blockworks API
  url: https://api.blockworks.com
security:
- apiKey: []
tags:
- description: 'Models documented under Projects & Entities: Projects (timeseries).'
  name: Projects & Entities
paths:
  /query/timeseries/projects/{granularity}:
    get:
      description: 'Fundamentals for a project on its primary ecosystem network: protocol revenue, TVL, primary asset market cap, stablecoin supply, DEX volume and mindshare. Each series is one project, keyed by its project id. Only the metrics that apply to a project are populated, so pass selections.'
      operationId: getTimeseries_projects
      parameters:
      - description: Data granularity.
        in: path
        name: granularity
        required: true
        schema:
          enum:
          - 1d
          type: string
      - description: 'Comma-separated Project ID values naming the series to return (up to 10). Required: this model has too many series to return at once.'
        in: query
        name: series
        required: true
        schema:
          type: string
      - description: 'Time window, one of: to-date (ytd, qtd, mtd, dtd, htd); relative, <n> followed by m, h, d or w (30d, 12h, 4w; 1y and 1M are not accepted, use 365d, 52w, ytd or a calendar year); a calendar day (YYYY-MM-DD), month (YYYY-MM) or year (YYYY); or an RFC3339 instant, which runs from then to now. Mutually exclusive with start/end. Default: everything retained, up to now.'
        in: query
        name: timeframe
        schema:
          type: string
      - description: 'Window start, inclusive (RFC3339, unix seconds, or YYYY-MM-DD). Default: unbounded.'
        in: query
        name: start
        schema:
          type: string
      - description: 'Window end, exclusive (RFC3339, unix seconds, or YYYY-MM-DD). Default: now.'
        in: query
        name: end
        schema:
          type: string
      - description: If true, return only the first and last point of the resolved time window instead of every point in it.
        in: query
        name: bounds
        schema:
          type: boolean
      - description: Comma-separated metric fields to return; defaults to every metric. A point always leads with its timestamp, and the values that follow are described by point_schema in catalog order regardless of the order requested here.
        in: query
        name: selections
        schema:
          items:
            enum:
            - primary-ecosystem-revenue-usd
            - primary-ecosystem-revenue-usd-rolling-7d
            - primary-ecosystem-tvl-usd
            - primary-asset-circulating-marketcap-usd
            - stablecoin-outstanding-supply-usd
            - dex-volume-usd
            - mindshare-score
            - mindshare-score-rolling-7d
            - mindshare-rank
            type: string
          type: array
      - description: 'Response format, overriding the Accept header: json (default), csv, or jsonl (NDJSON). csv and jsonl return the rows as a downloadable file.'
        in: query
        name: acceptFormat
        schema:
          default: json
          enum:
          - json
          - csv
          - jsonl
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  point_schema:
                  - description: Timestamp of the data point.
                    field: time
                    name: Time
                    time: true
                    type: time
                  - description: Share of fees that goes to the protocol.
                    field: primary-ecosystem-revenue-usd
                    name: Primary Ecosystem Revenue USD
                    time: false
                    type: float64
                    unit: usd
                  - description: Rolling 7D average of share of fees that goes to the protocol.
                    field: primary-ecosystem-revenue-usd-rolling-7d
                    name: Primary Ecosystem Revenue USD Rolling 7D
                    time: false
                    type: float64
                    unit: usd
                  series:
                  - entity:
                      name: <name>
                      slug: <slug>
                    key: <Project ID>
                    points:
                    - - 1704067200
                      - 123.45
                      - 123.45
                error: null
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectsData'
                  error:
                    type:
                    - string
                    - 'null'
                required:
                - data
                type: object
            application/x-ndjson:
              schema:
                description: JSON Lines (NDJSON); one JSON object per line.
                type: string
            text/csv:
              schema:
                description: CSV with a header row; one row per record.
                type: string
          description: Timeseries points for each series.
        '400':
          content:
            application/json:
              example:
                data: null
                error: 'too many series requested: 11 exceeds the maximum of 10'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The request is malformed: an empty, duplicated or too long series list (at most 10 keys), an unknown query parameter, an unrecognized timeframe (1y and 1M are not accepted; use 365d, 52w, ytd or a calendar year), timeframe combined with start or end, an unknown selections field, or an invalid bounds or acceptFormat value.'
        '401':
          content:
            application/json:
              example:
                data: null
                error: this model requires authentication
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No API key was sent and the model requires one.
        '403':
          content:
            application/json:
              example:
                data: null
                error: this model requires the "projects_protocols_unified" permission
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The API key is not valid, or does not hold the "projects_protocols_unified" permission.
        '404':
          content:
            application/json:
              example:
                data: null
                error: the all-series endpoint is not available for model "projects"; request specific series via ?series or a series-key path
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The series parameter was omitted: this model does not return every series at once, so name the ones you want. Also returned when the path names a model that does not exist or a granularity the model is not available at.'
      summary: Batch Get Project timeseries
      tags:
      - Projects & Entities
      x-badges:
      - color: '#7c3aed'
        name: projects_protocols_unified
        position: after
      x-mint:
        metadata:
          sidebarTitle: Batch Get Project timeseries
          title: Batch Get Project timeseries
      x-series-key-entity: projects
  /query/timeseries/projects/{granularity}/{id}:
    get:
      description: 'Fundamentals for a project on its primary ecosystem network: protocol revenue, TVL, primary asset market cap, stablecoin supply, DEX volume and mindshare. Each series is one project, keyed by its project id. Only the metrics that apply to a project are populated, so pass selections.'
      operationId: getTimeseriesSeries_projects
      parameters:
      - description: Data granularity.
        in: path
        name: granularity
        required: true
        schema:
          enum:
          - 1d
          type: string
      - description: 'The Project ID identifying the series. A key no series has is not an error: the response carries an empty points array.'
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: 'Time window, one of: to-date (ytd, qtd, mtd, dtd, htd); relative, <n> followed by m, h, d or w (30d, 12h, 4w; 1y and 1M are not accepted, use 365d, 52w, ytd or a calendar year); a calendar day (YYYY-MM-DD), month (YYYY-MM) or year (YYYY); or an RFC3339 instant, which runs from then to now. Mutually exclusive with start/end. Default: everything retained, up to now.'
        in: query
        name: timeframe
        schema:
          type: string
      - description: 'Window start, inclusive (RFC3339, unix seconds, or YYYY-MM-DD). Default: unbounded.'
        in: query
        name: start
        schema:
          type: string
      - description: 'Window end, exclusive (RFC3339, unix seconds, or YYYY-MM-DD). Default: now.'
        in: query
        name: end
        schema:
          type: string
      - description: If true, return only the first and last point of the resolved time window instead of every point in it.
        in: query
        name: bounds
        schema:
          type: boolean
      - description: Comma-separated metric fields to return; defaults to every metric. A point always leads with its timestamp, and the values that follow are described by point_schema in catalog order regardless of the order requested here.
        in: query
        name: selections
        schema:
          items:
            enum:
            - primary-ecosystem-revenue-usd
            - primary-ecosystem-revenue-usd-rolling-7d
            - primary-ecosystem-tvl-usd
            - primary-asset-circulating-marketcap-usd
            - stablecoin-outstanding-supply-usd
            - dex-volume-usd
            - mindshare-score
            - mindshare-score-rolling-7d
            - mindshare-rank
            type: string
          type: array
      - description: 'Response format, overriding the Accept header: json (default), csv, or jsonl (NDJSON). csv and jsonl return the rows as a downloadable file.'
        in: query
        name: acceptFormat
        schema:
          default: json
          enum:
          - json
          - csv
          - jsonl
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  entity:
                    name: <name>
                    slug: <slug>
                  key: <Project ID>
                  point_schema:
                  - description: Timestamp of the data point.
                    field: time
                    name: Time
                    time: true
                    type: time
                  - description: Share of fees that goes to the protocol.
                    field: primary-ecosystem-revenue-usd
                    name: Primary Ecosystem Revenue USD
                    time: false
                    type: float64
                    unit: usd
                  - description: Rolling 7D average of share of fees that goes to the protocol.
                    field: primary-ecosystem-revenue-usd-rolling-7d
                    name: Primary Ecosystem Revenue USD Rolling 7D
                    time: false
                    type: float64
                    unit: usd
                  points:
                  - - 1704067200
                    - 123.45
                    - 123.45
                error: null
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectsSeriesData'
                  error:
                    type:
                    - string
                    - 'null'
                required:
                - data
                type: object
            application/x-ndjson:
              schema:
                description: JSON Lines (NDJSON); one JSON object per line.
                type: string
            text/csv:
              schema:
                description: CSV with a header row; one row per record.
                type: string
          description: Timeseries points for the series.
        '400':
          content:
            application/json:
              example:
                data: null
                error: 'unrecognized timeframe "1y": expected ytd|qtd|mtd|dtd|htd, <n>m|h|d|w, YYYY-MM-DD, YYYY-MM, YYYY, or RFC3339'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The request is malformed: an unknown query parameter, an unrecognized timeframe (1y and 1M are not accepted; use 365d, 52w, ytd or a calendar year), timeframe combined with start or end, a start after the end, an unknown selections field, or an invalid bounds or acceptFormat value.'
        '401':
          content:
            application/json:
              example:
                data: null
                error: this model requires authentication
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No API key was sent and the model requires one.
        '403':
          content:
            application/json:
              example:
                data: null
                error: this model requires the "projects_protocols_unified" permission
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: The API key is not valid, or does not hold the "projects_protocols_unified" permission.
        '404':
          content:
            application/json:
              example:
                data: null
                error: 'model "projects" does not support granularity "1h" (supported: 1d)'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'The path names a model that does not exist ("no timeseries model ..."), or a granularity the model is not available at. An unknown series key is not a 404: it returns 200 with an empty points array.'
      summary: Get Project timeseries
      tags:
      - Projects & Entities
      x-badges:
      - color: '#7c3aed'
        name: projects_protocols_unified
        position: after
      x-mint:
        metadata:
          sidebarTitle: Get Project timeseries
          title: Get Project timeseries
      x-series-key-entity: projects
components:
  schemas:
    ErrorResponse:
      properties:
        data:
          description: Always null on an error.
          type:
          - object
          - 'null'
        error:
          description: What went wrong, in one sentence.
          type: string
      required:
      - error
      - data
      type: object
    ProjectsSeriesData:
      properties:
        entity:
          description: Information about what the series key identifies, from the "projects" model.
          properties:
            name:
              description: The name of the project.
              type:
              - string
              - 'null'
            slug:
              description: The URL slug of the project.
              type:
              - string
              - 'null'
          type: object
        key:
          type: string
        point_schema:
          items:
            properties:
              description:
                type: string
              field:
                type: string
              name:
                type: string
              time:
                type: boolean
              type:
                type: string
              unit:
                description: What the value is denominated in. Absent for a plain number.
                enum:
                - usd
                - btc
                - sats
                - eth
                - gwei
                - native-token
                - percent
                - count
                - ratio
                type: string
            type: object
          type: array
        points:
          items:
            description: A unix timestamp (seconds) followed by the metric values, in point_schema order.
            items:
              type:
              - number
              - 'null'
            type: array
          type: array
      required:
      - point_schema
      - key
      - points
      type: object
    ProjectsData:
      properties:
        point_schema:
          items:
            properties:
              description:
                type: string
              field:
                type: string
              name:
                type: string
              time:
                type: boolean
              type:
                type: string
              unit:
                description: What the value is denominated in. Absent for a plain number.
                enum:
                - usd
                - btc
                - sats
                - eth
                - gwei
                - native-token
                - percent
                - count
                - ratio
                type: string
            type: object
          type: array
        series:
          items:
            properties:
              entity:
                description: Information about what the series key identifies, from the "projects" model.
                properties:
                  name:
                    description: The name of the project.
                    type:
                    - string
                    - 'null'
                  slug:
                    description: The URL slug of the project.
                    type:
                    - string
                    - 'null'
                type: object
              key:
                type: string
              points:
                items:
                  description: A unix timestamp (seconds) followed by the metric values, in point_schema order.
                  items:
                    type:
                    - number
                    - 'null'
                  type: array
                type: array
            type: object
          type: array
      required:
      - point_schema
      - series
      type: object
  securitySchemes:
    apiKey:
      description: API key sent in the `X-Blockworks-API-Key` header; `x-messari-api-key` is accepted for existing integrations. The catalog endpoints and models on the public access tier need no key.
      in: header
      name: X-Blockworks-API-Key
      type: apiKey
x-tagGroups:
- name: Meta
  tags:
  - Tabular
  - Timeseries
- name: Market Data
  tags:
  - Assets
  - Markets
  - Exchanges
  - Derivatives
  - Market Overview
- name: Blockchains
  tags:
  - Blockchains
- name: Projects & Protocols
  tags:
  - Projects & Entities
  - Protocol Revenue
  - Lending Protocols
  - Spot DEXes
  - Perp DEXes
  - Vaults
  - Launchpads
  - TCG Platforms
- name: Real World Assets
  tags:
  - Stablecoins
  - Tokenized Equities
  - Tokenized Commodities
- name: Institutional
  tags:
  - ETFs
  - Digital Asset Treasuries
- name: Fundraising
  tags:
  - Funding Rounds
  - Funds & Investors
  - Acquisitions
- name: Social & Mindshare
  tags:
  - Social & Mindshare
- name: News & Research
  tags:
  - News & Research
- name: Token Transparency Framework
  tags:
  - Token Transparency Framework