MacroSignal API Documentation

You need an API key to use the API (Get an API Key), or your application or bot can pay on demand without an account or API key using x402.

Quick start

Authenticate using your API key in the Authorization header:

curl -H "Authorization: Bearer <YOUR_KEY>" https://api.macrosignal/v1/events/next

Public API endpoints

GET /v1/events

List events. Query params: country, window_days (default 7).

curl -H "Authorization: Bearer <YOUR_KEY>" "https://api.macrosignal/v1/events?country=US&window_days=7"

Sample snippet of the response payload:

{
  "country": "US",
  "window_days": 7,
  "generated_at": "2026-03-22T12:00:00Z",
  "events_count": 2,
  "events": [
    {
      "event_definition_id": "us-cpi-yoy",
      "event_instance_id": "us-cpi-2026-03-11",
      "event_instance_name": "US CPI YoY (Mar 2026)",
      "country": "US",
      "category": "inflation",
      "importance": "high",
      "impact_score": 0.9,
      "timestamp": "2026-03-11T08:30:00Z",
      "reference_date": "2026-03-11",
      "previous_value": 0.5,
      "forecast_value": 0.6,
      "actual_value": null
    },
    {
      "event_definition_id": "us-nfp",
      "event_instance_id": "us-nfp-2026-03-06",
      "event_instance_name": "Nonfarm Payrolls (Mar 2026)",
      "country": "US",
      "category": "labor",
      "importance": "high",
      "impact_score": 0.85,
      "timestamp": "2026-03-06T12:30:00Z",
      "reference_date": "2026-03-06",
      "previous_value": 200000,
      "forecast_value": 180000,
      "actual_value": 220000
    }
  ]
}

GET /v1/events/next

Returns the next scheduled high-impact event and minutes until it occurs. Query param: country (optional).

curl -H "Authorization: Bearer <YOUR_KEY>" "https://api.macrosignal/v1/events/next?country=US"

Sample response:

{
  "country": "US",
  "minutes_until_next_high_impact_event": 45,
  "next_event": {
    "event_definition_id": "us-cpi-yoy",
    "event_instance_id": "us-cpi-2026-03-11",
    "event_instance_name": "US CPI YoY (Mar 2026)",
    "country": "US",
    "category": "inflation",
    "importance": "high",
    "impact_score": 0.9,
    "timestamp": "2026-03-11T08:30:00Z",
    "reference_date": "2026-03-11",
    "previous_value": 0.5,
    "forecast_value": 0.6,
    "actual_value": null
  }
}

GET /v1/events/impact_today

Shows events for today and whether there's elevated risk.

curl -H "Authorization: Bearer <YOUR_KEY>" "https://api.macrosignal/v1/events/impact_today?country=US"

Sample response:

{
  "country": "US",
  "risk_today": true,
  "events": [
    {
      "event_definition_id": "us-nfp",
      "event_instance_id": "us-nfp-2026-03-06",
      "event_instance_name": "Nonfarm Payrolls (Mar 2026)",
      "country": "US",
      "category": "labor",
      "importance": "high",
      "impact_score": 0.85,
      "timestamp": "2026-03-06T12:30:00Z",
      "reference_date": "2026-03-06",
      "previous_value": 200000,
      "forecast_value": 180000,
      "actual_value": 220000
    }
  ]
}

OpenAPI spec

The machine-readable OpenAPI spec (YAML) is available here: /static/openapi.yaml

Back