如何快速接入贵金属期货实时行情 API：python 实战分享

原创

FxStock Lab

发布于 2026-01-20 18:49:06

在贵金属期货交易与量化分析中，实时行情数据是核心前提。无论是黄金、白银等贵金属，还是原油、天然气等能源期货，及时获取主力合约及实时报价，能为交易决策提供关键支撑。本文将以 Python 为工具，带你快速完成贵金属期货实时行情 API 的接入，覆盖核心品种与主力合约筛选，附完整可运行代码。

一、前期准备：环境与 API 选择

1. 开发环境配置

本次实战基于 Python 3.6+版本，需提前安装核心依赖库：

requests：用于发送 HTTP 请求，调用 API 接口；
pandas：用于数据解析、筛选与格式化，方便后续分析。

安装命令直接在终端执行：

pip install requests pandas

2. API 选择建议

选择 API 时需重点关注 3 点：

1. 品种覆盖度（需包含黄金、白银、原油、天然气）;
1. 实时性（延迟 ≤2 秒）;
1. 支持主力合约查询;

本文代码示例以 iTick API 为例（需提前注册账号，获取 API token），其支持黄金（AU）、白银（AG）、原油（CL）、天然气（NG）等品种，可直接返回主力合约行情。

二、Python 代码实战：接入实时行情与主力合约筛选

1. 核心代码实现

以下代码完整实现“API 调用-数据解析-主力合约筛选-结果输出”全流程，可直接替换 API token 运行：

import requests
import pandas as pd
from datetime import datetime

def get_precious_metal_quote(token):
    # API基础地址
    base_url = "https://api.itick.org/future/quotes"
    # 品种配置：按region分组
    symbol_groups = {
        "CN": "AU,AG",  # 黄金、白银
        "US": "CL,NG"   # 原油、天然气
    }

    quote_list = []

    headers = {
        "accept": "application/json",
        "token": token
    }

    try:
        for region, codes in symbol_groups.items():
            # 构建请求参数
            params = {
                "region": region,
                "codes": codes
            }

            # 发送GET请求
            response = requests.get(base_url, params=params, headers=headers, timeout=5)
            response.raise_for_status()  # 抛出HTTP请求异常
            data = response.json()

            # 数据校验
            if data["code"] != 0:
                print(f"API调用失败 for {region}: {data.get('msg', 'Unknown error')}")
                continue

            quotes_data = data["data"]

            for code, quote_data in quotes_data.items():
                # 提取关键字段，并适配原格式
                quote = {
                    "symbol": quote_data["s"],
                    "contract": f"{quote_data['s']}主力",  # 假设返回为主力合约
                    "price": quote_data["ld"],
                    "change": f"{quote_data['ch']} ({quote_data['chp']}%)",
                    "volume": quote_data["v"],
                    "update_time": datetime.fromtimestamp(quote_data["t"] / 1000).strftime("%Y-%m-%d %H:%M:%S")
                }
                quote_list.append(quote)

        if not quote_list:
            return None

        # 转换为DataFrame
        df = pd.DataFrame(quote_list)

        # 由于API直接返回主力行情，无需额外筛选
        result_df = df[[
            "symbol", "contract", "price", "change", "volume", "update_time"
        ]]

        return result_df

    except requests.exceptions.RequestException as e:
        print(f"网络请求异常：{e}")
        return None
    except Exception as e:
        print(f"数据处理异常：{e}")
        return None

# 主程序
if __name__ == "__main__":
    # 替换为你的API token
    TOKEN = "your_token_here"
    # 获取行情数据
    market_quote = get_precious_metal_quote(TOKEN)
    if market_quote is not None:
        print("贵金属期货主力合约实时行情：")
        print(market_quote.to_string(index=False))
    else:
        print("未能获取行情数据")

2. 代码关键说明

品种代码适配：iTick API 使用 region 和 codes 参数，例如 CN&codes=AU,AG 为黄金和白银，US&codes=CL,NG 为原油和天然气。需参考 API 文档确认具体代码；
主力合约筛选：iTick API 返回的报价通常对应主力或连续合约，若需精确主力，可根据文档调整 codes（例如使用连续合约代码如 AU0）；
异常处理：加入超时控制、HTTP 异常捕获，避免因网络波动或 API 限制导致程序崩溃。