Market Data API v1

A normalized, permission-aware API for market prices, SentimenTrader indicators, paired series, snapshots, recent bulk values, intraday history, and account-owned custom indicators.

Base URL

st-tools.sentimentrader.com/data/v1

Protocol

HTTPS · GET only

Authentication

Basic · Cookie · optional OIDC Bearer

Format

JSON envelope

Endpoint directory

Authentication and authorization

HTTP calls use Basic Auth, a valid session cookie, or an OIDC Bearer access token when OAuth is enabled. Access is layered: an authenticated local account, the data_api app gate (including legacy REST Data API compatibility), then per-resource entitlement or custom-indicator ownership.

Response contract

Every successful endpoint returns one JSON object with three parts: data rows, descriptive meta, and a warnings list. Metadata is part of the contract — report it rather than recomputing it client-side.

{
  "data": [
    { "DT": "2026-09-10", "close": 55.2 }
  ],
  "meta": {
    "schema_version": "1.0",
    "source_per_series": { "optix_spx": "catalog-resolved MySQL table" },
    "fallback_used": false,
    "data_as_of": "2026-09-10",
    "retrieved_at": "2026-09-14T04:00:00Z",
    "timezone": "UTC",
    "calendar": "business-day",
    "frequency": "daily",
    "alignment": "none",
    "fill_policy": "none",
    "adjustment_policy": "not_applicable",
    "row_count": 1,
    "cell_count": 2,
    "truncated": false,
    "response_bytes": 412
  },
  "warnings": []
}

Pagination walkthrough

Collection endpoints — catalog, snapshots, recent bulk, intraday, and both custom-indicator endpoints — page with the same three-step exchange: request a page, pass meta.next_cursor back unchanged as cursor, and stop when it is null. Keep the filter parameters (query, group, kind, market_symbol) identical across the pages of one enumeration; limit may differ per page. Price, indicator, and pair history do not use cursors: omit limit for the complete series, or pass it to receive the most recent N rows with meta.truncated set.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/catalog?limit=2"

{
  "data": [ /* 2 catalog rows */ ],
  "meta": {
    "count": 31156,      // total entries matched
    "offset": 0,
    "truncated": true,
    "next_cursor": "eyJ2IjoxLCJzY29wZ…In0.x7Q"  // opaque, signed; display shortened
  }
}

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/catalog?limit=2&cursor=eyJ2IjoxLCJzY29wZ…In0.x7Q"

{
  "data": [ /* rows 3–4 */ ],
  "meta": {
    "count": 31156,
    "offset": 2,
    "truncated": true,
    "next_cursor": "eyJ2IjoxLCJzY29wZ…In0.k9W"  // a different value every page
  }
}

{
  "data": [ /* final rows */ ],
  "meta": {
    "count": 31156,
    "offset": 31154,
    "truncated": false,
    "next_cursor": null  // stop — no more pages
  }
}

import requests

s = requests.Session()
s.auth = ("[email protected]", "your-password")
params = {"limit": 50000}                 # no filters — the whole catalog in one page
records = []

while True:
    page = s.get(
        "https://st-tools.sentimentrader.com/data/v1/catalog",
        params=params,
    ).json()
    records.extend(page["data"])
    cursor = page["meta"].get("next_cursor")
    if not cursor:
        break
    params["cursor"] = cursor             # hand it back verbatim

print(len(records))                       # 31156 — every entitled entry, one call

A rejected continuation returns 422 with {"detail": "cursor is invalid; pass back the next_cursor value unmodified."} — restart the enumeration from the first page. Catalog and custom-indicator cursors freeze their result snapshot, so a page whose underlying data changed between requests is rejected rather than silently shifted; snapshot, recent-bulk, and intraday cursors bind only the query and the account, so ordinary value refreshes never invalidate a page.

Query budget

Date and identifier formats

Indicator catalog

Discover indicator identifiers before requesting history or pair data. Catalog rows are metadata; indicator (identical to url, kept for legacy callers) is the identifier used by every other endpoint.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/catalog?query=optix&limit=5"

{
  "data": [
    {
      "chart_name": "SPY Optix",
      "indicator": "etf_spy",
      "url": "etf_spy",
      "market_symbol": "SPX",
      "type": "etf",
      "sub_type": "optix",
      "table_name": "OPTIX",
      "updated": "2026-09-10"
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "query": "optix",
    "count": 1,
    "entitlement_tier": "full",
    "source_per_series": { "catalog": "users.url_map" },
    "truncated": false
    // + standard envelope fields: row_count, cell_count,
    // retrieved_at, next_cursor, response_bytes
  },
  "warnings": []
}

Price history

Complete OHLCV history for one tradable symbol, daily by default. The whole available range is returned unless you pass limit, which returns the most recent N rows and reports meta.truncated.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/prices/SPY?start=2026-08-01&end=2026-09-10&limit=5"

{
  "data": [
    {
      "DT": "2026-09-10",
      "Open": 5450.12,
      "High": 5471.31,
      "Low": 5444.20,
      "Close": 5468.55,
      "Volume": 4213300000
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "symbol": "SPY",
    "source_per_series": { "SPY": "stocks.eod_stocks" },
    "fallback_used": false,
    "frequency": "daily",
    "calendar": "business-day",
    "adjustment_policy": "raw_close_excluding_split_rows",
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

Indicator series

One entitled SentimenTrader indicator over its full available range, returned with the OHLCV of the market the indicator belongs to. The indicator is forward-filled onto the daily grid and carried as {indicator}_close (and {indicator}_sentiment when requested), the same naming pair requests use. Pass limit for the most recent N rows.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/indicators/etf_spy/series?include_sentiment=true&limit=5"

{
  "data": [
    { "DT": "2026-09-10", "close": 55.2, "sentiment": 64 }
  ],
  "meta": {
    "schema_version": "1.0",
    "indicator": "etf_spy",
    "market_symbol": "SPY",
    "source_per_series": { "SPY": "stocks.eod_stocks", "etf_spy": "catalog-resolved MySQL table" },
    "frequency": "daily",
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

Paired series

Align one tradable symbol with up to 10 indicators for comparison, charting, or downstream analysis. Prices are aggregated with OHLCV semantics; each indicator becomes a {indicator}_close column. indicators is optional: omit it to receive the market's own OHLCV series. The full series is returned — pass limit only when you want the most recent N rows, and note that meta.truncated then reports true.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/pairs?symbol=SPX&indicators=etf_spy&frequency=daily&limit=5"

{
  "data": [
    {
      "DT": "2026-09-11",
      "Close": 5468.55,
      "Volume": 4213300000,
      "etf_spy_close": 55.2
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "symbol": "SPX",
    "indicators": ["etf_spy"],
    "source_per_series": {
      "SPX": "stocks.INDEXES_ST",
      "etf_spy": "catalog-resolved MySQL table"
    },
    "frequency": "daily",
    "alignment": "outer_join_then_resample",
    "fill_policy": "forward_fill_only",
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

Snapshots

Latest or dated point-in-time values. Prefer a snapshot over fetching history and taking the last row. Multi-record results are filtered to the caller's entitled indicators.

# Latest values (omit date), or a specific date:
curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/snapshots?indicators=etf_spy&date=2026-09-10"

{
  "data": [
    {
      "name": "SPY Optix",
      "indicator": "etf_spy",
      "last_close": 55.2,
      "update_date": "2026-09-11",
      "sentiment_value": 42,
      "market_symbol": "SPX"
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "date": null,
    "count": 1,
    "entitlement_filtered": true,
    "source_per_series": { "snapshot": "users.url_map" },
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

Recent bulk data

Tall-row bulk reads over the SPX trading calendar: every observation of every entitled indicator for the last N trading days. Use this instead of looping per-indicator history calls.

# Last 5 trading days for all entitled indicators:
curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/recent?trading_days=5&limit=1000"

{
  "data": [
    {
      "DT": "2026-09-11",
      "indicator": "etf_spy",
      "close": 55.2,
      "sentiment": 42
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "trading_days": 5,
    "resolved_as_of_date": "2026-09-11",
    "indicator_count": 312,
    "offset": 0,
    "truncated": false,
    "next_cursor": null
    // + standard envelope fields
  },
  "warnings": []
}

Intraday history

A separate, higher-volume capability. Use it only when intraday resolution is material; daily price or indicator history answers most questions with less data.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/intraday/SPX?start=2026-09-11T09:30:00&end=2026-09-11T16:00:00&limit=13"

{
  "data": [
    {
      "DT": "2026-09-11T10:00:00",
      "close": 5468.55,
      "market_symbol": "SPX"
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "symbol": "SPX",
    "source_per_series": { "SPX": "stocks.intraday" },
    "frequency": "intraday",
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

Custom indicators

Indicators created in the SentimenTrader web application, scoped to the authenticated account. Discover them with the list endpoint before requesting data; ownership is enforced by the server.

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/custom-indicators"

{
  "data": [
    {
      "name": "XLE Crude ROC1 Spread",
      "url": "sy9192-sy9218-1roc_1roc_1-0-0-sh0_c|sh0_c",
      "timeframe": "daily",
      "calculate": "spread",
      "create_date": "2026-07-14T12:12:19Z"
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "source_per_series": { "custom_catalog": "custom-indicator-service" },
    "count": 1,
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

curl -u "[email protected]:your-password" \
  "https://st-tools.sentimentrader.com/data/v1/custom-indicators/sy9192-sy9218-1roc_1roc_1-0-0-sh0_c|sh0_c/series?limit=5"

{
  "data": [
    {
      "DT": "2026-09-10",
      "close": -2.6607,
      "symbol": "XLE Crude ROC1 Spread"
    }
  ],
  "meta": {
    "schema_version": "1.0",
    "url": "sy9192-sy9218-1roc_1roc_1-0-0-sh0_c|sh0_c",
    "is_sample": false,
    "source_per_series": { "...": "custom-indicator-service" },
    "truncated": false
    // + standard envelope fields
  },
  "warnings": []
}

MCP tools

The mounted MCP endpoint exposes intent-oriented workflows over the same application service. MCP and Tool API share one tool_api master permission that can be explicitly granted or revoked. While TOOL_API_SUBSCRIPTION_ENFORCE=false, all legacy Data API subscribers—including Light Data and RGNCM—retain their old MCP access. Once Recurly synchronization and production plan codes are confirmed, enabling the switch makes Light Data and RGNCM REST-Data-API-only unless explicitly granted. Market Data tools additionally enforce the existing Data API app gate and indicator entitlements. Its seven canonical tools aggregate related reads where useful, preserve the normalized envelope, and attribute every call to the authenticated user.

Deprecated aliases

Three aliases remain registered for one compatibility cycle. New clients should use get_market_history, which takes mode plus that mode's parameters directly.

Optional Data API Dashboard

Open it in one line: tell the connected agent Open my SentimenTrader Data API Dashboard. MCP Apps hosts render the read-only dashboard inline and need nothing installed. The former phrase Open the SentimenTrader Indicator Workbench remains supported for compatibility. Open the Data API Dashboard guide for the full description and the optional standalone build.

Subscribers can browse their permitted indicators in the optional, read-only My Data API Dashboard. The in-chat view reuses the mounted MCP connection; the standalone build runs only on 127.0.0.1. Either way the catalog and readings use the same signed-in account, tool permission, and indicator entitlements as search_market_data. It is not a website-favorites list and does not show account-owned custom indicators.

Standalone local build: if it is already running on its default port and http://127.0.0.1:4174/_health identifies it, open the local Data API Dashboard directly. Otherwise ask the connected agent to Open my SentimenTrader Data API Dashboard; it calls get_indicator_workbench and follows the verified setup guide. Opening it is optional.

In the standalone build, when no installed dashboard is available, that explicit request automatically runs the fixed official bootstrap launcher. It automatically downloads the runtime bundle and its checksum, verifies the checksum before extraction, rejects unsafe archive entries, installs it into a dedicated private location, starts it on 127.0.0.1:4174 (another free loopback port when 4174 is busy), and returns its actual dashboard link—without another confirmation. The page asks you to sign in on the first visit. Automatic startup always uses browser OAuth + PKCE and remembers only its rotating OAuth refresh session in the operating-system credential store; a manually started bridge can use a readable Basic MCP configuration. Do not put credentials in a browser, command, project file, or chat.

Errors, access, and limits

Domain errors carry a stable status code and error code. Permission denials and backend failures are distinct: a user without entitlement sees 403, one whose entitlement cannot be read sees 502, and an unavailable app-access policy backend fails closed with 503.

MCP tools return every failure as a result with isError: true and the body {"error": {"code", "status", "message", "details"}}, so a client can branch on the flag and on the code. Rejected arguments report invalid_parameters with error.details.fields naming the offending field, its constraint, and the value received; an unsupported parameter name is reported rather than ignored. Pydantic-internal text (generated model names, error-type tags, documentation links) is never returned.

REST endpoints render the same failures as a plain {"detail": "<message>"} body with the status from the table above; the structured error envelope is the MCP form. The pagination walkthrough shows the rejected-cursor case and its recovery.

Trial access

Trial accounts receive the most recent 90 observations only, on every series endpoint. The response reports truncated_to_trial_window in meta and adds a warning so callers can state the limitation instead of treating the tail as full history.

Request volume

Reuse catalog pages within one task, and prefer a pair request, recent-bulk request, or snapshot over many repeated single-series calls. Pair and ordinary history series come back in full when limit is omitted; an explicit tail length is checked against the response budgets. Continue catalog, snapshot, recent-bulk, intraday, and custom-data pages only with the returned opaque meta.next_cursor; a date range is optional rather than a pagination mechanism.

Budgets

The query budget table above lists every request-level bound, and the failure semantics are the same for all of them: a violated bound fails the call with invalid_parameters rather than returning a partial series, while an applied default page sets meta.truncated instead of cutting the data off silently.