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 生成，具體接口參數以最新官方文檔為準。產品代碼和可用性可能隨市場變化而調整。