API Documentation

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

Quick Start

New access is pay per call with x402: no account and no API key. An existing subscription's API key keeps working with a Bearer token, as in the examples below.

# List all available series

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

https://darklyenergized.com/api/v1/series

# Fetch data for a series

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

https://darklyenergized.com/api/v1/series/cbdeo

# Get a summary (great for AI agents)

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

"https://darklyenergized.com/api/v1/series/cbdeo?summary=true"

Projects API

A signed-in client, or their agent, can create and edit a project brief with a project token (de_project_…, generated at /projects). POST, GET and PATCH on /api/v1/projects. There is deliberately no submit endpoint; sending is a human step. Full schema in the OpenAPI document.

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/mcp

Model Context Protocol server for agents, with no account or key: listing and freshness are free, and each series is paid per call over x402. See MCP Integration below.

POST/api/v1/mcp

The same tools for an existing API key (Bearer de_live_...), which only subscriptions sold before 2026-10 have.

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 at /mcp: no account and no API key. Listing the series and checking their freshness are free; fetching a series is paid per call over x402, so the client needs a wallet and x402 support for MCP (for example the @x402/mcp client). An unpaid call returns the price; the client pays and repeats it.

{
  "mcpServers": {
    "darklyenergized": {
      "type": "http",
      "url": "https://darklyenergized.com/mcp"
    }
  }
}

An existing API key keeps the same tools at /api/v1/mcp, with an Authorization: Bearer de_live_... header.

Available Tools

de_list_series

Every series x402 sells, with its price per call. Free.

de_get_series

Fetch a series: a summary with interpretation by default, or the most recent 500 points. Paid per call over x402: $0.10 for aggregate series, $0.05 for individual central bank series.

de_get_health

How fresh each series is: its last observation and whether it is stale. Free.

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

The detailed catalog: every series x402 serves, with its details. $0.01 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, priced by its tier (below). Only Darkly Energized computed indicators are available; ids are lowercase (e.g. cbdeo, wresbal_plus, cb_usd_walcl). A raw or unknown id is refused with 403 or 404 before any payment is asked for.

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

summarybooleanReturn statistical summary

POST/api/v1/x402/series/batch

Fetch multiple computed series. The price is the sum of each distinct 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

Request	Price per call (USDC)
Aggregate series · CBDET, CBDEO, WRESBAL+, DRAINS	$0.10
Individual central bank series · Fed, BOJ, ECB, PBoC, BoE, SNB, BoC, BoK (USD)	$0.05
Batch request · Up to 20 series in one call	Sum of each series
Detailed catalog · Every series, with its details	$0.01
Discovery manifest · /.well-known/x402.json	Free

Every series x402 serves, with its tier and price, is listed free at /.well-known/x402.json.

Example

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

curl https://darklyenergized.com/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

Pay-per-call requests are limited per IP address, and a request over the limit answers 429 with a retry time. An existing subscription's API key keeps the daily limit it was sold with.

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.