# 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());
}
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.infoway.io/en-docs/sdk-and-tools/java-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.