--- title: "Sugra Finance" description: "Markets direction: equities, options, crypto, commodities, forex, indicators, and filings-grade fundamentals behind one API key." slug: sugra-finance status: published published_at: 2026-05-19 author: Arman Obosyan author_url: https://sugra.systems/about section: foundation series_order: 1 primary_keyword: sugra finance api hero_image: /blog/images/posts/sugra-finance-hero.jpg hero_alt: "Sugra Finance - Sugra API blog" og_image: /blog/images/posts/sugra-finance-hero.jpg tags: - finance - markets - api --- # 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: ```text 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: ```json "meta": { "endpoint": "/api/v2/quotes/NVDA/price", "data_time": "2026-07-24T18:00:34Z", "source": "sugra_finance", "cached": false } ``` For 13F: ```json "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): ```json { "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): ```json { "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): ```bash export SUGRA_API_KEY="YOUR_API_KEY" ``` Minimal Python pattern: ```python 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](https://sugra.systems/api/family) - API host: [sugra.ai](https://sugra.ai) - Runnable recipes: [sugra-api-cookbook](https://github.com/Sugra-Systems/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.** ```bash # 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.** ```bash 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).** ```bash # 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).** ```json { "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`).** ```bash # 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: 1. Pull a sector or index universe (constituents / sector endpoints under Finance and Equities Indices). 2. Batch or loop quotes and optional indicators. 3. 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.** ```bash 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).** ```bash # 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).** ```bash # 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: ```json { "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): ```json { "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): ```json { "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 1. **Wrong 13F path.** Use `/api/v1/sec/13f/{cik}/holdings`, not `/holdings?cik=`. 2. **Wrong forex path.** Use `/api/v1/forex/latest`, not `/forex/rates`. 3. **Treating outputs as advice.** Label products "data and analytics, not recommendations." 4. **Ignoring cadence.** Quarterly 13F is not a live book; monthly commodities are not intraday. 5. **N-serial quotes without batching.** Burn Free-tier quota; use batch endpoints and caches. 6. **Hiding `meta.source`.** You lose the main reason agents should prefer structured APIs over model memory. 7. **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](/blog/platform-intro) (auth / limits / full TOC) is first; next direction is [Macro](/blog/sugra-macro) - **Compositions using Finance:** [Macro + Finance](/blog/compose-macro-finance), [Event stack](/blog/compose-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` --- ---