Meridian Kit SDK for Python

Meridian Kit SDK 用于通过 Python 调用 Meridian Data API。SDK 使用 API Key，并提供 HTTP、WebSocket 业务函数和通用协议调用方式。

使用要求

• Python 3.9 或更高版本（推荐使用仍处于安全维护期的 Python 3.11 或更高版本）；
• 可访问 Meridian Data API 的网络环境；
• Meridian 提供的 API 地址，以及访问凭证页中 API Key 类型凭证的密钥（SK）。

SDK 依赖 requests>=2.31,<3 和 websocket-client>=1.8,<1.9。正常安装时，pip 会自动处理依赖；如果安装环境 不能访问 Python 包索引，需要由环境管理员预先准备依赖包。

Python 3.9 使用兼容旧版 macOS LibreSSL 的 urllib3>=1.26.20,<2；Python 3.10 及以上使用 Requests 正常解析出的 urllib3 2.x。urllib3 1.26 分支已停止常规维护， 因此新部署仍推荐使用 Python 3.11 或更高版本。

安装

首次安装

从 PyPI 安装：

python -m pip install meridian-kit-sdk

Windows PowerShell：

py -3 -m pip install meridian-kit-sdk

安装后可检查 SDK 版本：

python -c "import meridian_kit_sdk; print(meridian_kit_sdk.__version__)"

该命令会输出当前安装的 SDK 版本号。

配置并运行 Demo

如果使用仓库中的 demo.py，将以下两个占位值替换为 Meridian 提供的实际配置：

base_url = "https://api.ultrastiching.com"
api_key = "replace-with-your-api-key"

base_url 必须是 Meridian 提供的纯 HTTP(S) API 地址。当前生产 API 地址为 https://api.ultrastiching.com，不能误用 https://www.ultrastiching.com，也不能附带 /api/wd、Query 参数或 #fragment。

配置完成后执行：

python demo.py

Demo 调用 get_s_majorbiz()，成功时会输出服务端返回的 JSON 数据。示例中的股票 代码和日期可根据实际查询需求修改。

调用业务函数

SDK 业务函数通过 MeridianClient 调用，SDK 自动添加 Authorization: Bearer <API Key>：

from meridian_kit_sdk import MeridianClient

base_url = "https://api.ultrastiching.com"
api_key = "replace-with-your-api-key"

with MeridianClient(
    base_url=base_url,
    api_key=api_key,
) as client:
    result = client.get_s_majorbiz(
        code=["600745", "603986"],
        trade_date=["20240705", "20240704"],
    )
    print(result)

业务函数返回服务端响应解码后的 JSON 对象。SDK 不自动转换为 pandas.DataFrame。

完整业务函数、调用签名、HTTP 路径、参数和返回值说明见仓库中的 API_LIST.md。该文件可直接使用编辑器全文搜索函数名或业务说明。安装后也可以在 Python 中查看单个函数说明，例如：

help(MeridianClient.get_s_majorbiz)

调用 WebSocket 接口

WebSocket 与 HTTP 使用同一个 api_key。SDK 只把它作为 Authorization: Bearer <API Key> 请求头带入握手，不增加签名、刷新或其他鉴权流程。

from meridian_kit_sdk import MeridianClient

with MeridianClient(
    base_url="https://api.ultrastiching.com",
    api_key=api_key,
) as client:
    with client.ws_newsflash(limit=10) as stream:
        while True:
            message = stream.receive_json()
            print(message)

ws_newsflash() 使用目录中的 wss://ws.ultrastiching.com/api/wd/ws/newsflash 建立连接，并在连接后发送订阅 JSON。SDK 不自动重连或重发订阅；调用方应在保存已处理 消息的 cursor 后自行决定何时重连，避免重复处理。测试环境可通过 websocket_base_url= 覆盖 WebSocket 域名。

从旧 AK/SK 接入迁移

用户端统一使用 api_key，不再接受 AK/SK 签名。升级时会吊销有效旧凭证并生成全新的 API Key； 请到控制台的“访问凭证”查看新 API Key，更新 SDK 后改用 api_key= 参数。 旧 SK 不能直接当作新 API Key。SDK 不再接收 access_key / secret_key 参数。

通过 API 路径调用

当需要直接调用 API 路径时，可以使用 request()：

with MeridianClient(
    base_url=base_url,
    api_key=api_key,
) as client:
    response = client.request(
        "POST",
        "/api/wd/get_s_majorbiz",
        json={
            "code": {"symbols": ["600745", "603986"]},
            "trade_date": {"dates": ["20240705", "20240704"]},
        },
    )
    result = response.json()

request() 返回 requests.Response。请求路径必须以单个 / 开头，不能传入完整 URL。请求体最大为 1 MiB。

错误处理

from meridian_kit_sdk import (
    MeridianApiError,
    MeridianResponseError,
    MeridianTransportError,
)

try:
    result = client.get_s_majorbiz(
        code=["600745"],
        trade_date=["20240705"],
    )
except MeridianApiError as error:
    # 服务端返回非 2xx。
    print(error.status_code, error.error_code, error.message, error.request_id)
except MeridianTransportError as error:
    # DNS、连接、TLS 或响应读取失败。
    print(error)
except MeridianResponseError as error:
    # 服务端返回 2xx，但响应不是合法 JSON。
    print(error.request_id)

SDK 默认不自动重试。网络中断时不能仅根据客户端错误判断服务端是否已经完成调用； 是否重试应结合具体业务和计费规则决定。

常见问题

提示 No module named 'meridian_kit_sdk'

确认安装 SDK 和运行程序使用的是同一个 Python 解释器，并重新执行安装命令。

返回 401 或 API Key 无效

检查凭证是否有效，以及 API Key 是否为控制台当前显示的完整新密钥。 不要覆盖 Authorization 或 X-Meridian-* 鉴权请求头。

返回 405，且 code 和 request_id 都为空

这通常表示请求没有进入 Meridian Data API 网关，而是发到了网站入口。确认 base_url 使用 https://api.ultrastiching.com，不要使用 https://www.ultrastiching.com。SDK 会自动拼接 /api/wd/...，不要把该路径加到 base_url 中。

网络连接失败

检查域名解析、代理、防火墙、TLS 证书和目标 API 地址。若所在环境必须使用代理， 请先按所在组织的网络规范配置 Python/Requests 代理。

出现 NotOpenSSLWarning

该警告通常表示旧版 macOS Python 使用 LibreSSL，同时环境中残留了 urllib3 2.x。 请重新安装当前 SDK，让 pip 按 Python 3.9 的依赖约束安装兼容版本：

python -m pip install --upgrade --force-reinstall meridian-kit-sdk

接口返回不可用

确认当前凭证是否有权调用目标接口，以及接口是否已对当前账号发布。如需定位，向 Meridian 支持人员提供异常中的 request_id，不要提供 Secret Key。

升级与卸载

升级到新版本

使用 --upgrade 安装最新版本：

python -m pip install --upgrade meridian-kit-sdk

重新安装同一版本

如果需要重新安装当前版本，使用 --force-reinstall 保证替换本地已经安装的内容：

python -m pip install --force-reinstall meridian-kit-sdk

卸载

卸载 SDK：

python -m pip uninstall meridian-kit-sdk

凭证安全

• 不要将真实 SK 提交到 Git、粘贴到工单或发送到群聊；
• 不要在日志、异常消息或截图中输出完整 AK/SK；
• API Key 只通过 SDK 管理的 Authorization 头传递，不要放入 URL 或 Query；
• 如果凭证疑似泄露，应立即联系 Meridian 管理员撤销并重新生成。