Responses

Response Format

All successful API responses follow this structure:

{
  "results": [...],
  "filter": {...},
  "sort": {...},
  "pagination": {
    "page": 1,
    "perPage": 50,
    "pageCount": 10,
    "resultCount": 487
  }
}

Response Fields

results - Array of result objects
filter - Applied filter (if any)
sort - Applied sort configuration
pagination - Pagination metadata
- page - Current page number
- perPage - Results per page
- pageCount - Total number of pages
- resultCount - Total number of results matching the query

Metric Objects

Numeric metrics on assets and tokens are returned as objects containing the current value plus historical snapshots and deltas:

{
  "circulating_market_value_dollar": {
    "val": 2394947347.33,
    "val_7d": 2118658299.28,
    "val_30d": 1950000000.00,
    "val_90d": 1200000000.00,
    "chg_7d_amt": 276289048.05,
    "chg_7d_pct": 13.04,
    "chg_30d_amt": 444947347.33,
    "chg_30d_pct": 22.82,
    "chg_90d_amt": 1194947347.33,
    "chg_90d_pct": 99.58
  }
}

Field	Description
`val`	Current value
`val_7d`	Value 7 days ago
`val_30d`	Value 30 days ago
`val_90d`	Value 90 days ago
`chg_7d_amt`	Absolute change over 7 days
`chg_7d_pct`	Percentage change over 7 days
`chg_30d_amt`	Absolute change over 30 days
`chg_30d_pct`	Percentage change over 30 days
`chg_90d_amt`	Absolute change over 90 days
`chg_90d_pct`	Percentage change over 90 days

Not all fields are present on every metric — only periods with available data are included.

Timeseries Responses

Aggregate timeseries endpoints (/v4/assets/aggregates/timeseries, /v4/tokens/aggregates/timeseries) return a different shape. Each result contains a measure descriptor, a group descriptor, and an array of points:

{
  "results": [
    {
      "measure": {
        "id": 3,
        "slug": "net_asset_value_dollar",
        "name": "Net Asset Value (Dollar)",
        "unit": "dollar"
      },
      "group": {
        "id": 51,
        "type": "asset",
        "name": "Circle USYC",
        "color": "#2A3758"
      },
      "points": [
        ["2023-10-19", 1.01577],
        ["2023-10-20", 1.01590]
      ]
    }
  ],
  "pagination": { "page": 1, "perPage": 30, "pageCount": 1, "resultCount": 1 }
}

measure — the metric being returned (use the Data Catalog to discover available measures)
group — what the data is grouped by (e.g., a specific asset, token, or asset class)
points — array of [date, value] pairs in chronological order

Error Handling

HTTP Status Codes

Status	Description
`200`	Success
`400`	Bad Request — invalid query, filter, or parameters
`401`	Unauthorized — missing or invalid API key
`405`	Method Not Allowed — endpoint only supports GET
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "message": "Error description"
}

Common Errors

Invalid Filter

{
  "message": "Invalid filter format"
}

Invalid Operator

{
  "message": "Invalid operator 'invalidOp' for field 'market_value_dollar'"
}

Rate Limit Exceeded

When you exceed a rate limit, the API returns 429 with headers indicating when you can retry. See Rate Limits for details.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000

Home

Methodology

Frameworks

Data Schemas

MCP Server

API

Response Format

Response Fields

Metric Objects

Timeseries Responses

Error Handling

HTTP Status Codes

Error Response Format

Common Errors

Invalid Filter

Invalid Operator

Rate Limit Exceeded

​Response Format

​Response Fields

​Metric Objects

​Timeseries Responses

​Error Handling

​HTTP Status Codes

​Error Response Format

​Common Errors

​Invalid Filter

​Invalid Operator

​Rate Limit Exceeded

Response Format

Response Fields

Metric Objects

Timeseries Responses

Error Handling

HTTP Status Codes

Error Response Format

Common Errors

Invalid Filter

Invalid Operator

Rate Limit Exceeded