MarketDataApp · Sep 17, 2026 · Sep 9, 2026 · Sep 17, 2026
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -1,4 +1,4 @@
-# Authentication
+# Authentication (Java SDK)
 
 The Market Data API uses a **Bearer Token** for authentication. The token is required for almost every request. Your token should have been e-mailed to you when you first signed up for an account. If you do not have a token or have lost your sign-up email, request a new token from the [Market Data Dashboard](https://www.marketdata.app/dashboard/).
 
@@ -41,7 +41,7 @@ setx MARKETDATA_TOKEN "your_api_token"
 
 The SDK automatically loads a `.env` file from your working directory at startup. Create a file named `.env` in your project root:
 
-```env title=".env"
+```ini title=".env"
 MARKETDATA_TOKEN=your_api_token
 ```
 
@@ -111,7 +111,7 @@ MarketDataClient("your_token_here", null, null, true).use { client ->
 ```
 
 > [!NOTE]
-> **Demo mode**
+> **[Demo mode]**
 >
 > If no token is found anywhere in the cascade, the SDK runs in **demo mode** — startup validation is skipped and you can call the free, public endpoints (such as `AAPL` quotes and `utilities().status()`).
 

diff --git a/docs/client.md b/docs/client.md
@@ -1,13 +1,13 @@
-# Client
+# Client (Java SDK)
 
 The `MarketDataClient` is the entry point to the SDK. It handles API requests, response parsing, rate-limit tracking, retries with exponential backoff, and logging. A single client gives you access to all five resources: stocks, options, funds, markets, and utilities.
 
 The client is immutable, thread-safe, and `AutoCloseable`. Create one per application (it holds a shared HTTP client and a 50-request concurrency pool) and close it when you're done.
 
-### Get Started Quickly
+## Get Started Quickly
 
 1. Review the [authentication documentation](./authentication.md) to learn how to set your API token.
-2. Create a [`MarketDataClient`](#MarketDataClient) and use it to make requests.
+2. Create a [`MarketDataClient`](#marketdataclient) and use it to make requests.
 3. Reach a resource through `client.stocks()`, `client.options()`, etc.
 4. Track your [rate limit](#rate-limits) to see how many API credits remain.
 5. Configure [Settings](./settings.md) to customize output format, date format, and other universal parameters.
@@ -82,7 +82,7 @@ MarketDataClient("your_token", null, null, false).use { client ->
 ```
 
 > [!NOTE]
-> **Fail-fast configuration**
+> **[Fail-fast configuration]**
 >
 > A misconfigured base URL or API version is rejected with an `IllegalArgumentException` **at construction**, not later on the first request. Tokens are never printed in full — the client's `toString()` redacts them (long tokens show only the last four characters; short ones are hidden entirely).
 
@@ -235,7 +235,7 @@ client.stocks().quoteAsync(StockQuoteRequest.of("AAPL"))
 ```
 
 > [!NOTE]
-> **`join()` vs `get()`**
+> **[`join()` vs `get()`]**
 >
 > To block on a future, prefer **`join()`** — it throws an unchecked `CompletionException`. `get()` does the same thing but throws the checked `ExecutionException` (plus `InterruptedException`), forcing a `try/catch`. Both wrap the underlying cause identically, so `join()` is usually the friendlier choice.
 

diff --git a/docs/funds/README.md b/docs/funds/README.md
@@ -1,9 +1,9 @@
-# Funds
+# Funds (Java SDK)
 
 The Java SDK from Market Data provides methods to streamline your use of the Funds endpoints. These methods provide a typed interface over the underlying HTTP requests and responses, with both sync and async variants.
 
 Reach the resource through `client.funds()`. For CSV output use `client.funds().asCsv()`.
 
 ## Funds Endpoints
 
-- [Candles](./candles.md)
+- [Fund Candles (Java SDK)](./candles.md) — Retrieve a mutual fund net asset value OHLC series with the Java SDK FundCandlesRequest, choosing the resolution that you need.
diff --git a/docs/funds/candles.md b/docs/funds/candles.md
@@ -1,4 +1,4 @@
-# Candles
+# Fund Candles (Java SDK)
 
 Retrieve a mutual fund's NAV (net asset value) OHLC series.
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,4 +1,4 @@
-# Installation
+# Installation (Java SDK)
 
 This guide will help you install the Market Data Java SDK and configure it for your project.
 

diff --git a/docs/markets/README.md b/docs/markets/README.md
@@ -1,9 +1,9 @@
-# Markets
+# Markets (Java SDK)
 
 The Java SDK from Market Data provides methods to streamline your use of the Markets endpoints. These methods provide a typed interface over the underlying HTTP requests and responses, with both sync and async variants.
 
 Reach the resource through `client.markets()`. For CSV output use `client.markets().asCsv()`.
 
 ## Markets Endpoints
 
-- [Status](./status.md)
+- [Market Status (Java SDK)](./status.md)
diff --git a/docs/markets/status.md b/docs/markets/status.md
@@ -1,4 +1,4 @@
-# Status
+# Market Status (Java SDK)
 
 Retrieve the exchange open/closed calendar — whether the market was (or will be) open on a given day.
 

diff --git a/docs/options/README.md b/docs/options/README.md
@@ -1,12 +1,12 @@
-# Options
+# Options (Java SDK)
 
 The Java SDK from Market Data provides methods to streamline your use of the Options endpoints. These methods provide a typed interface over the underlying HTTP requests and responses, with both sync and async variants.
 
 Reach the resource through `client.options()`. For CSV output use `client.options().asCsv()`.
 
 ## Options Endpoints
 
-- [Lookup](./lookup.md)
-- [Expirations](./expirations.md)
-- [Quotes](./quotes.md)
-- [Chain](./chain.md)
+- [Lookup (Java SDK)](./lookup.md) — Turn a human-readable option description into a well-formed OCC option symbol with the Java SDK and its OptionsLookupRequest type.
+- [Expirations (Java SDK)](./expirations.md) — List the available option expiration dates for an underlying symbol with the Java SDK and its OptionsExpirationsRequest type.
+- [Option Quotes (Java SDK)](./quotes.md) — Retrieve bid, ask, last and Greeks for option contracts by OCC symbol with the Java SDK quote and quotes methods, which fan out per symbol.
+- [Option Chain (Java SDK)](./chain.md)
diff --git a/docs/options/chain.md b/docs/options/chain.md
@@ -1,4 +1,4 @@
-# Chain
+# Option Chain (Java SDK)
 
 Retrieve a full option chain for an underlying, with a rich set of filters. The chain is where most option workflows start.
 

diff --git a/docs/options/expirations.md b/docs/options/expirations.md
@@ -1,4 +1,4 @@
-# Expirations
+# Expirations (Java SDK)
 
 List the available expiration dates for an underlying.
 

diff --git a/docs/options/lookup.md b/docs/options/lookup.md
@@ -1,4 +1,4 @@
-# Lookup
+# Lookup (Java SDK)
 
 Turn a human-readable option description into a well-formed OCC option symbol.
 
@@ -33,7 +33,7 @@ try (MarketDataClient client = new MarketDataClient()) {
   String occSymbol = client.options()
       .lookup(OptionsLookupRequest.of("AAPL 1/16/2026 $200 Call"))
       .values();
-  System.out.println("Resolved to: " + occSymbol); // AAPL260116C00200000
+  System.out.println("Resolved to: " + occSymbol); // AAPL271217C00300000
 }
 ```
 

diff --git a/docs/options/quotes.md b/docs/options/quotes.md
@@ -1,4 +1,4 @@
-# Quotes
+# Option Quotes (Java SDK)
 
 Retrieve quotes (bid, ask, last, greeks, etc.) for one or more option contracts by OCC symbol.
 
@@ -42,7 +42,7 @@ OptionsQuotesRequest.builder(String first, String... rest)
 
 #### Returns
 
-`OptionsQuotesResponse` wraps `List<OptionQuote>`. See [Chain](./chain.md#optionquote) for the full `OptionQuote` record (price fields plus greeks).
+`OptionsQuotesResponse` wraps `List<OptionQuote>`. See [Chain](./chain.md) for the full `OptionQuote` record (price fields plus greeks).
 
 ## Examples
 
@@ -58,13 +58,13 @@ try (MarketDataClient client = new MarketDataClient()) {
 
   // Single contract.
   OptionQuote q = client.options()
-      .quote(OptionsQuoteRequest.of("AAPL260116C00200000"))
+      .quote(OptionsQuoteRequest.of("AAPL271217C00300000"))
       .values().get(0);
   System.out.println("last=" + q.last() + " iv=" + q.iv() + " delta=" + q.delta());
 
   // Multiple contracts — one request each, keyed by symbol.
   var quotes = client.options().quotes(
-      OptionsQuotesRequest.of("AAPL260116C00200000", "AAPL260116C00210000"));
+      OptionsQuotesRequest.of("AAPL271217C00300000", "AAPL271217C00310000"));
   quotes.forEach((sym, resp) ->
       System.out.println(sym + " → " + resp.values().size() + " row(s)"));
 }
@@ -78,7 +78,7 @@ import com.marketdata.sdk.options.OptionsQuoteRequest
 
 MarketDataClient().use { client ->
     val q = client.options()
-        .quote(OptionsQuoteRequest.of("AAPL260116C00200000"))
+        .quote(OptionsQuoteRequest.of("AAPL271217C00300000"))
         .values()[0]
     println("last=${q.last()} iv=${q.iv()} delta=${q.delta()}")
 }

diff --git a/docs/settings.md b/docs/settings.md
@@ -1,4 +1,4 @@
-# Settings
+# Settings (Java SDK)
 
 The Java SDK lets you customize API requests through **universal parameters** — settings such as date format, data mode, column projection, and CSV shaping that apply across endpoints. These are configured per resource, and some can also be set globally through environment variables.
 

diff --git a/docs/stocks/README.md b/docs/stocks/README.md
@@ -1,13 +1,13 @@
-# Stocks
+# Stocks (Java SDK)
 
 The Java SDK from Market Data provides methods to streamline your use of the Stocks endpoints. These methods provide a typed interface over the underlying HTTP requests and responses, with both sync and async variants.
 
 Reach the resource through `client.stocks()`. For CSV output use `client.stocks().asCsv()`.
 
 ## Stocks Endpoints
 
-- [Candles](./candles.md)
-- [Quotes](./quotes.md)
-- [Prices](./prices.md)
-- [News](./news.md)
-- [Earnings](./earnings.md)
+- [Stock Candles (Java SDK)](./candles.md) — Retrieve historical open, high, low, close and volume candles for a stock with the Java SDK StockCandlesRequest and its resolution options.
+- [Stock Quotes (Java SDK)](./quotes.md) — Retrieve real-time bid, ask, mid, last and volume for one or more stock symbols with the Java SDK, in single or multi-symbol request form.
+- [Prices (Java SDK)](./prices.md) — Retrieve the latest mid price and change for one or more stock symbols with the Java SDK StockPricesRequest, a lighter payload than a quote.
+- [News (Java SDK)](./news.md) — Retrieve news articles for a stock symbol with the Java SDK, building the query with a StockNewsRequest object.
+- [Earnings (Java SDK)](./earnings.md)
diff --git a/docs/stocks/candles.md b/docs/stocks/candles.md
@@ -1,4 +1,4 @@
-# Candles
+# Stock Candles (Java SDK)
 
 Retrieve historical OHLCV (open/high/low/close/volume) candles for a stock symbol.
 

diff --git a/docs/stocks/earnings.md b/docs/stocks/earnings.md
@@ -1,4 +1,4 @@
-# Earnings
+# Earnings (Java SDK)
 
 Retrieve historical and upcoming earnings data (EPS actuals, estimates, surprises) for a stock symbol.
 

diff --git a/docs/stocks/news.md b/docs/stocks/news.md
@@ -1,4 +1,4 @@
-# News
+# News (Java SDK)
 
 Retrieve news articles for a stock symbol.
 

diff --git a/docs/stocks/prices.md b/docs/stocks/prices.md
@@ -1,4 +1,4 @@
-# Prices
+# Prices (Java SDK)
 
 Retrieve the latest price (mid, change) for one or more stock symbols — a lighter payload than a full quote.
 

diff --git a/docs/stocks/quotes.md b/docs/stocks/quotes.md
@@ -1,4 +1,4 @@
-# Quotes
+# Stock Quotes (Java SDK)
 
 Retrieve real-time quotes (bid, ask, mid, last, volume, etc.) for one or more stock symbols.
 

diff --git a/docs/utilities/README.md b/docs/utilities/README.md
@@ -1,11 +1,11 @@
-# Utilities
+# Utilities (Java SDK)
 
 The Java SDK from Market Data provides utility methods for checking API health, inspecting your account quota, and debugging requests. These methods provide a typed interface over the underlying HTTP requests and responses, with both sync and async variants.
 
 Reach the resource through `client.utilities()`.
 
 ## Utilities Endpoints
 
-- [Status](./status.md)
-- [User](./user.md)
-- [Headers](./headers.md)
+- [API Status (Java SDK)](./status.md) — Call status() on the Java SDK utilities resource for a public liveness check of Market Data API services, with an online flag and uptime percentiles.
+- [User (Java SDK)](./user.md) — Retrieve your Market Data account details with the Java SDK, including how much of the daily request quota is still available.
+- [Headers (Java SDK)](./headers.md) — Echo back the headers the Market Data API received with the Java SDK, to confirm your Authorization header arrived. Sensitive values are redacted.
diff --git a/docs/utilities/headers.md b/docs/utilities/headers.md
@@ -1,4 +1,4 @@
-# Headers
+# Headers (Java SDK)
 
 Echo back the HTTP headers the server received for your request — useful for confirming your `Authorization` header actually reached the API. Sensitive values are redacted in the response.
 
@@ -11,7 +11,7 @@ UtilitiesHeadersResponse headers()
 CompletableFuture<UtilitiesHeadersResponse> headersAsync()
 ```
 
-#### Returns
+### Returns
 
 `UtilitiesHeadersResponse` wrapping `Map<String, String>` — the headers the server received, lower-cased keys to values (sensitive values redacted server-side).
 

diff --git a/docs/utilities/status.md b/docs/utilities/status.md
@@ -1,4 +1,4 @@
-# Status
+# API Status (Java SDK)
 
 Retrieve the health of the Market Data API's services — a handy liveness check.
 
@@ -14,7 +14,7 @@ UtilitiesStatusResponse status()
 CompletableFuture<UtilitiesStatusResponse> statusAsync()
 ```
 
-#### Returns
+### Returns
 
 `UtilitiesStatusResponse` wrapping `List<ServiceStatus>`. Each `ServiceStatus` exposes the service name, a status string, an `online()` flag, uptime percentiles, and an updated timestamp.
 

diff --git a/docs/utilities/user.md b/docs/utilities/user.md
@@ -1,4 +1,4 @@
-# User
+# User (Java SDK)
 
 Retrieve your account details — including how much of your daily request quota remains. This is the same endpoint the SDK calls on startup to validate your token.
 
@@ -11,7 +11,7 @@ UtilitiesUserResponse user()
 CompletableFuture<UtilitiesUserResponse> userAsync()
 ```
 
-#### Returns
+### Returns
 
 `UtilitiesUserResponse` wrapping a `User`, which exposes your plan and quota — for example `requestsRemaining()` and `requestsLimit()`.