Finance & Market Data
Build reliable real-time stock data workflows for Codex with verified timestamps, market coverage, freshness, and failure handling.
Published: April 18, 2026 · By the QVeris Team
Use this guide to choose an integration path, define freshness correctly, implement the tool contract, and validate what Codex says when market conditions are messy.
The right path depends on where the conversation lives and how much control the workflow needs.
Best when Codex should discover and call structured market capabilities directly. Configure an MCP server, keep credentials outside prompts and repositories, inspect the chosen tool, and allow only the read-only quote operations the task needs.
Read the QVeris MCP server setupBest when a repository needs a testable, versioned adapter. Give Codex one command that validates symbols, calls the provider, emits stable JSON, and returns non-zero exit codes for timeouts, limits, or ambiguous instruments.
Open the Codex-specific QVeris setupRun the official Codex command below with your own API key. It registers the read-only capability layer in Codex without putting the key in the repository. The Codex CLI and IDE extension store this MCP entry in your local Codex configuration.
codex mcp add qveris --env QVERIS_API_KEY=your-api-key-here -- npx -y @qverisai/mcp
codex mcp listAfter QVeris appears as enabled, ask Codex to discover a capability before executing anything. Inspect the selected capability to confirm its provider, input schema, freshness, entitlement, and cost. Only then call it with parameters that match the inspected schema.
qveris discover "real-time stock quote with source and timestamp"
qveris inspect <tool-id>
qveris call <tool-id> --params '<validated-json-from-the-inspected-schema>'Verification prompt: “Use QVeris to find a read-only current quote capability for AAPL. Inspect it first. Return the exchange, currency, market session, source, delay status, and provider timestamp. Do not place a trade.”
See the complete Codex configuration and troubleshooting steps
Adding real-time stock market data to Codex is not a direct model-to-exchange connection. A production design separates language reasoning from deterministic validation, provider access, and evidence formatting.
Codex identifies whether the user wants a current quote, a historical comparison, market status, or a broader research task. It should ask for clarification when a symbol, exchange, or time horizon is ambiguous.
A narrow schema constrains symbols, exchanges, fields, and permitted operations. This layer rejects malformed input, applies user and workspace policy, and keeps read-only retrieval separate from trading.
Server-side code owns credentials, provider selection, entitlement checks, retries, normalization, and caching. If providers use different names for sessions or timestamps, the adapter maps them into one stable response.
The final response combines the quote with its currency, as-of time, session, delay status, and source. The model may explain the result, but it must not silently replace missing fields or present stale data as current.
Let the model decide when a quote is needed; let application code decide whether and how the request is safe to execute. The returned JSON—not model memory—is the source of truth for the price.
A price without timing context can be confidently wrong. Require enough metadata to explain what the number represents.
| Field | Why it matters | Example shape |
|---|---|---|
| symbol, exchange | Disambiguates tickers across venues. | NASDAQ:AAPL |
| price, currency | Prevents an unlabeled number from being treated as USD. | number + ISO currency |
| as_of | Shows when the provider observed or published the value. | ISO 8601 timestamp |
| session | Separates regular, pre-market, after-hours, and closed states. | regular / pre / post / closed |
| delay, source | Makes licensing and freshness limits visible. | delay seconds + provider |
The best stock market API for Codex is the one whose coverage, entitlement, freshness, and response metadata match the questions your users ask. A cheap quote endpoint may be sufficient for casual lookup but unsuitable for alerts, compliance-sensitive research, or redistribution.
| Criterion | Questions to verify | Failure if ignored |
|---|---|---|
| Market coverage | Which exchanges, instruments, countries, and asset classes are included? | The same ticker resolves to the wrong venue or no result. |
| Freshness | Is the value real-time, delayed, indicative, snapshot, or previous close for this entitlement? | Codex labels an old value as a live stock price. |
| Session detail | Can the API distinguish regular, pre-market, after-hours, halted, and closed? | A post-market value is compared with a regular-session close without explanation. |
| Licensing | May values be displayed to end users, cached, logged, or redistributed? | A technically working integration violates display terms. |
| Operational fit | What are the rate limits, timeout behavior, status page, and support path? | Peak traffic becomes unexplained missing or repeated quotes. |
Do not copy a universal “real-time” label from a provider homepage. Verify the specific exchange, endpoint, account tier, and intended display use in the provider’s official documentation and agreement.
Start with quote lookup, daily change, session status, and a timestamp. Treat charts, news, filings, screening, and trading as separate capabilities with separate permissions.
Check exchange coverage, entitlement, delay, redistribution terms, uptime, rate limits, and whether timestamps and session status are returned. “Real-time” must match your plan and market.
Accept a symbol or query plus an optional exchange. Return a stable JSON object. Keep provider keys server-side and never ask the model to assemble secret-bearing URLs.
Require the answer to state the as-of time, currency, session, and source. If data is stale, missing, or ambiguous, the assistant should say so rather than infer a current price.
Test weekends, holidays, halts, pre-market and after-hours, invalid symbols, duplicate ticker names, provider timeouts, rate limits, and split-adjusted historical values.
Log request ID, selected capability, provider, latency, status, and data timestamp—without leaking keys. Cache only for a duration compatible with the promised freshness.
This illustrative tool definition is intentionally provider-neutral. Your application—not the model—owns authentication, symbol normalization, retries, entitlements, and the final provider request.
Separate factual market retrieval from recommendations, trading, suitability assessment, and regulated activities.
{
"type": "function",
"name": "get_stock_quote",
"description": "Return a current market quote with freshness metadata",
"parameters": {
"type": "object",
"properties": {
"symbol": { "type": "string" },
"exchange": { "type": "string" }
},
"required": ["symbol"],
"additionalProperties": false
}
}
// Server returns:
{
"symbol": "...",
"price": 0,
"currency": "...",
"session": "...",
"as_of": "...",
"delay_seconds": 0,
"source": "..."
}
A good tool call can still produce a misleading answer if the model hides timing and scope. Give the assistant a compact output policy that is easy to test.
Example Company (EXCH:XYZ) is shown at 123.45 USD. The quote is marked regular session and was observed at 14:32:08 America/New_York. Source: Example Provider. Data status: real-time under the configured entitlement.
This is a formatting example, not an observed market quote. Production values must come from the tool result.
“For any request containing current, live, now, today, latest, pre-market, or after-hours price intent, call the quote tool before answering. Never recall a price from conversation history. If the result lacks an as-of timestamp, source, or session status, state that the quote cannot be verified as current.”
QVeris can help an agent discover market-data capabilities, inspect their inputs and outputs, and call the selected tool through a unified interface. This is useful when one workflow may later expand from quotes to filings, news, indicators, or alerts.
Use the live stock page to inspect quote freshness, charts, and market-session context.
Test a timestamped quote in PlaygroundFor code-first workflows, discover and inspect stock capabilities through the QVeris CLI or documentation.
Read the QVeris CLI guideSee how a market-data MCP entry point can cover quotes, movers, news, macro signals, and historical data.
Read the market data MCP guideA reliable Codex stock-data workflow makes these trade-offs explicit. Optimizing only for the fastest model response can increase quote staleness, provider cost, or operational risk.
Set cache policy by user intent and feed rights. A repeated educational lookup may tolerate a short cache; a market alert may require a new request. Return both the provider timestamp and any cache age so the assistant can describe the result honestly.
Use a bounded timeout and at most a controlled retry for transient failures. If a fallback provider has different coverage or delay, expose that substitution in the response instead of making the sources appear equivalent.
Prevent one prompt from expanding into hundreds of symbols. Cap list size, separate batch endpoints, deduplicate repeated symbols, and monitor provider calls per conversation. Ask for confirmation before expensive scans.
Store market-data keys in a server-side secret manager or managed connection. Scope credentials to read-only data where possible, rotate them, redact request headers from logs, and never return provider secrets to Codex.
A quote symbol is often low sensitivity, but watchlists, positions, account identifiers, and strategy prompts may not be. Minimize what is sent to the provider and document what external service receives.
Keep the quote tool read-only. If trading is ever added, use a separate tool, stronger authentication, explicit confirmation, idempotency, position and risk checks, and a complete audit trail.
| Symptom | Likely cause | What to fix |
|---|---|---|
| Codex gives a price without calling the tool | Tool description or assistant instructions do not identify freshness intent. | Add trigger terms and require a tool call for current-price questions; test paraphrases, not only one prompt. |
| The quote is correct but labeled “live” incorrectly | The adapter discarded provider delay or entitlement metadata. | Preserve data status and make the model repeat it; never infer real-time status from a recent timestamp alone. |
| A symbol returns the wrong company | Ticker resolution ignored exchange or country context. | Return candidate matches and ask the user to disambiguate before the quote call. |
| Prices change between two turns with no explanation | One answer came from cache or a different session/feed. | Display as-of time, cache age, session, and source on every answer. |
| The assistant retries until rate-limited | The tool loop lacks terminal error states and retry limits. | Classify errors as retryable or terminal, cap attempts, and return a user-readable failure reason. |
A useful evaluation set measures more than whether an API returned HTTP 200. Test tool selection, argument accuracy, evidence preservation, language quality, and safe failure behavior.
Do not publish the integration until every supported market has an explicit freshness definition, every quote includes traceable metadata, and every tested provider failure ends with an honest user-facing response. Re-run the set whenever the provider, schema, tool description, model, or caching policy changes.
Do not assume it does. For a repeatable application, connect a trusted market-data source and retrieve the quote at answer time. Display the source, market session, and timestamp.
Yes. Connect an approved MCP server or give Codex a narrow CLI that calls the provider and returns structured JSON. Keep credentials out of the repository, make the quote path read-only, and test failure behavior before relying on it.
The exact meaning depends on the exchange, feed, and entitlement. A provider may return a current value for one venue but delayed or indicative data for another. Preserve the provider timestamp and delay metadata instead of applying one label globally.
Usually no. Keep read-only market retrieval separate from order entry. Trading requires stronger identity, authorization, confirmations, risk controls, audit trails, and regulatory review.
Return the latest available value with its timestamp and session status, and state whether it is the previous close, an after-hours quote, or another provider-defined value.
OpenAI product behavior and market-data entitlements can change. Check the current official documentation before publishing or modifying a production integration.
Start with one symbol, verify its source and freshness, and inspect the structured result before adding news, filings, indicators, or alerts.
A verified profile link does not guarantee entitlement, field availability, price or current execution success; inspect the current contract before calling.