Butterfly Effect Engine API

Turn verified world events into structured market intelligence inside your own product. Authenticate with an API key, pay by usage, and stream our intelligence feed, forecasts, and recommendations as JSON.

API-key auth JSON responses Self-serve keys Usage metering

Starter API

$199/month

10,000 API calls per month.

Growth API

Enterprise API

Custom

Millions of API calls — custom pricing.

Contact Sales

Authentication

Every request must include your API key. Pass it in the X-API-Key header, or as an apiKey field in the JSON body.

curl -X POST https://<your-app>.base44.app/api/functions/apiEvents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bee_sk_your_key_here" \
  -d '{"limit": 5}'

Endpoints

POST/v1/events

The live intelligence feed — summarized market-impact events.

Params: category, severity, limit

POST/v1/events/:id

Full intelligence card for a single event (cascade, sources, forecasts).

Params: id

POST/v1/recommendations

Latest AI-generated Buy/Sell/Hold/Hedge recommendations.

Params: limit

POST/v1/forecasts/:event_id

Forecasts issued for an event, with probability & accuracy status.

Params: event_id

Public Schema & Changelog

v1.0.0 Stability contract: required & read-only fields are guaranteed; optional fields may evolve. Breaking changes bump the major version with 30 days' notice.

Build with confidence against a documented, versioned contract. Every event and forecast our API returns conforms to the schemas below. Copy the JSON Schema into your validators, codegen, or ingestion pipeline.

Eventresource

Field	Type	Constraints	Description
idro	string	—	Unique event identifier.
created_datero	date-time	—	Record creation timestamp (ISO 8601).
updated_datero	date-time	—	Last update timestamp (ISO 8601).
title*	string	—	Short headline of the event.
summary	string	—	One-paragraph plain-language summary.
category*	string	GeopoliticalMacroeconomicWeather & ClimateEnergyCommodityCritical MaterialsSupply ChainCorporateCryptocurrencyTechnologyAgriculturePublic HealthPeople & LeadershipMarket InterdependenceTrade & TariffsCurrency & FXFixed Income & RatesRegulatory & Policy	Event domain.
geography	string	—	Region or market scope, e.g. "Global", "US", "EU".
severity	string	LowModerateHighSevere	Market-impact severity tier.
verification_level	string	UnverifiedSingle SourceCross-VerifiedOfficial	Source-verification tier.
event_date*	date-time	—	When the event occurred or is scheduled to occur.
market_impact	string	—	AI market-impact analysis (prose).
affected_markets	array<string>	—	Tickers, sectors, or indexes the event touches.
cascade_effects	array<object>	—	Ordered economic cascade.
confirmation_signals	array<string>	—	Signals that would confirm the thesis.
invalidation_conditions	array<string>	—	Conditions that would invalidate the thesis (kill-switch).
forecast_direction	string	BullishBearishNeutral	Net forecast direction.
forecast_probability	number	0…100	Forecast probability, percent.
confidence_score	number	0…100	Confidence in the analysis, percent.
status	string	ActiveMonitoringResolvedArchived	Lifecycle status.
sources	array<object>	—	Source provenance.
image_url	string	—	Optional illustrative image URL.

Forecastresource

Field	Type	Constraints	Description
idro	string	—	Unique forecast identifier.
created_datero	date-time	—	Record creation timestamp (ISO 8601).
updated_datero	date-time	—	Last update timestamp (ISO 8601).
event_id	string	—	Linked Event id.
event_title*	string	—	Denormalized event title for convenience.
direction*	string	BullishBearishNeutral	Forecast direction.
probability*	number	0…100	Forecast probability, percent.
magnitude	string	—	Estimated move magnitude, e.g. "+3–5%".
time_horizon*	string	24h5 days30 days90 days180 days1 year	Forecast horizon.
published_date*	date-time	—	When the forecast was issued.
actual_outcome	string	—	What actually happened — filled in after the horizon elapses.
brier_score	number	0…1	Forecast-accuracy Brier score (lower is better).
accuracy_status	string	PendingCorrectIncorrectPartially Correct	Accountability status.

Changelog

v1.0.0Public release2026-07-28

› Initial public schema release for Event and Forecast resources.
› 18 event categories, four verification tiers, and the cascade-effects (Butterfly Path) model.
› Forecast accountability fields: brier_score, accuracy_status, actual_outcome.
› Stability contract: required and read-only fields are guaranteed; optional fields may evolve between minor versions. Breaking changes bump the major version and are announced 30 days in advance.

Machine-readable: each resource exposes an expandable JSON Schema block above. Pin to v1.0.0 in your client to lock the contract.

Sample Response

{
  "count": 2,
  "data": [
    {
      "id": "evt_8f3a...",
      "title": "OPEC+ announces surprise production cut",
      "category": "Energy",
      "geography": "Global",
      "severity": "High",
      "event_date": "2026-07-28T08:00:00Z",
      "forecast_direction": "Bearish",
      "forecast_probability": 72,
      "status": "Active"
    }
  ]
}

Already have a key? Manage your API key & view usage →

Informational only. Not investment advice. Investing involves risk of loss. · Privacy Policy · Terms of Service