实时期货、黄金贵金属、外汇数据接口文档

StockTV 提供全面的期货、黄金贵金属和外汇市场数据接口，支持全球主要交易所的期货合约、贵金属现货及期货、全球外汇货币对等多种金融产品。所有接口返回数据均为 JSON 格式。

快速开始

1. 获取 API Key

请联系官方获取有效的 API Key，所有接口调用都需要在参数中携带 key。

2. 基础信息

• 基础URL: https://api.stocktv.top
• WebSocket URL: wss://ws-api.stocktv.top/connect
• 数据格式: JSON
• 实时性: 支持 HTTP 实时查询和 WebSocket 实时推送

期货市场接口

1. 期货市场列表

获取所有期货品种列表

GET /futures/list?key=您的API_KEY

响应示例:

{
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "date": "17:57:41",
            "symbol": "FEF",
            "buy": "101.100",
            "sell": "101.200",
            "high_price": "102.600",
            "prev_price": "99.460",
            "volume": "372006.000",
            "name": "新加坡铁矿石",
            "time": "2024-08-09",
            "low_price": "99.450",
            "open_price": "99.700",
            "last_price": "101.250",
            "chg": "2.215",
            "chg_pct": "0.022"
        },
        {
            "date": "17:57:56",
            "symbol": "FCPO",
            "buy": "3749.000",
            "sell": "3750.000",
            "high_price": "3767.000",
            "prev_price": "3704.000",
            "volume": "80515.000",
            "name": "马棕油",
            "time": "2024-08-09",
            "low_price": "3709.000",
            "open_price": "3751.000",
            "last_price": "3750.800",
            "chg": "2.215",
            "chg_pct": "0.022"
        }
    ]
}

2. 期货实时行情

查询特定期货品种

GET /futures/querySymbol?key=您的API_KEY&symbol=XAG

参数说明:

• symbol: 期货品种代码

支持的期货品种:

• XAG: 白银期货
• XAU: 黄金期货
• EUA: 欧盟碳排放配额
• FEF: 新加坡铁矿石
• FCPO: 马棕油
• CL: 原油期货
• NG: 天然气期货

3. 期货K线数据

获取期货K线图表数据

GET /futures/kline?key=您的API_KEY&symbol=EUA&interval=1

参数说明:

• symbol: 期货品种代码
• interval: 时间间隔 (1, 5, 15, 30, 60, 1d)

响应示例:

{
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "date": "2024-08-07 20:29:00",
            "volume": "14",
            "high": "71.082",
            "s": "0",
            "low": "71.082",
            "position": "0",
            "close": "71.082",
            "open": "71.082",
            "timestamp": 1723062540.0
        }
    ]
}

黄金贵金属接口

1. 黄金现货数据

通过外汇接口获取黄金现货

GET /market/currency?key=您的API_KEY&symbol=XAUUSD=X

主要贵金属代码:

• XAUUSD=X: 黄金兑美元
• XAGUSD=X: 白银兑美元
• XPTUSD=X: 铂金兑美元
• XPDUSD=X: 钯金兑美元

2. 贵金属实时信息

获取当前贵金属价格

GET /market/todayMarket?key=您的API_KEY&symbol=XAUUSD=X

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "previous_close": "1950.25",
    "ask": "1951.30 x --",
    "52week_range": "1800.50 - 2050.75",
    "bid": "1950.80 x --",
    "open": "1949.75",
    "day_trange": "1948.50 - 1952.25"
  }
}

3. 贵金属K线数据

获取贵金属K线图表

GET /market/chart?key=您的API_KEY&symbol=XAUUSD=X&interval=1h

外汇市场接口

1. 外汇市场列表

获取全球汇率列表

GET /market/currencyList?key=您的API_KEY

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "conversions": {
      "GBP": {
        "CHF": 1.1427055077249675,
        "MXN": 23.271022526241303,
        "USD": 1.2672484962849393
      },
      "USD": {
        "CHF": 0.9017217310376919,
        "MXN": 18.36342484876687,
        "JPY": 161.1447184737087
      }
    },
    "generatedAt": "2024-07-01T16:00:35.664Z",
    "dataAsOf": "2024-07-01T00:00:00.000Z"
  }
}

2. 实时汇率列表

获取主要货币对实时汇率

GET /market/currency?key=您的API_KEY&countryType=sg

参数说明:

• countryType: 国家交叉汇率 (可选)

响应示例:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "symbol": "EURUSD=X",
      "chg": "+0.0016",
      "chgPct": "+0.15%",
      "name": "EUR/USD",
      "lastPrice": "1.0765"
    },
    {
      "symbol": "EURJPY=X",
      "chg": "+0.7220",
      "chgPct": "+0.42%",
      "name": "EUR/JPY",
      "lastPrice": "174.1660"
    }
  ]
}

3. 外汇K线数据

获取外汇货币对K线

GET /market/chart?key=您的API_KEY&symbol=EURUSD=X&interval=5m

参数说明:

• symbol: 货币对代码
• interval: 时间间隔 (1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo)

4. 汇率信息详情

获取汇率详细信息

GET /market/spark?key=您的API_KEY&symbol=EURUSD=X&interval=5m

WebSocket 实时数据

连接WebSocket服务器

const wsUri = "wss://ws-api.stocktv.top/connect?key=您的API_KEY";
const websocket = new WebSocket(wsUri);

实时数据格式

实时数据会根据产品类型推送不同的字段，主要包含：

基础字段:

{
  "symbol": "EURUSD=X",
  "lastPrice": "1.0765",
  "chg": "+0.0016",
  "chgPct": "+0.15%",
  "timestamp": "1717728251"
}

详细行情字段:

{
  "bid": "1.0763",
  "ask": "1.0767",
  "high": "1.0772",
  "low": "1.0758",
  "open": "1.0760",
  "volume": "125000",
  "time": "16:30:25"
}

主要产品代码参考

期货品种

品种	代码	说明
黄金期货	XAU	COMEX黄金
白银期货	XAG	COMEX白银
原油期货	CL	WTI原油
布伦特原油	BZ	布伦特原油
天然气	NG	亨利港天然气
铜期货	HG	COMEX铜
大豆	ZS	芝加哥大豆

贵金属代码

品种	代码	说明
黄金现货	XAUUSD=X	黄金兑美元
白银现货	XAGUSD=X	白银兑美元
铂金现货	XPTUSD=X	铂金兑美元
钯金现货	XPDUSD=X	钯金兑美元

主要外汇货币对

货币对	代码	说明
欧元美元	EURUSD=X	欧元兑美元
美元日元	USDJPY=X	美元兑日元
英镑美元	GBPUSD=X	英镑兑美元
美元人民币	USDCNY=X	美元兑人民币
澳元美元	AUDUSD=X	澳元兑美元
美元加元	USDCAD=X	美元兑加元

时间间隔参数说明

期货时间间隔

• 1: 1分钟
• 5: 5分钟
• 15: 15分钟
• 30: 30分钟
• 60: 60分钟
• 1d: 1天

外汇时间间隔

• 1m: 1分钟
• 2m: 2分钟
• 5m: 5分钟
• 15m: 15分钟
• 30m: 30分钟
• 60m: 60分钟
• 90m: 90分钟
• 1h: 1小时
• 1d: 1天
• 5d: 5天
• 1wk: 1周
• 1mo: 1月
• 3mo: 3月

使用示例

获取黄金实时数据

GET /market/todayMarket?key=您的API_KEY&symbol=XAUUSD=X

获取欧元美元K线数据

GET /market/chart?key=您的API_KEY&symbol=EURUSD=X&interval=1h

获取原油期货列表

GET /futures/list?key=您的API_KEY

监控多个外汇货币对

GET /market/currency?key=您的API_KEY&countryType=all

数据更新频率

• 实时行情: 秒级更新
• K线数据: 按选择间隔实时更新
• 汇率数据: 实时更新
• 期货数据: 实时更新
• 历史数据: 按需查询

错误处理

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

常见错误代码:

• 200: 操作成功
• 400: 参数错误
• 401: API Key无效
• 404: 数据不存在
• 500: 服务器内部错误

最佳实践

1. 批量数据获取

对于监控多个品种，建议使用 WebSocket 连接实时数据，减少 HTTP 请求次数。

2. 缓存策略

对于不经常变化的数据（如货币对列表），可以实施本地缓存。

3. 错误重试机制

实现适当的错误重试逻辑，处理网络波动情况。

4. 数据验证

对接收到的数据进行有效性验证，确保数据质量。

5. 频率控制

注意 API 调用频率限制，避免过度请求。

注意事项

交易时间

• 外汇市场: 24小时交易（周末除外）
• 期货市场: 按各交易所交易时间
• 贵金属: 近24小时交易

价格精度

• 外汇: 通常4位小数（日元对为2位）
• 黄金: 2位小数
• 原油: 2位小数
• 期货: 根据不同合约而定

时区考虑

所有时间戳均为UTC时间，需要注意时区转换。

---

本文档基于 StockTV API 生成，具体接口参数以最新官方文档为准。产品代码和可用性可能随市场变化而调整。