Composition: event stack (Finance + News + Macro)

Series: compositions (4 of 4)
Prerequisites: Platform intro, Finance, News, Macro
Directions: Finance + News + Macro
Auth: x-api-key

Build a single-name or single-theme event pack: market print, media coverage, and official macro backdrop. Client-side join only. Not investment advice.

Goal

For symbol AAPL (example) and optional theme query:

Finance: quote, short history, earnings-history hook
News: curated search + GDELT articles / themes
Macro: 1-2 official series that frame the tape (CPI, policy rate, or curve spread)

Output one event_pack for agents or research UIs.

Call sequence

[Finance] GET /api/v2/quotes/{symbol}/price
[Finance] GET /api/v2/quotes/{symbol}/historical?range=1mo&interval=1d
[Finance] GET /api/v2/quotes/{symbol}/earnings-history?limit=4   (optional)
[News]    GET /api/v1/news/search?q={symbol_or_name}&limit=10
[News]    GET /api/v1/gdelt/articles?q={company_name}&max_records=10
[News]    GET /api/v1/gdelt/themes/trending?period=6h&limit=8    (optional)
[Macro]   GET /api/v1/fred/series/CPIAUCSL?limit=2&units=pc1
[Macro]   GET /api/v1/fred/series/T10Y2Y?limit=2
         -> event_pack

H="x-api-key: $SUGRA_API_KEY"
B=https://sugra.ai
SYM=AAPL

curl -H "$H" "$B/api/v2/quotes/$SYM/price"
curl -H "$H" "$B/api/v2/quotes/$SYM/historical?range=1mo&interval=1d"
curl -H "$H" "$B/api/v1/news/search?q=$SYM&limit=10"
curl -H "$H" "$B/api/v1/gdelt/articles?q=Apple&max_records=10"
curl -H "$H" "$B/api/v1/fred/series/CPIAUCSL?limit=2&units=pc1"
curl -H "$H" "$B/api/v1/fred/series/T10Y2Y?limit=2"

Budget: about 6-9 calls per pack. Cache Macro aggressively (monthly/daily series).

Client package (example)

event_pack = {
    "symbol": symbol,
    "market": {
        "price": quote["regularMarketPrice"],
        "change_pct": quote["regularMarketChangePercent"],
        "market_state": quote.get("marketState"),
        "history_bars": len(history_bars),
        "source": finance_meta.get("source"),
    },
    "media": {
        "curated": curated_items,
        "gdelt": gdelt_items,
        "gdelt_ok": gdelt_ok,
    },
    "macro_backdrop": {
        "cpi_yoy": cpi_yoy,
        "t10y2y": t10y2y,
        "sources": ["fred"],
    },
    "disclaimer": "Composition of market data, media signals, and official series. Not investment advice.",
}

Agents should cite each leg’s meta.source when answering.

Why three directions

Direction	Role in the pack
Finance	What the name is doing (price / path / earnings history)
News	What is being published and covered
Macro	Official backdrop (inflation, curve) without conflating it with the stock

Do not merge these into one fake “sentiment score” without documenting your formula.

Variants

Variant	Change
Earnings week	Add earnings-history + calendar; tighten news query to company name
Policy day	Emphasize Macro (FRED + BIS) + News policy themes; lighter Finance
Multi-name	Batch quotes; share one Macro backdrop across names

Failure modes

Failure	Handling
GDELT 503	Curated news only
Earnings history empty	Omit section
Macro lag	Show observation dates clearly
429	Partial pack with `truncated: true`

Building an event pack