邮箱: xianfengcode@gmail.com
Telegram: @xinger888888
← 返回首页

API 对接手册

版本 v1 · 更新于 2026-07-07

📖 目录

一、概述

KData API 提供贵金属与外汇市场的实时报价和历史 K 线数据。所有接口通过 HTTP/HTTPS 访问，返回统一的 JSON 响应格式。

Base URL: http://127.0.0.1:8000（本地部署）
数据格式: JSON (UTF-8)
字符编码: 所有请求和响应均使用 UTF-8
时间戳: 所有时间字段均为 UTC，格式 ISO-8601

支持品种

代码名称类别
XAU现货黄金 XAU/USD贵金属
XAG现货白银 XAG/USD贵金属
EURUSD欧元 / 美元外汇
GBPUSD英镑 / 美元外汇
USDJPY美元 / 日元外汇
AUDUSD澳元 / 美元外汇

二、鉴权方式

使用 API Key 进行鉴权。每个用户拥有独立的 Key，可通过以下两种方式传递：

  1. HTTP Header（推荐）: X-API-Key: your-api-key
  2. Query 参数: ?api_key=your-api-key
⚠️ API Key 是敏感信息，请勿在客户端代码（如前端 JavaScript）中直接暴露。建议在服务端转发。

获取 API Key

联系客服（见文末联系方式），提供使用场景和预估调用量，我们会为你生成专属 API Key 并设置配额。

三、接口列表

方法路径说明鉴权
GET/api/v1/health健康检查无需
GET/api/v1/symbols品种列表需要
GET/api/v1/quote实时报价需要
GET/api/v1/klineK 线数据需要

四、实时报价接口

获取指定品种的最新实时报价。

请求

GET /api/v1/quote?symbol=XAU
Header: X-API-Key: your-key

请求参数

参数类型必填说明
symbolstring是品种代码，如 XAU、EURUSD

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "symbol": "XAU",
    "bid": 4073.13,
    "ask": 4073.13,
    "last": 4073.13,
    "high": 4079.65,
    "low": 4030.77,
    "ts": "2026-07-03T06:35:00+00:00"
  },
  "server_ts": 1782981324096
}

响应字段说明

字段类型说明
symbolstring品种代码
bidfloat买入价
askfloat卖出价
lastfloat最新成交价
highfloat当日最高价
lowfloat当日最低价
tsdatetime报价时间 (UTC)

五、K 线数据接口

获取指定品种的历史 K 线数据，支持按时间范围过滤。

请求

GET /api/v1/kline?symbol=XAU&period=1m&limit=200&from=2026-07-01T00:00:00Z&to=2026-07-02T23:59:59Z
Header: X-API-Key: your-key

请求参数

参数类型必填说明
symbolstring是品种代码
periodstring是周期：1m / 5m / 15m / 60m / 1d
limitint否返回条数，1~1000，默认 200
fromdatetime否起始时间（ISO-8601），如 2026-07-01T00:00:00Z
todatetime否结束时间
周期说明：
• 1m — 1 分钟 K 线（直接从东方财富采集）
• 5m / 15m / 60m — 从 1 分钟 K 线合成，确保 bar 对齐
• 1d — 日线

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "symbol": "XAU",
    "period": "1m",
    "count": 3,
    "bars": [
      { "ts": "2026-07-03 02:17:00", "open": 4180.55, "high": 4180.67, "low": 4179.57, "close": 4180.12, "volume": 0 },
      ...
    ]
  },
  "server_ts": 1782981324096
}

OHLCV 字段说明

字段类型说明
tsdatetimeK 线起始时间 (UTC)
openfloat开盘价
highfloat最高价
lowfloat最低价
closefloat收盘价
volumefloat成交量

六、品种列表接口

获取当前 API 支持的所有品种清单。

GET /api/v1/symbols
Header: X-API-Key: your-key

响应 data 为数组，每个元素包含 code、name、category。

七、健康检查

无需鉴权，用于监控 API 是否在线。

GET /api/v1/health

返回：{"code":0,"message":"ok","data":{"ok":true},"server_ts":...}

八、限流说明

每个 API Key 有三层独立配额，任一超限即返回 429：

层级周期免费版默认配额重置方式
分钟60 秒滑动窗口60 次/分钟自动
天自然日（UTC）10,000 次/天自动
月自然月200,000 次/月自动

超限响应示例：

HTTP/1.1 429 Too Many Requests
Retry-After: 65
X-RateLimit-Limit-Minute: 60
X-RateLimit-Limit-Day: 10000
X-RateLimit-Limit-Month: 200000

{
  "code": 42901,
  "message": "rate_limit_exceeded:minute",
  "data": { "limit": 60, "window": "minute" },
  "server_ts": ...
}
建议：在客户端实现退避策略（exponential backoff）。当收到 429 后，等待 Retry-After 头指定的秒数再重试。

九、错误码表

HTTP 状态码codemessage说明
2000ok成功
40140101missing_api_key未提供 API Key
40140102invalid_api_keyAPI Key 无效或已过期
40440401quote not available yet报价数据暂不可用（数据源延迟）
422-validation error请求参数校验失败（具体见响应 detail）
42942901rate_limit_exceeded:xxx调用频率超限

十、通用响应格式

所有接口（包括错误）使用同一响应壳：

{
  "code": 0, // 业务码：0=成功，非0=错误
  "message": "ok", // 描述信息
  "data": { ... }, // 业务数据
  "server_ts": 1782981324096 // 服务器时间戳（毫秒）
}

十一、代码示例

cURL

# 获取黄金报价
curl.exe -H "X-API-Key: your-key" \
  "http://127.0.0.1:8000/api/v1/quote?symbol=XAU"

# 获取欧元/美元 1分钟K线
curl.exe -H "X-API-Key: your-key" \
  "http://127.0.0.1:8000/api/v1/kline?symbol=EURUSD&period=1m&limit=50"

Python (requests)

import requests

KEY = "your-key"
headers = {"X-API-Key": KEY}

# 报价
r = requests.get("http://127.0.0.1:8000/api/v1/quote",
  params={"symbol": "XAU"}, headers=headers)
print(r.json()["data"]["last"])

# K 线
r = requests.get("http://127.0.0.1:8000/api/v1/kline",
  params={"symbol": "EURUSD", "period": "1m", "limit": 100},
  headers=headers)
bars = r.json()["data"]["bars"]

PHP (Guzzle)

$client = new \GuzzleHttp\Client([
  'base_uri' => 'http://127.0.0.1:8000',
  'headers' => ['X-API-Key' => 'your-key']
]);

$r = $client->get('/api/v1/quote', ['query' => ['symbol' => 'XAU']]);
$data = json_decode($r->getBody(), true);
echo $data['data']['last'];

JavaScript (fetch)

const KEY = 'your-key';
const res = await fetch(
  'http://127.0.0.1:8000/api/v1/quote?symbol=XAU',
  { headers: { 'X-API-Key': KEY } }
);
const json = await res.json();
console.log(json.data.last);

十二、支持与联系

获取 API Key、咨询专业版配额或定制开发需求，请通过以下方式联系我们：

✉️
邮箱

xianfengcode@gmail.com

💬
微信

KData_WeChat

📱
Telegram

@xinger888888