{
  "openapi": "3.0.0",
  "info": {
    "description": "The Bulk API provides access to download large timeseries datasets in CSV or JSONL format. This API is optimized for downloading historical data at scale, supporting multiple granularities and dataset types.",
    "title": "Messari API - Bulk V1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "description": "Messari Bulk API",
      "url": "https://api.messari.io"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/bulk/v1/datasets": {
      "get": {
        "description": "Lists all bulk datasets available to the authenticated user based on their subscription tier. Each dataset includes its name, slug, description, required tier, available columns, and supported granularities.",
        "operationId": "GetBulkDatasets",
        "tags": [
          "Bulk API"
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved available datasets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkCatalog"
                },
                "example": {
                  "error": null,
                  "data": {
                    "datasets": [
                      {
                        "name": "Asset Marketcap",
                        "slug": "asset-marketcap",
                        "description": "Daily market capitalization for an asset",
                        "tier": "enterprise",
                        "columns": [
                          {
                            "name": "Circulating Marketcap",
                            "slug": "circulating-marketcap",
                            "description": "The market capitalization of the asset, calculated using the circulating supply",
                            "type": "float64"
                          },
                          {
                            "name": "Circulating Marketcap Dominance",
                            "slug": "circulating-marketcap-dominance",
                            "description": "The market capitalization of the asset as a percentage of the total market capitalization of all crypto assets",
                            "type": "float64"
                          },
                          {
                            "name": "Fully Diluted Marketcap",
                            "slug": "fully-diluted-marketcap",
                            "description": "The market capitalization of the asset, calculated using the fully diluted supply. Commonly known as Fully Diluted Valuation (FDV).",
                            "type": "float64"
                          }
                        ],
                        "granularities": [
                          "1d",
                          "1w"
                        ]
                      },
                      {
                        "name": "Asset Price",
                        "slug": "asset-price",
                        "description": "Daily volume weighted average price and volume for an asset",
                        "tier": "enterprise",
                        "columns": [
                          {
                            "name": "Open Price",
                            "slug": "open",
                            "description": "Price at the candle open.",
                            "type": "float64"
                          },
                          {
                            "name": "High Price",
                            "slug": "high",
                            "description": "High price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Low Price",
                            "slug": "low",
                            "description": "Low price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Close Price",
                            "slug": "close",
                            "description": "Price at the candle close.",
                            "type": "float64"
                          },
                          {
                            "name": "Volume",
                            "slug": "volume",
                            "description": "Volume traded during candle.",
                            "type": "float64"
                          }
                        ],
                        "granularities": [
                          "1d",
                          "1w"
                        ]
                      },
                      {
                        "name": "Asset Supply",
                        "slug": "asset-supply",
                        "description": "Daily supply metrics for an asset",
                        "tier": "enterprise",
                        "columns": [
                          {
                            "name": "Circulating Supply",
                            "slug": "circulating-supply",
                            "description": "The number of tokens that exist, excluding those that are locked in contracts or otherwise not available for trading",
                            "type": "float64"
                          },
                          {
                            "name": "Total Supply",
                            "slug": "total-supply",
                            "description": "The total number of tokens that exist",
                            "type": "float64"
                          }
                        ],
                        "granularities": [
                          "1d",
                          "1w"
                        ]
                      },
                      {
                        "name": "Market",
                        "slug": "market",
                        "description": "Market time series data.",
                        "tier": "enterprise",
                        "columns": [
                          {
                            "name": "Open Price",
                            "slug": "open-price",
                            "description": "USD price at the candle open.",
                            "type": "float64"
                          },
                          {
                            "name": "Open Price Raw",
                            "slug": "open-price-raw",
                            "description": "Raw price at the candle open.",
                            "type": "float64"
                          },
                          {
                            "name": "High Price",
                            "slug": "high-price",
                            "description": "High USD price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "High Price Raw",
                            "slug": "high-price-raw",
                            "description": "Raw high price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Low Price",
                            "slug": "low-price",
                            "description": "Low USD price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Low Price Raw",
                            "slug": "low-price-raw",
                            "description": "Raw low price during the candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Close Price",
                            "slug": "close-price",
                            "description": "USD price at the candle close.",
                            "type": "float64"
                          },
                          {
                            "name": "Close Price Raw",
                            "slug": "close-price-raw",
                            "description": "Raw price at the candle close.",
                            "type": "float64"
                          },
                          {
                            "name": "Volume",
                            "slug": "volume",
                            "description": "Volume traded during candle.",
                            "type": "float64"
                          },
                          {
                            "name": "Volume Raw",
                            "slug": "volume-raw",
                            "description": "Raw volume traded during candle.",
                            "type": "float64"
                          }
                        ],
                        "granularities": [
                          "1d",
                          "1w"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/bulk/v1/datasets/{datasetSlug}/{granularity}/data": {
      "get": {
        "description": "Downloads bulk timeseries data for a specific dataset at a given granularity. Data can be exported in CSV or JSONL format. The response includes all metric columns configured for bulk output. Time range is limited to prevent excessive data downloads.",
        "operationId": "DownloadBulkDatasetData",
        "tags": [
          "Bulk API"
        ],
        "parameters": [
          {
            "name": "datasetSlug",
            "in": "path",
            "required": true,
            "description": "Dataset slug identifier. Use /bulk/v1/datasets to see all available datasets.",
            "schema": {
              "type": "string",
              "enum": [
                "asset-marketcap",
                "asset-price",
                "asset-supply",
                "market"
              ],
              "default": "asset-price"
            }
          },
          {
            "name": "granularity",
            "in": "path",
            "required": true,
            "description": "Data granularity interval",
            "schema": {
              "type": "string",
              "enum": [
                "1d",
                "1w"
              ],
              "default": "1d"
            }
          },
          {
            "name": "rangeStart",
            "in": "query",
            "required": true,
            "description": "Start of time range in ISO 8601 format",
            "schema": {
              "type": "string",
              "format": "date-time",
              "default": "2025-10-01T00:00:00Z",
              "example": "2025-10-01T00:00:00Z"
            }
          },
          {
            "name": "rangeEnd",
            "in": "query",
            "required": true,
            "description": "End of time range in ISO 8601 format",
            "schema": {
              "type": "string",
              "format": "date-time",
              "default": "2025-10-07T23:59:59Z",
              "example": "2025-10-07T23:59:59Z"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Output format for the data",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "jsonl"
              ],
              "default": "csv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully generated and streaming bulk data file",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "asset_id,timestamp,price_usd,market_cap_usd\nbtc,2024-01-01T00:00:00Z,42500.50,834215000000\neth,2024-01-01T00:00:00Z,2250.75,270500000000\n"
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "example": "{\"asset_id\":\"btc\",\"timestamp\":\"2024-01-01T00:00:00Z\",\"price_usd\":42500.50,\"market_cap_usd\":834215000000}\n{\"asset_id\":\"eth\",\"timestamp\":\"2024-01-01T00:00:00Z\",\"price_usd\":2250.75,\"market_cap_usd\":270500000000}\n"
              }
            },
            "headers": {
              "Content-Disposition": {
                "description": "Suggests filename for downloaded file",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=asset_price_1d_2024-01-01_2024-12-31.csv"
                }
              },
              "Content-Type": {
                "description": "MIME type of the response",
                "schema": {
                  "type": "string",
                  "example": "text/csv; charset=utf-8"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters, time range, or format",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "examples": {
                  "invalidRange": {
                    "value": {
                      "error": "invalid range: 2024-01-01T00:00:00Z to 2023-01-01T00:00:00Z"
                    }
                  },
                  "invalidFormat": {
                    "value": {
                      "error": "invalid format: xml"
                    }
                  },
                  "rangeExceeded": {
                    "value": {
                      "error": "requested time range exceeds maximum allowed for this granularity"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - insufficient subscription tier for this dataset",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Not found - dataset does not exist",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-messari-api-key",
        "description": "API key for authentication. Get your key at https://messari.io/account/api"
      }
    },
    "schemas": {
      "BulkCatalog": {
        "type": "object",
        "properties": {
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BulkDataset"
            }
          }
        }
      },
      "BulkDataset": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable name of the dataset"
          },
          "slug": {
            "type": "string",
            "description": "URL-safe identifier for the dataset"
          },
          "description": {
            "type": "string",
            "description": "Detailed description of what data this dataset contains"
          },
          "tier": {
            "type": "string",
            "enum": [
              "FREE",
              "PROFESSIONAL",
              "ENTERPRISE"
            ],
            "description": "Minimum subscription tier required to access this dataset"
          },
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BulkColumn"
            },
            "description": "List of columns available in this dataset"
          },
          "granularities": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "1d",
                "1w"
              ]
            },
            "description": "Available time granularities for this dataset"
          }
        }
      },
      "BulkColumn": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable name of the column"
          },
          "slug": {
            "type": "string",
            "description": "Column identifier used in the data output"
          },
          "description": {
            "type": "string",
            "description": "Detailed description of what this column represents"
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "float",
              "integer",
              "timestamp",
              "boolean"
            ],
            "description": "Data type of the column"
          }
        }
      }
    }
  }
}