Sugra Finance: market signals and analytics behind one API key

Series: Sugra product directions (1 of 7)
Audience: developers integrating the Sugra API over HTTP
Live samples verified: 2026-07-24 against https://sugra.ai
Auth: x-api-key header on every data call

This article stands alone. You do not need the other direction articles to use Sugra Finance. Later articles in the series cover Macro, Entity, NetAtlas, News, Earth, and Research the same way: what the direction is, what responses are good for, and detailed single-direction use cases with real request paths.

Nothing in this direction is investment advice. Sugra is not an execution venue, a broker, or a ratings agency.

Essence

Every market signal behind one key - and the analytics we compute ourselves.

Sugra Finance is the markets facet of the Sugra API. One key unlocks:

Listed equities and related market surfaces (quotes, history, options, calendars)
Platform-computed technical indicators (same symbol, same key)
Regulatory and institutional positioning (SEC 13F, short-side and related regulatory feeds)
Fundamentals rebuilt from primary SEC filings with provenance
Adjacent market categories under Sugra-branded wrappers: crypto, forex, commodities, and (where enabled) predictions

Commercial market feed fields ship under meta.source values such as sugra_finance, sugra_crypto, and sugra_forex. Sovereign and academic upstreams are named openly (for example SEC EDGAR, FINRA, CFTC, Fama-French). You always see who answered in meta.source.

What this direction is not

Not this	Why it matters
Investment advice or a recommendation engine	You get data and platform analytics; decisions stay with you
An order router or brokerage	No trade execution, no account balances
A claim that Sugra originates exchange prices	Market prints come from the Sugra Finance feed wrapper; regulatory series come from named filings
A full-text news product	Headlines and global media analytics live in Sugra News
Official macro statistics only	CPI, policy rates, and sovereign series live in Sugra Macro

Open positive: what Finance does (quotes, indicators, filings, positioning). Close anti-positioning: what it refuses to pretend to be.

Capability map

Counts below follow the portal catalog (as of 2026-07-18). Treat them as order-of-magnitude; the live OpenAPI catalog is the authority for exact totals.

API Reference category	Endpoints (approx.)	What you get
Finance	121	`/api/v2` quotes, OHLCV history, options, screeners, market calendars, futures curves; short interest and market-structure series; factor and identifier helpers
Technical Indicators	113	Moving averages, momentum, volatility, volume, stats, patterns - computed on the platform from the market feed
Hedge Fund Intelligence	67	SEC 13F portfolios and reverse holders, Form ADV, CFTC COT, disclosed shorts, selected central-bank securities holdings aggregates
Fundamentals	34	Income, balance, cash flow, ratios from SEC EDGAR XBRL with filing provenance; Japan EDINET surface
Equities Indices	13	S&P 500 constituents, event studies / PEAD, quality and valuation models, sector percentiles
Funds and ETFs	12	ETF universe, holdings from filings, sector weights, flows
SEC EDGAR	11	Daily index, Form 4/5 insiders, 8-K, 13D/G, 10-K extraction
Options	7	Snapshots, IV surface, put-call history, implied move, unusual volume
Insiders	2	Transactions and sentiment from Forms 4/5
Earnings	1	Earnings calendar
Crypto / Forex / Commodities	separate categories	Sugra Crypto, Sugra Forex, and commodity series (for example World Bank Pink Sheet gold)

Shared contract for almost all of these surfaces:

Authorization style:  header  x-api-key: YOUR_API_KEY
Base host:            https://sugra.ai
Envelope:             { "data": ..., "meta": { "endpoint", "data_time", "source", ... } }

Rate limits are plan volume only (Free / Dev / Pro). Headers such as X-RateLimit-Remaining apply to the whole key across directions.

Why the response shape is useful

1. Standard envelope and provenance

Every successful call returns data plus meta. For a live equity quote:

"meta": {
  "endpoint": "/api/v2/quotes/NVDA/price",
  "data_time": "2026-07-24T18:00:34Z",
  "source": "sugra_finance",
  "cached": false
}

For 13F:

"meta": {
  "endpoint": "/api/v1/sec/13f/0001067983/holdings",
  "source": "sec_13f"
}

Agents and pipelines can cite meta.source and meta.data_time instead of inventing numbers. That is the core strength for AI agent builders and research desks.

2. Rich quote payload (not a bare last price)

A single GET /api/v2/quotes/{symbol}/price returns price, day range, volume, market state, exchange, and market cap in one object. Live sample (truncated, 2026-07-24):

{
  "data": {
    "symbol": "NVDA",
    "shortName": "NVIDIA Corporation",
    "exchange": "NMS",
    "marketState": "REGULAR",
    "regularMarketPrice": 209.81,
    "regularMarketChangePercent": 0.005029714,
    "regularMarketVolume": 62249316,
    "regularMarketDayHigh": 211.9099,
    "regularMarketDayLow": 205.67,
    "marketCap": 5081807716352
  },
  "meta": {
    "endpoint": "/api/v2/quotes/NVDA/price",
    "source": "sugra_finance"
  }
}

3. Platform-computed indicators with a stable parameter grammar

All indicator routes share symbol, time_period, interval, range, outputsize. Multi-period RSI (or other oscillators) can use comma-separated time_period values. Live RSI for ASML (truncated):

{
  "data": {
    "symbol": "ASML",
    "indicator": "rsi",
    "interval": "1d",
    "series_by_period": {
      "14": [
        { "date": "2026-07-24T13:30:00Z", "value": 49.62 },
        { "date": "2026-07-23T13:30:00Z", "value": 52.05 }
      ]
    }
  },
  "meta": { "source": "sugra_finance" }
}

You do not re-download OHLCV and reimplement RSI unless you want to. Sugra already computed the series.

4. Regulatory positioning with filing metadata

13F holdings return manager name, period of report, position count, total value, and per-line CUSIP, shares, voting authority, and accession. That is enough to build ownership dashboards without scraping SEC bulk files yourself.

5. Cross-asset market wrappers under the same key

Crypto, forex, and commodities use the same auth and envelope pattern with distinct meta.source labels (sugra_crypto, sugra_forex, worldbank_commodities, and so on). One integration surface for multi-asset agents.

How to call it (developer path)

Set a key (never commit it):

export SUGRA_API_KEY="YOUR_API_KEY"

Minimal Python pattern:

import os
import requests

BASE = "https://sugra.ai"
H = {"x-api-key": os.environ["SUGRA_API_KEY"]}

def get(path, **params):
    r = requests.get(f"{BASE}{path}", headers=H, params=params, timeout=30)
    r.raise_for_status()
    body = r.json()
    return body["data"], body.get("meta", {})

Public docs entry points:

Family overview: sugra.systems/api/family
API host: sugra.ai
Runnable recipes: sugra-api-cookbook

Agent UI users can also attach the hosted MCP at https://app.sugra.ai/mcp. This article stays on HTTP for application code.

Use case 1: Ticker snapshot desk

Goal. Answer “what is this name right now?” with price, session context, and recent bars.

When to use. Dashboards, chat agents, portfolio widgets, pre-trade context screens (still not advice).

Calls.

# 1) Latest quote
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/NVDA/price"

# 2) Recent daily history
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/AAPL/historical?range=5d&interval=1d"

What you get. Quote fields above; historical OHLCV bars with timestamps. Join client-side by symbol.

Strength. One or two HTTP calls replace a multi-vendor quote stack for a basic desk view.

Pitfalls. marketState matters (regular vs closed). Do not treat a single print as a signal without your own rules.

Use case 2: Momentum and technical check

Goal. Overlay momentum (RSI or similar) on a symbol without local indicator code.

When to use. Screening bots, research notebooks, agent tools that answer “is RSI stretched?”

Calls.

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/indicators/rsi?symbol=ASML&time_period=14&interval=1d&outputsize=30"

Extend with siblings such as moving averages and volatility bands under /api/v1/indicators/* (same parameter shape).

What you get. Time-ordered series in series_by_period, ready to chart or threshold.

Strength. Consistent grammar across 100+ indicators; multi-period in one request.

Pitfalls. Indicators are derived from the market feed. Document lookback and interval in your product UI so users know what they plot.

Use case 3: Institutional footprint (13F)

Goal. Reconstruct what a large manager reported last quarter, or who holds a CUSIP.

When to use. Ownership research, competitive analysis, “who owns this?” tooling. Lag is quarterly by design (SEC filing calendar).

Calls (verified live paths).

# Full portfolio for one manager (CIK path segment, not a query string)
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/sec/13f/0001067983/holdings"

# Top filers index
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/sec/13f/filers?limit=50"

# Reverse: holders of one CUSIP (9-character canonical CUSIP)
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/sec/13f/holders-of/037833100"

What you get (live sample, Berkshire Hathaway CIK 0001067983, truncated).

{
  "data": {
    "cik": "0001067983",
    "manager_name": "Berkshire Hathaway Inc",
    "period_of_report": "31-MAR-2026",
    "position_count": 90,
    "total_value_usd_thousands": 263095703570,
    "positions": [
      {
        "issuer": "APPLE INC",
        "title": "COM",
        "cusip": "037833100",
        "value_usd_thousands": 15618994925,
        "shares": 61542988,
        "shares_type": "SH",
        "accession": "0001193125-26-226661"
      }
    ]
  },
  "meta": { "source": "sec_13f" }
}

Full rows also include voting authority, investment discretion, and related manager sequence fields. Aggregate carefully when one issuer appears on multiple lines.

Strength. Filing-native structure and accession IDs for audit trails.

Pitfalls.

Correct path is /api/v1/sec/13f/{cik}/holdings, not /holdings?cik=....
Multiple lines can share one issuer (different reporting rows / manager sequences). Aggregate carefully.
13F is a lagging snapshot, not a live book.

Use case 4: Post-earnings move study

Goal. For each recent fiscal quarter, pair EPS surprise with the stock’s subsequent path.

When to use. Event-study research, agent explanations of “how did it trade after reports?”

Calls (pattern from cookbook recipe 15_markets_post_earnings_moves.py).

# Earnings / EPS history
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/AAPL/earnings-history?limit=8"

# Daily closes spanning those quarters
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/AAPL/historical?range=2y&interval=1d"

Join client-side: for each quarter timestamp, measure close-to-close return over a window (for example 30 calendar days). For the next announcement date, prefer the calendar endpoint on the same quotes surface.

Strength. Two HTTP calls replace a multi-file earnings+price join.

Pitfalls. History anchors on fiscal quarter timestamps, not always the exact press-release clock. Document that in any user-facing study.

Use case 5: Sector universe and relative strength

Goal. Build a sector leaderboard or universe list for further ranking.

When to use. Weekly sector dashboards, rotation research scaffolds (still client-side logic).

Calls (cookbook recipes 02_markets_sector_momentum.py, 16_markets_sector_universe.py).

Typical flow:

Pull a sector or index universe (constituents / sector endpoints under Finance and Equities Indices).
Batch or loop quotes and optional indicators.
Rank by your metric (return, RSI, relative strength).

Strength. One key covers universe metadata and market prints.

Pitfalls. Batch carefully against daily quota. Prefer batch quote endpoints where available (/api/v2/market/batch-quotes) over naive N serial calls.

Use case 6: Fundamentals with filing provenance

Goal. Ratios and statements grounded in SEC XBRL, not opaque vendor fundamentals.

When to use. Credit-style checks, research agents that must cite a filing.

Calls.

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fundamentals/MSFT/ratios"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fundamentals/MSFT/income"

What you get. Margins, ROE, leverage, and related ratios plus statement lines; provenance blocks point at accession and filing identity where the surface exposes them.

Strength. source-level honesty (SEC EDGAR XBRL) and structured ratios ready for tables.

Pitfalls. Filing lag and restatements. Foreign filers may need usd=true (when supported) for currency normalization.

Use case 7: Options and insider confluence (Finance-only)

Goal. Combine unusual options activity with Form 4/5 insider flow for a single name - still entirely inside Finance.

When to use. Event monitoring desks that want regulatory + options surfaces without leaving the direction.

Calls (illustrative surface names; confirm parameters in OpenAPI).

# Options snapshot / unusual volume family under /api/v1 or /api/v2 options routes
# Insider transactions under SEC / insiders routes for the same issuer or CIK

Strength. Same auth, same envelope, citable meta.source mix (sugra_finance vs sec_*).

Pitfalls. Some options universes depend on ingest state; handle 503 with backoff. Insider data is sparse and delayed by filing rules.

Use case 8: Multi-asset market board (crypto, forex, commodities)

Goal. One dashboard row for BTC, a USD cross, and a commodity series.

When to use. Multi-asset agents, treasury dashboards, research notebooks.

Calls (live-verified paths).

# Crypto
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/crypto/bitcoin/price"

# Forex (correct path: /latest, not /rates)
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/forex/latest?base=USD"

# Commodities (example: gold, World Bank Pink Sheet series)
curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/commodities/gold"

Live samples (truncated, 2026-07-24).

Bitcoin price surface:

{
  "data": {
    "id": "bitcoin",
    "symbol": "btc",
    "current_price": 64127,
    "price_change_percentage_24h": -1.5,
    "market_cap_rank": 1
  },
  "meta": { "source": "sugra_crypto" }
}

Forex latest (note: default base in the live sample was EUR when only base=USD behavior is exercised against cache - always read data.base and data.date from the response rather than assuming):

{
  "data": {
    "base": "EUR",
    "date": "2026-07-24",
    "rates": { "USD": 1.1377, "GBP": 0.85388, "JPY": 186.38 }
  },
  "meta": { "source": "sugra_forex", "cached": true }
}

Gold (monthly series, World Bank):

{
  "data": {
    "id": "gold",
    "title": "Gold ($/troy oz)",
    "source": "World Bank Pink Sheet",
    "data": [
      { "date": "2025-12", "value": 4309.23 },
      { "date": "2025-11", "value": 4087.19 }
    ]
  },
  "meta": { "source": "worldbank_commodities" }
}

Strength. Cross-asset coverage without a second vendor contract for basic board rows.

Pitfalls. Cadence differs (crypto prints vs monthly commodity sheets). Always surface meta.data_time and series frequency to users.

Response strengths summary

Strength	How to use it
`meta.source` + `meta.data_time`	Cite in agents and UI footers
Fat quote objects	Build desks without five follow-up calls
Indicator parameter grammar	Generic indicator client for 100+ endpoints
13F structure + accession	Ownership products with audit hooks
Fundamentals provenance	Filing-grounded analytics
Sugra wrappers for commercial market fields	Public-safe naming; keep Tier C vendor brands out of your UI
Same key as other directions	Expand later to Macro/News without re-auth design

Antipatterns

Wrong 13F path. Use /api/v1/sec/13f/{cik}/holdings, not /holdings?cik=.
Wrong forex path. Use /api/v1/forex/latest, not /forex/rates.
Treating outputs as advice. Label products “data and analytics, not recommendations.”
Ignoring cadence. Quarterly 13F is not a live book; monthly commodities are not intraday.
N-serial quotes without batching. Burn Free-tier quota; use batch endpoints and caches.
Hiding meta.source. You lose the main reason agents should prefer structured APIs over model memory.
Naming commercial feed vendors on public surfaces. Use Sugra Finance / Sugra Crypto / Sugra Forex wrappers in product copy.

Scenarios where Finance alone is enough

Equity research agent that must show price, RSI, and a SEC-grounded ratio pack
Institutional ownership explorer (13F filers, holders-of, consensus)
Earnings path study (earnings-history + historical)
Multi-asset status board (equities + crypto + FX + commodities)
Internal market widgets for ops tools that are not macro or compliance products

When you need official CPI or policy rates, open the Macro article next. When you need sanctions screening, open Entity. When you need headlines or global media volume, open News. Those are separate directions with their own response strengths - not missing Finance features.

Live verification notes (2026-07-24)

Surface	Result
`GET /api/v2/quotes/NVDA/price`	200
`GET /api/v1/indicators/rsi?symbol=ASML&...`	200
`GET /api/v2/quotes/AAPL/historical?range=5d`	200
`GET /api/v1/sec/13f/0001067983/holdings`	200
`GET /api/v1/sec/13f/filers?limit=3`	200
`GET /api/v1/crypto/bitcoin/price`	200
`GET /api/v1/forex/latest?base=USD`	200
`GET /api/v1/commodities/gold`	200

Samples in this article were truncated for readability; field sets match production envelopes.

Where to go next

Series order: Platform intro (auth / limits / full TOC) is first; next direction is Macro
Compositions using Finance: Macro + Finance, Event stack
Portal direction page: Sugra Finance on the API docs portal (module tables and flagship schemas)
Sources page: upstream list with tier and license for Finance
Cookbook: 01_quickstart.py, 02_markets_sector_momentum.py, 05_crypto_onchain.py, 10_forex_usd_rates.py, 11_commodities_prices.py, 15_markets_post_earnings_moves.py, 16_markets_sector_universe.py