docs: sync from documentation@55d35fe34473617fb1009ba844cffec94a57f0bc

docs/.sync-manifest.txt

@@ -0,0 +1,28 @@
+# Auto-generated by MarketDataApp/documentation/scripts/export-sdk-docs.js.
+# These files are owned by the docs sync workflow — do not edit them by hand.
+# Editing this manifest will not break anything; the workflow rebuilds it each run.
+.sync-manifest.txt
+README.md
+authentication.md
+client.md
+funds/README.md
+funds/candles.md
+installation.md
+markets/README.md
+markets/status.md
+options/README.md
+options/chain.md
+options/expirations.md
+options/lookup.md
+options/quotes.md
+settings.md
+stocks/README.md
+stocks/candles.md
+stocks/earnings.md
+stocks/news.md
+stocks/prices.md
+stocks/quotes.md
+utilities/README.md
+utilities/headers.md
+utilities/status.md
+utilities/user.md

docs/README.md

@@ -0,0 +1,63 @@
+# Java SDK
+
+Welcome to the Market Data Java SDK documentation. This SDK lets you integrate Market Data services into any JVM application. It ships typed, records-based responses, sync **and** async (`CompletableFuture`) variants for every endpoint, automatic retries and rate-limit tracking, and a sealed exception hierarchy you can branch on exhaustively.
+
+The SDK is written in Java (JDK 17+) with no Kotlin runtime dependency, but it is designed to be **idiomatic from Kotlin too**: nullability is annotated (no platform types), the client is `AutoCloseable` (so `use {}` works), and async methods return `CompletableFuture`, which Kotlin interops with directly.
+
+## Quick Start
+
+### Java
+
+```java
+import com.marketdata.sdk.MarketDataClient;
+import com.marketdata.sdk.stocks.StockQuoteRequest;
+
+// The no-arg constructor reads MARKETDATA_TOKEN from the environment (or a .env file)
+// and validates it on startup. The client is AutoCloseable.
+try (MarketDataClient client = new MarketDataClient()) {
+
+  // A single quote — quote(...) returns a list; a single symbol is row 0.
+  var quote = client.stocks().quote(StockQuoteRequest.of("AAPL")).values().get(0);
+  System.out.println(quote.symbol() + " last=" + quote.last());
+}
+```
+
+### Kotlin
+
+```kotlin
+import com.marketdata.sdk.MarketDataClient
+import com.marketdata.sdk.stocks.StockQuoteRequest
+
+// `use {}` closes the client when the block ends — the Kotlin equivalent of try-with-resources.
+MarketDataClient().use { client ->
+    val quote = client.stocks().quote(StockQuoteRequest.of("AAPL")).values()[0]
+    println("${quote.symbol()} last=${quote.last()}")
+}
+```
+
+## Open Source
+
+The SDK is open source and available on GitHub. Feel free to contribute to the project, report bugs, or request new features.
+
+- [Java SDK on GitHub](https://github.com/MarketDataApp/sdk-java/)
+
+## Documentation
+
+The best source for documentation on the SDK is right here. This documentation is the most up-to-date and accurate source of information on the SDK.
+
+## Using the SDK
+
+This SDK is designed to help you get up and running with Market Data's APIs as quickly as possible, providing all the tools you need to access real-time stock and options prices, historical data, and much more.
+
+### Getting Started
+
+1. [Install the SDK](./installation.md) into a Gradle or Maven project.
+2. Set up your [authentication token](./authentication.md) to access the API.
+3. Learn about the [client](./client.md) and how to make your first API requests.
+4. Configure [Settings](./settings.md) to customize output format, date format, and other universal parameters.
+5. Explore the available endpoints for [stocks](./stocks/README.md), [options](./options/README.md), [funds](./funds/README.md), [markets](./markets/README.md), and [utilities](./utilities/README.md).
+
+### Support
+
+- If you have any questions or need further assistance, please don't hesitate to open a ticket at our [helpdesk](https://www.marketdata.app/dashboard/).
+- If you find a bug you may also [open an issue in our GitHub repository](https://github.com/MarketDataApp/sdk-java/issues). Please only open issues if you find a bug. Use our helpdesk for general questions or implementation assistance.

docs/authentication.md

@@ -0,0 +1,120 @@
+# Authentication
+
+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/).
+
+There are three ways to set your token when using the Java SDK:
+
+1. Set it from an environment variable _(recommended for production)_
+2. Load it from a `.env` file _(recommended for local development)_
+3. Pass it directly when creating the [client](./client.md)
+
+On startup, the SDK looks for the `MARKETDATA_TOKEN` environment variable. If found, it uses that token for all requests. The SDK also loads a `.env` file automatically from the working directory if one is present.
+
+> [!TIP]
+> When your code is running in a production environment, we recommend using an environment variable to ensure your token is not stored with your code. This is the most secure way to set your token.
+
+## How To Set Up The Environment Variable
+
+### Set The Environment Variable In The Console
+
+### Mac / Linux
+
+This command sets the environment variable for the current session only. If you open a new terminal or restart your computer, it will not persist.
+
+```bash
+export MARKETDATA_TOKEN="your_api_token"
+```
+
+#### Make The Variable Persistent
+
+Add the `export` line to your shell's profile script (`~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, etc.), then restart your terminal or run `source ~/.zshrc` (adjusting for your shell).
+
+### Windows
+
+`setx` sets the variable permanently, but it is not available in the current Command Prompt session — open a new one after running it.
+
+```bash
+setx MARKETDATA_TOKEN "your_api_token"
+```
+
+### Using a .env File
+
+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"
+MARKETDATA_TOKEN=your_api_token
+```
+
+> [!WARNING]
+> Add `.env` to your `.gitignore` so the token is not committed to source control.
+
+### Make A Test Request
+
+Verify your authentication is working by making a test request against `SPY` (or any symbol that requires authentication). Do **not** use `AAPL` to test authentication — `AAPL` is a free test symbol and returns data even when you are not authenticated.
+
+### Java
+
+```java
+import com.marketdata.sdk.MarketDataClient;
+import com.marketdata.sdk.stocks.StockQuoteRequest;
+import com.marketdata.sdk.exception.AuthenticationError;
+
+// No need to pass a token here — the SDK reads MARKETDATA_TOKEN automatically.
+try (MarketDataClient client = new MarketDataClient()) {
+  var quote = client.stocks().quote(StockQuoteRequest.of("SPY")).values().get(0);
+  System.out.println(quote.symbol() + " last=" + quote.last());
+} catch (AuthenticationError e) {
+  System.out.println("Authentication failed: " + e.getMessage());
+}
+```
+
+### Kotlin
+
+```kotlin
+import com.marketdata.sdk.MarketDataClient
+import com.marketdata.sdk.stocks.StockQuoteRequest
+import com.marketdata.sdk.exception.AuthenticationError
+
+MarketDataClient().use { client ->
+    try {
+        val quote = client.stocks().quote(StockQuoteRequest.of("SPY")).values()[0]
+        println("${quote.symbol()} last=${quote.last()}")
+    } catch (e: AuthenticationError) {
+        println("Authentication failed: ${e.message}")
+    }
+}
+```
+
+## Passing the Token Directly
+
+If you prefer to pass the token explicitly (not recommended for production code), use the four-argument constructor `(apiKey, baseUrl, apiVersion, validateOnStartup)`. Pass `null` for any slot you want resolved from the cascade or left at its default.
+
+### Java
+
+```java
+import com.marketdata.sdk.MarketDataClient;
+
+try (MarketDataClient client =
+         new MarketDataClient("your_token_here", null, null, true)) {
+  // ... make requests
+}
+```
+
+### Kotlin
+
+```kotlin
+import com.marketdata.sdk.MarketDataClient
+
+MarketDataClient("your_token_here", null, null, true).use { client ->
+    // ... make requests
+}
+```
+
+> [!NOTE]
+> **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()`).
+
+## Next Steps
+
+After successful authentication, read the overview of how the [client](./client.md) works, then configure [Settings](./settings.md) to customize output format, date format, and other universal parameters.