Skip to main content

​
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
  }
}
FieldDescription
valCurrent value
val_7dValue 7 days ago
val_30dValue 30 days ago
val_90dValue 90 days ago
chg_7d_amtAbsolute change over 7 days
chg_7d_pctPercentage change over 7 days
chg_30d_amtAbsolute change over 30 days
chg_30d_pctPercentage change over 30 days
chg_90d_amtAbsolute change over 90 days
chg_90d_pctPercentage 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

StatusDescription
200Success
400Bad Request — invalid query, filter, or parameters
401Unauthorized — missing or invalid API key
405Method Not Allowed — endpoint only supports GET
429Too Many Requests — rate limit exceeded
500Internal 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