# Alltick Agent

实时金融市场数据 API，为 LLM 提供股票、外汇、加密货币等实时行情。

## 特性

- 支持多种交易品种：加密货币、股票（美股/港股/A股）、外汇、贵金属
- REST API 封装：K线、成交价、订单簿查询
- WebSocket 实时行情订阅
- MCP Server：LLM 可直接调用的工具接口
- CLI 工具：命令行快速查询

## 安装

```bash
npm install @alltick/agent
# 或
pnpm add @alltick/agent
```

## 快速开始

### Node.js API

```typescript
import { AlltickHttpClient, DEMO_TOKEN } from '@alltick/agent';

const client = new AlltickHttpClient({ token: DEMO_TOKEN });

// 获取K线数据
const response = await client.getKline({
  code: 'BTCUSDT',
  klineType: 1,  // 1分钟K线
  queryKlineNum: 10,
});

console.log(response.data?.klines);
```

### WebSocket 实时行情

```typescript
import { AlltickWsClient, WsSubscribeType } from '@alltick/agent';

const ws = new AlltickWsClient({ token: DEMO_TOKEN });

ws.on('push', (data) => {
  console.log('实时数据:', data);
});

ws.on('connected', () => console.log('已连接'));
ws.on('authenticated', async () => {
  await ws.subscribe(['BTCUSDT', 'ETHUSDT'], WsSubscribeType.TRADE);
});

await ws.connect();
```

### MCP Server

```typescript
import { AlltickMcpServer } from '@alltick/agent';

const mcp = new AlltickMcpServer({ token: DEMO_TOKEN });

// 获取工具定义
const tools = mcp.getTools();

// 调用工具
const result = await mcp.callTool({
  name: 'get_trade',
  arguments: { code: 'BTCUSDT' },
});
```

### CLI 工具

```bash
# 查询最新成交
alltick -s BTCUSDT

# 查询K线
alltick -s BTCUSDT -k 1h -n 50

# 实时订阅
alltick -s BTCUSDT -r
```

## API 文档

### 支持的交易品种

| 类型 | 代码示例 |
|------|---------|
| 加密货币 | BTCUSDT, ETHUSDT, BNBUSDT |
| 美股 | AAPL.US, TSLA.US, NVDA.US |
| 港股 | 00700.HK, 09988.HK |
| A股 | 600519.SH, 300750.SZ |
| 外汇 | EURUSD, GBPUSD, USDJPY |
| 贵金属 | XAUUSD (黄金), XAGUSD (白银) |

### K线类型

| 类型 | 代码 |
|------|------|
| 1分钟 | 1 |
| 5分钟 | 5 |
| 15分钟 | 15 |
| 30分钟 | 30 |
| 1小时 | 60 |
| 4小时 | 240 |
| 日K | 1000 |
| 周K | 2000 |
| 月K | 3000 |

### HTTP API 方法

- `getKline(params)` - 获取K线数据
- `getTrade(params)` - 获取最新成交价
- `getOrderBook(params)` - 获取订单簿
- `batchGetKline(codes, klineType, num)` - 批量获取K线

### WebSocket 事件

- `connected` - 连接成功
- `authenticated` - 认证成功
- `push` - 收到推送数据
- `error` - 错误
- `disconnected` - 连接断开
- `reconnecting` - 正在重连

### MCP 工具

| 工具名 | 描述 | 参数 |
|--------|------|------|
| get_kline | 获取K线数据 | code, kline_type, num |
| get_trade | 获取最新成交价 | code |
| get_orderbook | 获取订单簿 | code |
| get_batch_kline | 批量获取K线 | codes, kline_type, num |
| list_symbols | 列出支持的品种 | category |

## 类型定义

```typescript
import type {
  AlltickConfig,
  KlineQuery,
  KlineType,
  TradeQuote,
  OrderBook,
  WsSubscribeType,
} from '@alltick/agent';
```

## 开发

```bash
# 安装依赖
pnpm install

# 开发模式（监听变化）
pnpm dev

# 类型检查
pnpm typecheck

# 运行测试
pnpm test

# 构建
pnpm build

# 运行测试（监听模式）
pnpm test:watch
```

## License

MIT