API reference

Base URL: https://api.naven.network/v1/stocks.

All endpoints are read-only and accept either a valid, funded project API key (Authorization: Bearer naven_api_...) or x402 exact payment. With neither credential, HTTP 402 returns a PAYMENT-REQUIRED header and a payment challenge in the body. After settlement, PAYMENT-RESPONSE accompanies HTTP 200. Project-key requests deduct the same listed price from prepaid project credits after a successful response. Add credits in the Naven workspace. Keep project keys server-side. If you already have personal Naven Credits, transfer them into your project from the workspace before using a project key. Personal and project balances are separate.

The company data endpoints take a symbol as a URL path segment; /catalog takes no symbol. Lowercase symbols are accepted and normalized to uppercase.

The curl examples use NAVEN_API_KEY from your shell:

export NAVEN_API_KEY='naven_api_...'

Valid symbols start with a letter, contain at most 12 characters, and may contain letters, numbers, dots, or hyphens. Examples include AAPL, BRK.B, and RDS-A.

Response envelope

Successes return:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Every symbol-based data object includes:

Fields documented as nullable are JSON null when the provider does not supply a value.

Stock token catalog

GET /catalog lists verified stock tokens on Robinhood Chain (chain ID 4663). Each items entry has a symbol, name, token contract address, and iconUrl for a Naven-hosted logo. The response also includes source: "naven" and chainId: 4663. The list describes available stock tokens; a trading application should still check its execution venue before placing an order. Logo URLs may be unavailable for newly listed symbols until their images are published.

curl -H "Authorization: Bearer $NAVEN_API_KEY" https://api.naven.network/v1/stocks/catalog

Quote

GET /quote/{symbol}

curl -H "Authorization: Bearer $NAVEN_API_KEY" https://api.naven.network/v1/stocks/quote/NVDA

Company profile

GET /profile/{symbol}

curl -H "Authorization: Bearer $NAVEN_API_KEY" https://api.naven.network/v1/stocks/profile/MSFT

The response includes companyName, currency, exchange, industry, sector, country, ceo, website, description, imageUrl, marketCap, beta, priceRange, averageVolume, fullTimeEmployees, headquarters, ipoDate, and activelyTrading. Every field except source and symbol can be null.

activelyTrading describes the provider's symbol status. It is not an assurance that a particular broker, account, or jurisdiction can trade the security.

Price history

GET /history/{symbol}

from must not be after to. Daily requests support up to five years. Intraday requests support at most 30 calendar days inclusive; split longer ranges into non-overlapping requests. Each items entry contains date, open, high, low, close, volume, change, changePercent, and vwap. Market holidays and weekends do not produce rows.

curl -H "Authorization: Bearer $NAVEN_API_KEY" 'https://api.naven.network/v1/stocks/history/TSLA?from=2026-08-01&to=2026-09-01'

Intraday intervals currently cover symbols in the verified stock-token catalog, and regular US trading sessions only. 1m is not supported. Omit interval to preserve daily behavior. The response includes interval. Intraday responses also include timezone: "UTC", sessionTimezone: "America/New_York", and session: "regular". Intraday date values are ISO 8601 UTC bar-start timestamps, with daylight saving applied; daily date values remain YYYY-MM-DD trading dates. Intraday results are ordered newest first. change, changePercent, and vwap are null when unavailable.

curl -H "Authorization: Bearer $NAVEN_API_KEY" 'https://api.naven.network/v1/stocks/history/AAPL?interval=5m&from=2026-09-01&to=2026-09-30'

History pricing and authentication are the same for each interval. A temporarily unavailable interval returns 503; it is not an x402 payment challenge, and an unsuccessful response is not charged. Missing bars are not filled, and a current-session bar may still be forming. Clients running backtests must exclude unfinished bars and verify the requested interval and coverage. Data availability may vary by symbol and date.

Earnings

GET /earnings/{symbol}

Each event contains date, epsActual, epsEstimate, epsSurprisePercent, revenueActual, revenueEstimate, and revenueSurprisePercent. Future events normally have null actuals. Surprise percentages are calculated as (actual - estimate) / abs(estimate) * 100 and are null when no non-zero estimate exists.

curl -H "Authorization: Bearer $NAVEN_API_KEY" 'https://api.naven.network/v1/stocks/earnings/AMZN?limit=8'

Financial statements

GET /financials/{symbol}

Each item represents one reporting period:

• Identity: date, fiscalYear, fiscalPeriod, currency, filingDate, acceptedDate.
• income: revenue, grossProfit, operatingIncome, netIncome, dilutedEps.
• balanceSheet: cashAndShortTermInvestments, totalAssets, totalDebt, totalLiabilities, stockholdersEquity.
• cashFlow: operatingCashFlow, capitalExpenditure, freeCashFlow.

Naven aligns the three statements by reporting date or fiscal year and period. If an income statement is available before its matching balance sheet or cash flow, the unmatched values are null instead of being copied from another period.

curl -H "Authorization: Bearer $NAVEN_API_KEY" 'https://api.naven.network/v1/stocks/financials/META?period=annual&limit=5'

Company news

GET /news/{symbol}

Each item includes publishedAt, publisher, title, summary, site, imageUrl, and sourceUrl. publishedAt is normalized to an ISO 8601 UTC timestamp when the provider's timestamp can be parsed. sourceUrl points to the original article.

curl -H "Authorization: Bearer $NAVEN_API_KEY" 'https://api.naven.network/v1/stocks/news/GOOGL?limit=5'

Caching

Successful responses include a private Cache-Control policy. The suggested client cache windows are:

The source may update at a different cadence. A cache window describes when Naven may reuse a response; it is not a guarantee of when a company, exchange, publisher, or provider posts new data.

Errors

Errors use a non-zero code, a readable message, and data. Validation errors may include field details in data; an insufficient-credit response includes a top-up URL.

Empty items with HTTP 200 is valid for history, earnings, financials, or news. It means no rows were available for that symbol and query; it is not equivalent to a zero value.