Developer API

REST API

Everything cvforge apps consume is a plain HTTPS + JSON API you can call from any language, notebook, spreadsheet, or cron job. Base URL:

https://tap.convexvalue.com/api/data

Options-pricing boundary: current option valuation is exposed only as fair_market_value, a proprietary estimate. The API does not provide option bid/ask quotes, quote sizes, midpoint, NBBO, or last-trade data. Do not treat FMV as an executable price.

Authentication

Every request needs a data API key (cv_live_…) as a Bearer token:

curl

curl -H "Authorization: Bearer cv_live_your_key_here" \
  "https://tap.convexvalue.com/api/data/chains/SPY?params=strike_price,implied_volatility,delta"

Personal API keys are a Go and Research plan feature: create and revoke them on your account page. The full key is shown once at creation — store it safely.
Inside the desktop app you never handle a key: cvforge provisions one automatically and injects it server-side via a local proxy, so keys never enter the pages you build.
Keys can be named and revoked independently; usage and rate limits are counted per user, so multiple keys share one quota.

Endpoints

Method	Path	Access	Description
POST	`/chains`	all plans	Option chain for one underlying (JSON body: symbol, params[])
GET	`/chains/{symbol}?params=a,b,c`	all plans	Same, CDN-friendly GET form
POST	`/screen`	all plans	Cross-market screener over every contract
POST	`/query`	all plans	Read-only SQL over the options snapshot
GET	`/mas/v2/aggs/ticker/{t}/range/{m}/{ts}/{from}/{to}`	Research	Historical OHLC bars (Massive mirror)
POST	`/mas/aggs`	Research	Same, JSON body
GET	`/mas/v1/open-close/{ticker}/{date}`	Research	Daily open/close for one contract
POST	`/mas/open-close`	Research	Same, JSON body
GET/POST	`/fmp/stable/{endpoint}`	all plans	157 FMP endpoints (fundamentals, filings, news, …)
POST	`/mcp`	all plans	MCP server (JSON-RPC 2.0) for coding agents
GET	`/ai/models`	all plans	Curated model catalog for the AI gateway
GET	`/ai/balance`	all plans	Your prepaid AI-credit balance (micro-USD)
POST	`/ai/v1/chat/completions`	AI credits	OpenAI-compatible chat completions, streaming SSE

The /ai routes are not plan-gated: they’re metered by prepaid AI credits instead, and /ai/v1/chat/completions is OpenAI-compatible — point any OpenAI SDK at https://tap.convexvalue.com/api/data/ai/v1 with your cv_live_ key.

Errors

Errors return a JSON body of the form { "error": "message" } with these status codes:

Status	Meaning
`400`	Invalid request — unknown field, bad SQL, malformed body. The error message says what to fix.
`401`	Missing, malformed, or revoked API key.
`402`	Your plan lacks the feature for this route (e.g. historical bars without Research), or your AI-credit balance is empty on /ai routes. Upgrade or top up at the account portal.
`404`	Not found — e.g. an unknown contract/date on historical endpoints.
`429`	Hourly request limit reached. The counter is per user (extra keys don’t add quota) and resets on the hour.
`502`	An upstream data provider returned an error.
`503`	A data source isn’t configured or the snapshot is unavailable.

Feature gates are checked before the rate limiter, so a 402 never consumes quota.

Rate limits

Each plan sets an hourly request limit across all data endpoints combined: Free 20/hr · Go 1,000/hr · Research 50,000/hr. The window resets on the hour. Details on plans & limits.

Caching

Chain responses carry x-cv-cache: hit|miss; the server keeps a short in-process cache that clears when fresh snapshot data lands (about once a minute).
GET forms (/chains/{symbol}, /mas/*) set Cache-Control: private, max-age=15 — safe for browsers, never cached at the CDN edge.

Get example prompts & new data guides

Occasional emails with prompts worth trying and what’s new in the data.