@awaken-finance/agent-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Awaken Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# Awaken Agent Kit
+
+[![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87%E6%96%87%E6%A1%A3-blue)](./README.zh-CN.md)
+
+> AI Agent toolkit for [Awaken DEX](https://awaken.finance) on the [aelf](https://aelf.com) blockchain — swap tokens, manage liquidity, and fetch K-line data.
+
+---
+
+## Architecture
+
+```
+awaken-agent-kit/
+├── index.ts                  # SDK entry — direct import for LangChain / LlamaIndex
+├── src/
+│   ├── core/                 # Pure business logic (no I/O side effects)
+│   │   ├── query.ts          # getQuote, getPair, getTokenBalance, getTokenAllowance, getLiquidityPositions
+│   │   ├── trade.ts          # executeSwap, addLiquidity, removeLiquidity, approveTokenSpending
+│   │   └── kline.ts          # fetchKline, getKlineIntervals
+│   └── mcp/
+│       └── server.ts         # MCP adapter — for Claude Desktop, Cursor, GPT, etc.
+├── awaken_query_skill.ts     # CLI adapter — OpenClaw / terminal query commands
+├── awaken_trade_skill.ts     # CLI adapter — OpenClaw / terminal trade commands
+├── awaken_kline_skill.ts     # CLI adapter — OpenClaw / terminal K-line commands
+├── cli-helpers.ts            # CLI output helpers (outputSuccess / outputError)
+├── lib/
+│   ├── config.ts             # Network config, env overrides, defaults
+│   ├── aelf-client.ts        # aelf-sdk wrapper (wallet, contract calls, decimals)
+│   └── types.ts              # TypeScript interfaces & constants
+├── openclaw.json             # OpenClaw tool definitions
+├── mcp-config.example.json   # MCP client config example
+├── .env.example              # Environment variable template
+└── __tests__/                # Unit / Integration / E2E tests
+```
+
+**Core + Adapters pattern:**
+
+| Layer | Location | Role |
+|-------|----------|------|
+| **Core** | `src/core/` | Pure functions. No `process.exit`, no `console.log`. Throw on error. |
+| **CLI Adapter** | `awaken_*_skill.ts` | Thin wrappers using `commander`. Parses args → calls core → outputs JSON. |
+| **MCP Adapter** | `src/mcp/server.ts` | Registers core functions as MCP tools for Claude Desktop, Cursor, GPT, etc. |
+| **SDK** | `index.ts` | Re-exports core functions + types. `import { executeSwap } from '@awaken-finance/agent-kit'`. |
+
+---
+
+## Features
+
+| # | Category | Capability | CLI Tool | MCP Tool | SDK Function |
+|---|----------|-----------|----------|----------|-------------|
+| 1 | Query | Swap quote & route | `awaken-query-quote` | `awaken_quote` | `getQuote` |
+| 2 | Query | Trade pair info | `awaken-query-pair` | `awaken_pair` | `getPair` |
+| 3 | Query | Token balance | `awaken-query-balance` | `awaken_balance` | `getTokenBalance` |
+| 4 | Query | Token allowance | `awaken-query-allowance` | `awaken_allowance` | `getTokenAllowance` |
+| 5 | Query | Liquidity positions (+ USD) | `awaken-query-liquidity` | `awaken_liquidity` | `getLiquidityPositions` |
+| 6 | Trade | Swap tokens | `awaken-trade-swap` | `awaken_swap` | `executeSwap` |
+| 7 | Trade | Add liquidity | `awaken-trade-add-liquidity` | `awaken_add_liquidity` | `addLiquidity` |
+| 8 | Trade | Remove liquidity | `awaken-trade-remove-liquidity` | `awaken_remove_liquidity` | `removeLiquidity` |
+| 9 | Trade | Approve token spending | `awaken-trade-approve` | `awaken_approve` | `approveTokenSpending` |
+| 10 | K-Line | Fetch candlestick data | `awaken-kline-fetch` | `awaken_kline_fetch` | `fetchKline` |
+| 11 | K-Line | List intervals | `awaken-kline-intervals` | `awaken_kline_intervals` | `getKlineIntervals` |
+
+---
+
+## Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.0
+- An aelf wallet private key (for trade operations only)
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# As a dependency
+bun add @awaken-finance/agent-kit
+
+# Or clone and install locally
+git clone https://github.com/AwakenFinance/awaken-agent-skills.git
+cd awaken-agent-skills
+bun install
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+# Edit .env — add your AELF_PRIVATE_KEY
+```
+
+**Config priority (high → low):**
+
+1. Function params (SDK callers)
+2. CLI args (`--network`, `--slippage`)
+3. MCP env block (`mcp.json` → `env: {}`)
+4. Environment variables (`AWAKEN_*`)
+5. `.env` file
+6. Code defaults
+
+See [`.env.example`](./.env.example) for all available overrides (RPC URL, API URL, contract addresses, slippage, etc.).
+
+---
+
+## Usage
+
+### CLI (OpenClaw / Terminal)
+
+```bash
+# Query swap quote
+bun run awaken_query_skill.ts quote --symbol-in ELF --symbol-out USDT --amount-in 10
+
+# Query trade pair
+bun run awaken_query_skill.ts pair --token0 ELF --token1 USDT --fee-rate 0.3
+
+# Query balance
+bun run awaken_query_skill.ts balance --address YOUR_ADDRESS --symbol ELF
+
+# Query liquidity positions
+bun run awaken_query_skill.ts liquidity --address YOUR_ADDRESS
+
+# Swap tokens (requires AELF_PRIVATE_KEY)
+bun run awaken_trade_skill.ts swap --symbol-in ELF --symbol-out USDT --amount-in 1
+
+# Add liquidity (requires AELF_PRIVATE_KEY)
+bun run awaken_trade_skill.ts add-liquidity --token-a ELF --token-b USDT --amount-a 10 --amount-b 5
+
+# Remove liquidity (requires AELF_PRIVATE_KEY)
+bun run awaken_trade_skill.ts remove-liquidity --token-a ELF --token-b USDT --lp-amount 0.5
+
+# Fetch K-line data
+bun run awaken_kline_skill.ts fetch --pair-id PAIR_UUID --interval 1D
+
+# List K-line intervals
+bun run awaken_kline_skill.ts intervals
+```
+
+All commands output standardized JSON on success. Errors go to stderr with `[ERROR]` prefix.
+
+### MCP (Claude Desktop / Cursor / GPT)
+
+1. Copy the config from [`mcp-config.example.json`](./mcp-config.example.json) into your AI tool's MCP settings:
+
+   - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Cursor (project)**: `.cursor/mcp.json`
+   - **Cursor (global)**: `~/.cursor/mcp.json`
+
+2. Update the path and environment variables:
+
+```json
+{
+  "mcpServers": {
+    "awaken-agent-kit": {
+      "command": "bun",
+      "args": ["run", "/ABSOLUTE/PATH/TO/scripts/skills/src/mcp/server.ts"],
+      "env": {
+        "AELF_PRIVATE_KEY": "your_private_key_here",
+        "AWAKEN_NETWORK": "mainnet"
+      }
+    }
+  }
+}
+```
+
+3. Start the MCP server manually (for debugging):
+
+```bash
+bun run mcp
+```
+
+### SDK (TypeScript / JavaScript)
+
+```typescript
+import {
+  getQuote,
+  executeSwap,
+  getNetworkConfig,
+  getLiquidityPositions,
+} from '@awaken-finance/agent-kit';
+
+// Query a swap quote
+const config = getNetworkConfig('mainnet');
+const quote = await getQuote(config, {
+  symbolIn: 'ELF',
+  symbolOut: 'USDT',
+  amountIn: '10',
+});
+console.log(quote);
+
+// Execute a swap (requires privateKey)
+const result = await executeSwap(config, wallet, {
+  symbolIn: 'ELF',
+  symbolOut: 'USDT',
+  amountIn: '10',
+  slippage: '0.005',
+});
+console.log(result.transactionId);
+```
+
+### OpenClaw
+
+Import the [`openclaw.json`](./openclaw.json) file into your OpenClaw configuration. All 11 tools are pre-configured with descriptions optimized for AI comprehension.
+
+---
+
+## Network
+
+| Network | Chain ID | RPC | Explorer |
+|---------|----------|-----|----------|
+| **mainnet** (default) | tDVV | `https://tdvv-public-node.aelf.io` | `https://aelfscan.io/tDVV` |
+| testnet | tDVW | `https://tdvw-test-node.aelf.io` | `https://testnet.aelfscan.io/tDVW` |
+
+Switch via `--network testnet` (CLI), `AWAKEN_NETWORK=testnet` (env), or pass config directly (SDK).
+
+---
+
+## Testing
+
+```bash
+# All tests
+bun test
+
+# Unit tests only
+bun run test:unit
+
+# Integration tests (requires network access)
+bun run test:integration
+
+# E2E tests (requires AELF_PRIVATE_KEY, sends real txns on mainnet)
+bun run test:e2e
+```
+
+| Test Level | Scope |
+|------------|-------|
+| **Unit** | Config, types, decimal math, core exports, error paths, MCP server, CLI helpers |
+| **Integration** | Awaken API, on-chain view calls, SignalR K-line, core query functions |
+| **E2E** | Real swap & liquidity add/remove on mainnet |
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AELF_PRIVATE_KEY` | For trades | — | aelf wallet private key |
+| `AWAKEN_NETWORK` | No | `mainnet` | `mainnet` or `testnet` |
+| `AWAKEN_RPC_URL` | No | Per network | Override RPC endpoint |
+| `AWAKEN_API_BASE_URL` | No | Per network | Override API endpoint |
+| `AWAKEN_SOCKET_URL` | No | Per network | Override SignalR endpoint |
+| `AWAKEN_EXPLORER_URL` | No | Per network | Override explorer URL |
+| `AWAKEN_TOKEN_CONTRACT` | No | Per network | Override token contract address |
+| `AWAKEN_SWAP_HOOK_CONTRACT` | No | Per network | Override swap hook contract |
+| `AWAKEN_DEFAULT_SLIPPAGE` | No | `0.005` | Default slippage tolerance |
+
+---
+
+## Security
+
+- **Never commit your `.env` file.** It is git-ignored by default.
+- Private keys are only needed for trade operations (swap, add/remove liquidity, approve). Query and K-line operations are read-only.
+- When using MCP, pass the private key via the `env` block in your MCP config — it is not transmitted over the network.
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,267 @@
+# Awaken Agent Kit
+
+[![English](https://img.shields.io/badge/docs-English-blue)](./README.md)
+
+> 面向 [Awaken DEX](https://awaken.finance)（[aelf](https://aelf.com) 区块链）的 AI Agent 工具包 —— 代币兑换、流动性管理、K 线数据获取。
+
+---
+
+## 架构
+
+```
+awaken-agent-kit/
+├── index.ts                  # SDK 入口 — 可直接导入用于 LangChain / LlamaIndex
+├── src/
+│   ├── core/                 # 纯业务逻辑（无 I/O 副作用）
+│   │   ├── query.ts          # getQuote, getPair, getTokenBalance, getTokenAllowance, getLiquidityPositions
+│   │   ├── trade.ts          # executeSwap, addLiquidity, removeLiquidity, approveTokenSpending
+│   │   └── kline.ts          # fetchKline, getKlineIntervals
+│   └── mcp/
+│       └── server.ts         # MCP 适配器 — 用于 Claude Desktop、Cursor、GPT 等
+├── awaken_query_skill.ts     # CLI 适配器 — OpenClaw / 终端查询命令
+├── awaken_trade_skill.ts     # CLI 适配器 — OpenClaw / 终端交易命令
+├── awaken_kline_skill.ts     # CLI 适配器 — OpenClaw / 终端 K 线命令
+├── cli-helpers.ts            # CLI 输出工具（outputSuccess / outputError）
+├── lib/
+│   ├── config.ts             # 网络配置、环境变量覆盖、默认值
+│   ├── aelf-client.ts        # aelf-sdk 封装（钱包、合约调用、精度转换）
+│   └── types.ts              # TypeScript 接口与常量
+├── openclaw.json             # OpenClaw 工具定义
+├── mcp-config.example.json   # MCP 客户端配置示例
+├── .env.example              # 环境变量模板
+└── __tests__/                # 单元 / 集成 / E2E 测试
+```
+
+**Core + Adapters 分层模式：**
+
+| 层 | 位置 | 职责 |
+|---|------|------|
+| **Core** | `src/core/` | 纯函数。无 `process.exit`，无 `console.log`。出错则 throw。 |
+| **CLI 适配器** | `awaken_*_skill.ts` | 基于 `commander` 的薄包装层。解析参数 → 调用 core → 输出 JSON。 |
+| **MCP 适配器** | `src/mcp/server.ts` | 将 core 函数注册为 MCP 工具，供 Claude Desktop、Cursor、GPT 等使用。 |
+| **SDK** | `index.ts` | 重新导出 core 函数和类型。`import { executeSwap } from '@awaken-finance/agent-kit'`。 |
+
+---
+
+## 功能列表
+
+| # | 分类 | 能力 | CLI 工具 | MCP 工具 | SDK 函数 |
+|---|------|------|----------|----------|----------|
+| 1 | 查询 | Swap 报价与路由 | `awaken-query-quote` | `awaken_quote` | `getQuote` |
+| 2 | 查询 | 交易对信息 | `awaken-query-pair` | `awaken_pair` | `getPair` |
+| 3 | 查询 | 代币余额 | `awaken-query-balance` | `awaken_balance` | `getTokenBalance` |
+| 4 | 查询 | 代币授权额度 | `awaken-query-allowance` | `awaken_allowance` | `getTokenAllowance` |
+| 5 | 查询 | 流动性持仓（含 USD 价值） | `awaken-query-liquidity` | `awaken_liquidity` | `getLiquidityPositions` |
+| 6 | 交易 | 代币兑换 | `awaken-trade-swap` | `awaken_swap` | `executeSwap` |
+| 7 | 交易 | 添加流动性 | `awaken-trade-add-liquidity` | `awaken_add_liquidity` | `addLiquidity` |
+| 8 | 交易 | 移除流动性 | `awaken-trade-remove-liquidity` | `awaken_remove_liquidity` | `removeLiquidity` |
+| 9 | 交易 | 授权代币消费 | `awaken-trade-approve` | `awaken_approve` | `approveTokenSpending` |
+| 10 | K线 | 获取 K 线数据 | `awaken-kline-fetch` | `awaken_kline_fetch` | `fetchKline` |
+| 11 | K线 | 列出时间间隔 | `awaken-kline-intervals` | `awaken_kline_intervals` | `getKlineIntervals` |
+
+---
+
+## 前置要求
+
+- [Bun](https://bun.sh) ≥ 1.0
+- 一个 aelf 钱包私钥（仅交易操作需要）
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+# 作为依赖安装
+bun add @awaken-finance/agent-kit
+
+# 或克隆后本地安装
+git clone https://github.com/AwakenFinance/awaken-agent-skills.git
+cd awaken-agent-skills
+bun install
+```
+
+### 2. 配置
+
+```bash
+cp .env.example .env
+# 编辑 .env — 填入你的 AELF_PRIVATE_KEY
+```
+
+**配置优先级（高 → 低）：**
+
+1. 函数参数（SDK 调用者）
+2. CLI 参数（`--network`, `--slippage`）
+3. MCP env 块（`mcp.json` → `env: {}`）
+4. 环境变量（`AWAKEN_*`）
+5. `.env` 文件
+6. 代码默认值
+
+查看 [`.env.example`](./.env.example) 了解所有可覆盖配置（RPC 地址、API 地址、合约地址、滑点等）。
+
+---
+
+## 使用方式
+
+### CLI（OpenClaw / 终端）
+
+```bash
+# 查询兑换报价
+bun run awaken_query_skill.ts quote --symbol-in ELF --symbol-out USDT --amount-in 10
+
+# 查询交易对
+bun run awaken_query_skill.ts pair --token0 ELF --token1 USDT --fee-rate 0.3
+
+# 查询余额
+bun run awaken_query_skill.ts balance --address YOUR_ADDRESS --symbol ELF
+
+# 查询流动性持仓
+bun run awaken_query_skill.ts liquidity --address YOUR_ADDRESS
+
+# 代币兑换（需要 AELF_PRIVATE_KEY）
+bun run awaken_trade_skill.ts swap --symbol-in ELF --symbol-out USDT --amount-in 1
+
+# 添加流动性（需要 AELF_PRIVATE_KEY）
+bun run awaken_trade_skill.ts add-liquidity --token-a ELF --token-b USDT --amount-a 10 --amount-b 5
+
+# 移除流动性（需要 AELF_PRIVATE_KEY）
+bun run awaken_trade_skill.ts remove-liquidity --token-a ELF --token-b USDT --lp-amount 0.5
+
+# 获取 K 线数据
+bun run awaken_kline_skill.ts fetch --pair-id PAIR_UUID --interval 1D
+
+# 列出 K 线时间间隔
+bun run awaken_kline_skill.ts intervals
+```
+
+所有命令成功时输出标准化 JSON，错误输出到 stderr 并带 `[ERROR]` 前缀。
+
+### MCP（Claude Desktop / Cursor / GPT）
+
+1. 将 [`mcp-config.example.json`](./mcp-config.example.json) 中的配置复制到你的 AI 工具的 MCP 设置中：
+
+   - **Claude Desktop**：`~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Cursor（项目级）**：`.cursor/mcp.json`
+   - **Cursor（全局）**：`~/.cursor/mcp.json`
+
+2. 更新路径和环境变量：
+
+```json
+{
+  "mcpServers": {
+    "awaken-agent-kit": {
+      "command": "bun",
+      "args": ["run", "/绝对路径/scripts/skills/src/mcp/server.ts"],
+      "env": {
+        "AELF_PRIVATE_KEY": "你的私钥",
+        "AWAKEN_NETWORK": "mainnet"
+      }
+    }
+  }
+}
+```
+
+3. 手动启动 MCP 服务器（用于调试）：
+
+```bash
+bun run mcp
+```
+
+### SDK（TypeScript / JavaScript）
+
+```typescript
+import {
+  getQuote,
+  executeSwap,
+  getNetworkConfig,
+  getLiquidityPositions,
+} from '@awaken-finance/agent-kit';
+
+// 查询兑换报价
+const config = getNetworkConfig('mainnet');
+const quote = await getQuote(config, {
+  symbolIn: 'ELF',
+  symbolOut: 'USDT',
+  amountIn: '10',
+});
+console.log(quote);
+
+// 执行兑换（需要 privateKey）
+const result = await executeSwap(config, wallet, {
+  symbolIn: 'ELF',
+  symbolOut: 'USDT',
+  amountIn: '10',
+  slippage: '0.005',
+});
+console.log(result.transactionId);
+```
+
+### OpenClaw
+
+将 [`openclaw.json`](./openclaw.json) 导入你的 OpenClaw 配置。所有 11 个工具已预配置，描述针对 AI 理解进行了优化。
+
+---
+
+## 网络
+
+| 网络 | Chain ID | RPC | 区块浏览器 |
+|------|----------|-----|-----------|
+| **mainnet**（默认） | tDVV | `https://tdvv-public-node.aelf.io` | `https://aelfscan.io/tDVV` |
+| testnet | tDVW | `https://tdvw-test-node.aelf.io` | `https://testnet.aelfscan.io/tDVW` |
+
+通过 `--network testnet`（CLI）、`AWAKEN_NETWORK=testnet`（环境变量）或直接传入 config（SDK）切换网络。
+
+---
+
+## 测试
+
+```bash
+# 全部测试
+bun test
+
+# 仅单元测试
+bun run test:unit
+
+# 集成测试（需要网络）
+bun run test:integration
+
+# E2E 测试（需要 AELF_PRIVATE_KEY，在 mainnet 发送真实交易）
+bun run test:e2e
+```
+
+| 测试级别 | 覆盖范围 |
+|---------|---------|
+| **Unit** | 配置、类型、精度运算、Core 导出、错误路径、MCP server、CLI helpers |
+| **Integration** | Awaken API、链上 view 调用、SignalR K 线、Core query 函数 |
+| **E2E** | mainnet 真实 Swap 与流动性增减 |
+
+---
+
+## 环境变量
+
+| 变量 | 是否必填 | 默认值 | 说明 |
+|------|---------|--------|------|
+| `AELF_PRIVATE_KEY` | 交易时必填 | — | aelf 钱包私钥 |
+| `AWAKEN_NETWORK` | 否 | `mainnet` | `mainnet` 或 `testnet` |
+| `AWAKEN_RPC_URL` | 否 | 按网络 | 覆盖 RPC 地址 |
+| `AWAKEN_API_BASE_URL` | 否 | 按网络 | 覆盖 API 地址 |
+| `AWAKEN_SOCKET_URL` | 否 | 按网络 | 覆盖 SignalR 地址 |
+| `AWAKEN_EXPLORER_URL` | 否 | 按网络 | 覆盖区块浏览器地址 |
+| `AWAKEN_TOKEN_CONTRACT` | 否 | 按网络 | 覆盖 Token 合约地址 |
+| `AWAKEN_SWAP_HOOK_CONTRACT` | 否 | 按网络 | 覆盖 Swap Hook 合约地址 |
+| `AWAKEN_DEFAULT_SLIPPAGE` | 否 | `0.005` | 默认滑点容忍度 |
+
+---
+
+## 安全
+
+- **永远不要提交你的 `.env` 文件。** 它已默认被 git 忽略。
+- 私钥仅用于交易操作（兑换、添加/移除流动性、授权）。查询和 K 线操作为只读。
+- 使用 MCP 时，通过 MCP 配置的 `env` 块传入私钥 —— 不会通过网络传输。
+
+---
+
+## 许可证
+
+MIT

package/awaken_kline_skill.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+// ============================================================
+// Awaken K-Line Skill - CLI Adapter (thin shell)
+// ============================================================
+// Commands: fetch, intervals
+// Core logic lives in src/core/kline.ts
+
+import { Command } from 'commander';
+import { getNetworkConfig } from './lib/config';
+import { outputSuccess, outputError } from './cli-helpers';
+import { fetchKline, getKlineIntervals } from './src/core/kline';
+
+const program = new Command();
+
+program
+  .name('awaken-kline')
+  .description('Awaken DEX K-line (candlestick) data tool')
+  .version('1.0.0')
+  .option('--network <network>', 'Network: mainnet or testnet', process.env.AWAKEN_NETWORK || 'mainnet');
+
+// ---- fetch ----
+program
+  .command('fetch')
+  .description('Fetch historical K-line data via SignalR')
+  .requiredOption('--pair-id <id>', 'Trade pair ID (UUID from pair query)')
+  .option('--interval <interval>', 'Time interval: 1m, 15m, 30m, 1h, 4h, 1D, 1W', '1D')
+  .option('--from <date>', 'Start date (ISO string or unix ms)', String(Date.now() - 7 * 24 * 60 * 60 * 1000))
+  .option('--to <date>', 'End date (ISO string or unix ms)', String(Date.now()))
+  .option('--timeout <ms>', 'Max wait time in ms', '15000')
+  .action(async (opts) => {
+    try {
+      const config = getNetworkConfig(program.opts().network);
+      const result = await fetchKline(config, {
+        tradePairId: opts.pairId,
+        interval: opts.interval,
+        from: opts.from,
+        to: opts.to,
+        timeout: parseInt(opts.timeout, 10),
+      });
+      outputSuccess(result);
+    } catch (err: any) {
+      outputError(err.message || 'K-line fetch failed');
+    }
+  });
+
+// ---- intervals ----
+program
+  .command('intervals')
+  .description('List supported K-line intervals')
+  .action(() => {
+    outputSuccess(getKlineIntervals());
+  });
+
+program.parse();