API Documentation

Access financial data, computed series, and market intelligence through a unified REST API.

Quick Start

All API endpoints require authentication via Bearer token. Get your API key from your dashboard.

# List all available series

curl -H "Authorization: Bearer de_live_..." \

/api/v1/series

# Fetch data for a series

curl -H "Authorization: Bearer de_live_..." \

/api/v1/series/CBDEO

# Get a summary (great for AI agents)

curl -H "Authorization: Bearer de_live_..." \

"/api/v1/series/CBDEO?summary=true"

Endpoints

GET/api/v1/series

List all available series. Supports filtering by category, source, and search.

categorystringFilter by category (e.g. "Central Bank", "Equities")

sourcestringFilter by source (e.g. "FRED", "DarklyEnergized")

searchstringSearch by name, ID, or description

GET/api/v1/series/:id

Fetch time-series data for a series. Supports date range, pagination, and summary mode.

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

limitintegerMax data points (default 500, max 10000)

afterdatePagination cursor — return data after this date

summarybooleanReturn statistical summary instead of raw data

POST/api/v1/series/batch

Fetch multiple series in one call. Up to 20 series per request.

idsstring[]Array of series IDs (required)

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

summarybooleanReturn summaries instead of raw data

POST/api/v1/mcp

Model Context Protocol endpoint for AI agent integration. Connect Darkly Energized as an MCP server in Claude Desktop, Claude Code, or other MCP clients.

Response Format

All responses follow a consistent envelope with data and meta fields.

{
  "data": {
    "id": "CBDEO",
    "name": "Dark Energy Divergence Oscillator",
    "description": "CBDEO measures the divergence...",
    "category": "Liquidity",
    "frequency": "daily",
    "data": [
      { "time": "2026-02-14", "value": 1.23 },
      { "time": "2026-02-13", "value": 0.87 }
    ]
  },
  "meta": {
    "timestamp": "2026-02-16T12:00:00Z",
    "count": 540,
    "dataRange": { "from": "2024-01-01", "to": "2026-02-14" },
    "freshness": {
      "lastObservation": "2026-02-14",
      "frequency": "daily",
      "isStale": false
    },
    "pagination": {
      "hasMore": true,
      "cursor": "2025-01-15",
      "total": 540
    }
  }
}

MCP Integration

Connect Darkly Energized as an MCP server in any MCP-compatible client. Add this to your MCP configuration:

{
  "mcpServers": {
    "darklyenergized": {
      "serverUrl": "/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer de_live_..."
      }
    }
  }
}

Available Tools

de_list_series

Discover available data series. Filter by category, source, or search term.

de_get_series

Fetch data for any series. Returns context-efficient summaries by default (~200 bytes) or raw data points.

de_get_health

Check data freshness and staleness for monitoring data quality.

x402 Pay-Per-Call (AI Agents)

AI agents can access data without an account or API key using x402 micropayments in USDC on Base. The agent sends a request, receives a 402 with pricing, signs a USDC payment, and retries — data is returned instantly.

Endpoints

GET/api/v1/x402/series

List available computed series. $0.005 per request.

categorystringFilter by category

sourcestringFilter by source

searchstringSearch by name or ID

GET/api/v1/x402/series/:id

Fetch data for a single computed series. $0.02 per request. Only DarklyEnergized computed indicators are available (e.g. WRESBAL+, CBDEO, CBDET, ICDO).

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

summarybooleanReturn statistical summary

POST/api/v1/x402/series/batch

Fetch multiple computed series. $0.02 per series in the batch.

idsstring[]Array of computed series IDs (required)

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

summarybooleanReturn summaries instead of raw data

Pricing

Endpoint	Price (USDC)
Catalog listing	$0.005
Computed series (e.g. WRESBAL+, CBDEO, CBDET)	$0.02
Batch request	$0.02 per series

Example

# Returns 402 with payment-required header (no auth needed)

curl /api/v1/x402/series/CBDEO

x402 access is limited to computed series only. Rate limits: 200 requests per 5 minutes per IP. By making a payment, you agree to our Terms of Service. Use @x402/fetch or any x402-compatible client to handle payment automatically. See the x402 buyer quickstart for setup instructions.

Rate Limits

Plan	Daily Limit
Basic	100 requests/day
Pro	1,000 requests/day
Enterprise	10,000 requests/day (contact us for more)

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Limits reset at midnight UTC.

OpenAPI Specification

The full OpenAPI 3.1 specification is available at /api/v1/openapi.json. Import it into your favorite API client (Postman, Insomnia, etc.) for testing.