> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/en-docs/sdk-and-tools/java-sdk.md).

# Java SDK

### Overview

Official Java SDK for the Infoway real-time financial data API, using the Builder pattern with REST API and WebSocket streaming support.

| Item          | Details                                                                            |
| ------------- | ---------------------------------------------------------------------------------- |
| Maven Central | [`io.infoway:infoway-sdk`](https://repo1.maven.org/maven2/io/infoway/infoway-sdk/) |
| Java          | 17+                                                                                |
| Dependencies  | OkHttp 4.x, Gson, SLF4J                                                            |
| License       | MIT                                                                                |
| GitHub        | [infoway-api/infoway-sdk-java](https://github.com/infoway-api/infoway-sdk-java)    |

### Installation

#### Maven

```xml
<dependency>
    <groupId>io.infoway</groupId>
    <artifactId>infoway-sdk</artifactId>
    <version>0.1.0</version>
</dependency>
```

#### Gradle

```groovy
implementation 'io.infoway:infoway-sdk:0.1.0'
```

### Quick Start

```java
import io.infoway.sdk.InfowayClient;
import io.infoway.sdk.KlineType;
import com.google.gson.JsonElement;

// Create client
InfowayClient client = InfowayClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

// Real-time trade data
JsonElement trades = client.stock().getTrade("AAPL.US");

// Crypto K-lines
JsonElement klines = client.crypto().getKline("BTCUSDT", KlineType.DAY, 100);

// Market temperature
JsonElement temp = client.market().getTemperature("HK,US");

// Industry sectors
JsonElement industry = client.plate().getIndustry("HK", 10);

// Company overview
JsonElement company = client.stockInfo().getCompany("AAPL.US");

// Clean up
client.close();
```

### Configuration

| Builder Method  | Default                   | Description               |
| --------------- | ------------------------- | ------------------------- |
| `apiKey(key)`   | `INFOWAY_API_KEY` env     | API key                   |
| `baseUrl(url)`  | `https://data.infoway.io` | Base URL                  |
| `timeout(secs)` | `15`                      | Request timeout (seconds) |
| `maxRetries(n)` | `3`                       | Max retries               |

### REST API Clients

#### Market Data (stock / crypto / japan / india / common)

| Method                         | Description          |
| ------------------------------ | -------------------- |
| `getTrade(codes)`              | Real-time trade data |
| `getDepth(codes)`              | Order book depth     |
| `getKline(codes, type, count)` | K-line data          |

#### Basic Info

```java
client.basic().getSymbols("US");                    // Symbol list
client.basic().getSymbolInfo("AAPL.US");            // Symbol details
client.basic().getTradingDays("US");                // Trading calendar
client.basic().getTradingHours("US");               // Trading hours
client.basic().getAdjustmentFactors("AAPL.US");     // Adjustment factors
```

#### Market Overview

```java
client.market().getTemperature("HK,US");   // Market temperature
client.market().getBreadth("US");          // Advance / decline
client.market().getIndexes();              // Global indexes
client.market().getLeaders("US", 10);      // Leading industries
client.market().getRankConfig("US");       // Ranking config
```

#### Plate / Sector Analysis

```java
client.plate().getIndustry("HK", 200);              // Industry sector list
client.plate().getConcept("HK", 100);               // Concept sector list
client.plate().getMembers("IN20293.HK", 0, 50);     // Sector constituents
client.plate().getIntro("IN20293.HK");              // Industry introduction
client.plate().getChart("HK", 50);                  // Sector heatmap
```

#### Stock Fundamentals

```java
client.stockInfo().getValuation("AAPL.US");  // Valuation data
client.stockInfo().getRatings("AAPL.US");    // Analyst ratings
client.stockInfo().getCompany("AAPL.US");    // Company overview
client.stockInfo().getPanorama("AAPL.US");    // Stock panorama
client.stockInfo().getConcepts("AAPL.US");    // Concept tags
client.stockInfo().getEvents("AAPL.US", 20);  // Corporate events
client.stockInfo().getDrivers("AAPL.US");     // Key drivers
```

### WebSocket Streaming

```java
import io.infoway.sdk.InfowayWebSocket;

InfowayWebSocket ws = InfowayWebSocket.builder()
    .apiKey("YOUR_API_KEY")
    .business("stock")
    .onTrade(msg -> System.out.println("Trade: " + msg))
    .onDepth(msg -> System.out.println("Depth: " + msg))
    .onKline(msg -> System.out.println("Kline: " + msg))
    .onError(err -> System.err.println("Error: " + err.getMessage()))
    .onReconnect(() -> System.out.println("Reconnected"))
    .build();

ws.connect();
ws.subscribeTrade("AAPL.US,TSLA.US");
ws.subscribeDepth("AAPL.US");

// Unsubscribe
ws.unsubscribeTrade("TSLA.US");
// Close connection
ws.close();
```

### K-line Types

| Enum         | Interval   |
| ------------ | ---------- |
| MIN\_1 (1)   | 1 minute   |
| MIN\_5 (2)   | 5 minutes  |
| MIN\_15 (3)  | 15 minutes |
| MIN\_30 (4)  | 30 minutes |
| HOUR\_1 (5)  | 1 hour     |
| HOUR\_2 (6)  | 2 hours    |
| HOUR\_4 (7)  | 4 hours    |
| DAY (8)      | Daily      |
| WEEK (9)     | Weekly     |
| MONTH (10)   | Monthly    |
| QUARTER (11) | Quarterly  |
| YEAR (12)    | Yearly     |

### Error Handling

```java
import io.infoway.sdk.exception.*;

try {
    client.stock().getTrade("AAPL.US");
} catch (InfowayAuthException e) {
    System.err.println("Auth failed: " + e.getMsg());
} catch (InfowayApiException e) {
    System.err.println("API error [" + e.getRet() + "]: " + e.getMsg());
    System.err.println("Trace ID: " + e.getTraceId());
} catch (InfowayTimeoutException e) {
    System.err.println("Timeout: " + e.getMessage());
}
```

***