系列：《零依赖量化数据实战》｜零依赖 · 纯 GET · 不 import 任何 SDK
适用：想做港股通资金面监控、北上资金持仓追踪、A+H 股折溢价套利，不想装库或对接多个数据源的开发者

你将得到什么

• 4 个「港股通资金」端点的路径、返回字段和语义（陆股通流向 / 沪股通持仓 / 深股通持股 / A+H 对比），照公开文档核对过的，不是猜的
• 一段 hk_connect_scan() 把 4 个端点一次性拉齐，做一张「北上资金面」快照
• 字段名容错写法（候选键命中），对字段名不敏感、对形态（list / dict）不敏感
• 完整可复制运行代码，把 你的智兔token 换成真实智兔证书即可直接跑

一、四个端点，一张语义表

「港股通资金面」拆成 4 个端点，路径前缀统一走 /ht/nbzj/，无路径参数。

GET https://api.zhituapi.com/ht/nbzj/lxgl   陆股通资金流向（北向资金净买入）
GET https://api.zhituapi.com/ht/nbzj/hgtc   沪股通持仓（沪市北向持股明细）
GET https://api.zhituapi.com/ht/nbzj/sgtc   深股通持股（深市北向持股明细）
GET https://api.zhituapi.com/ht/nbzj/ah     A+H 股对比（两地上市折溢价）

鉴权统一 ?token=<你的智兔token>。4 个端点都是整板/全量返回，无路径参数。lxgl 给资金流向量（净买入/净卖出），hgtc/sgtc 分别给沪深两市的北向持股明细，ah 给 A+H 两地上市的折溢价对比。

一个实际用法：先用 lxgl 看当天北向资金整体净流入/流出 → 用 hgtc/sgtc 看北向重仓了哪些股 → 用 ah 找 A+H 折价大的标的做套利。四步串起来就是一张「北上资金面扫描看板」。

二、字段名不固定？用候选键命中

港股通接口的返回字段名可能因数据源更新而变化。与其硬编码字段名（改了就全崩），不如用候选键列表命中抽取：

def _hit_key(d, cands):
    """从字典中按候选键名列表命中第一个存在的键。"""
    if not isinstance(d, dict):
        return None
    for k in cands:
        if k in d:
            return k
    return None

def _to_float(v):
    """把可能是 '5.2%' / '5.2' / None 的值归一成 float。"""
    if v is None:
        return None
    if isinstance(v, (int, float)):
        return float(v)
    s = str(v).replace("%", "").replace(",", "").strip()
    try:
        return float(s)
    except ValueError:
        return None

def summarize_hk(name, data):
    """从港股通返回中抽取关键字段做汇总，对字段名不敏感、对形态不敏感。"""
    if data is None:
        return f"  {name}: 无数据"
    if isinstance(data, list):
        if not data:
            return f"  {name}: 0 条"
        first = data[0] if isinstance(data[0], dict) else {}
        code_key = _hit_key(first, ["code", "dm", "symbol", "gpdm", "stockcode"])
        name_key = _hit_key(first, ["name", "mc", "gpmc", "shortname"])
        amount_key = _hit_key(first, ["amount", "je", "cje", "netbuy", "jme", "amt"])
        parts = [f"  {name}: {len(data)} 条"]
        if code_key:
            parts.append(f"首条代码={first.get(code_key)}")
        if name_key:
            parts.append(f"名称={first.get(name_key)}")
        if amount_key:
            parts.append(f"金额键={first.get(amount_key)}")
        return " | ".join(parts)
    if isinstance(data, dict):
        keys = list(data.keys())[:6]
        return f"  {name}: 聚合对象，键={keys}"
    return f"  {name}: {type(data).__name__}"

这样就算数据源把 dm 改成 stockcode，代码不用动。命不中也不报错——只是那行汇总少一个字段。

三、北上资金面扫描：把 4 个端点拉齐做快照

核心不是「把四个接口都调通」，而是把资金流向 + 持仓 + 折溢价三个维度归一后做全景扫描。我们关心两件事：

1. 每个端点各返回多少条、首条长什么样（确认数据到位）
2. 北向整体是净流入还是净流出、沪深两市持仓标的数对比

import sys, time
import requests

TOKEN = "你的智兔token"                  # ← 换成你的真实智兔token
BASE = "https://api.zhituapi.com"

HK_ENDPOINTS = {
    "lxgl": ("/ht/nbzj/lxgl", "陆股通资金流向"),
    "hgtc": ("/ht/nbzj/hgtc", "沪股通持仓"),
    "sgtc": ("/ht/nbzj/sgtc", "深股通持股"),
    "ah":   ("/ht/nbzj/ah",   "A+H股对比"),
}


def fetch(name, token=TOKEN, timeout=15):
    """拉一个港股通端点，返回 (data, err)。"""
    path, _ = HK_ENDPOINTS[name]
    url = f"{BASE}{path}"
    try:
        r = requests.get(url, params={"token": token}, timeout=timeout)
    except requests.RequestException as e:
        return None, f"网络异常：{e}"
    if r.status_code != 200:
        return None, f"{r.status_code} {r.text.strip()[:140]}"
    try:
        payload = r.json()
    except ValueError:
        return None, f"非 JSON 返回：{r.text[:140]}"
    if isinstance(payload, dict):
        detail = payload.get("detail") or payload.get("error")
        return None, f"业务错误：{detail or list(payload)[:6]}"
    return payload, None


def hk_connect_scan(token=TOKEN, sleep=0.2):
    """拉 4 个港股通端点做一张「北上资金面」快照。"""
    if token == "你的智兔token":
        print("[演示] TOKEN 为占位符，下面请求会返回错误码契约；请换成真实 token 后再跑。")
    snap = {}
    for name in HK_ENDPOINTS:
        data, err = fetch(name, token=token)
        if err:
            print(f"  {name} ({HK_ENDPOINTS[name][1]}): 暂不可用：{err}")
            snap[name] = None
        else:
            print(summarize_hk(name, data))
            snap[name] = data
        time.sleep(sleep)
    return snap

sleep=0.2 是限频保护——4 个端点 + 0.2 秒间隔 ≈ 0.8 秒，远在限频内。

四、代码自验结果

离线自测 6 项全 PASS（真实输出，不联网）：

selftest PASS: 端点注册完整(4/4) / _hit_key 命中 / _to_float 去百分号 / 列表汇总 / 空数据兜底 / 字段名不敏感 共 6 项

联网跑（占位 token）真实输出：

[演示] TOKEN 为占位符，下面请求会返回错误码契约；请换成真实 token 后再跑。
  lxgl (陆股通资金流向): 暂不可用：404 102:Licence证书(你的智兔token)不存在
  hgtc (沪股通持仓): 暂不可用：404 102:Licence证书(你的智兔token)不存在
  sgtc (深股通持股): 暂不可用：404 102:Licence证书(你的智兔token)不存在
  ah (A+H股对比): 暂不可用：404 102:Licence证书(你的智兔token)不存在

4 个端点契约一致，单端点失败不影响整体流程、程序友好退出。本文未编造任何港股通资金/持仓数据——换成覆盖该接口的正式证书后重跑，即可打印真实北上资金面全景。

五、坑与注意事项

坑 #1：102 不代表路径写对了。 鉴权发生在路由匹配之前。把路径故意写错配无效 token，同样返回 102。路径合法性只能靠客户端按白名单自查——本文 4 个路径是照公开文档核对的。

坑 #2：lxgl 是资金流量，hgtc/sgtc 是持仓存量。 lxgl（流向）给的是当天/近期的净买入/净卖出金额（流量），hgtc/sgtc（持仓）给的是北向资金当前持有的标的明细（存量）。别把流量当存量——持仓数据反映的是累计持有，不是当天买卖。

坑 #3：沪股通和深股通的标的范围不同。 沪股通（hgtc）覆盖沪市标的，深股通（sgtc）覆盖深市标的，两者不重叠。同一只股票不会同时出现在两个池子里（A+H 股除外）。合并看时要按代码区分沪深。

坑 #4：ah 的折溢价方向要看清。 A+H 对比端点给出的是 A 股相对 H 股的折溢价。溢价为正说明 A 股贵于 H 股，为负说明 A 股便宜于 H 股。做套利时方向反了会亏——A 股溢价时应该买 H 卖 A，不是反过来。

小结与下篇预告

这篇你拿到了 4 个港股通资金端点（流向/沪持仓/深持仓/A+H对比）、字段名容错抽取写法、以及一个把 4 维拉齐做北上资金面全景扫描的模板，顺带避开了 102 误判、流量存量混淆、沪深标的重叠、A+H 折溢价方向四个坑。

下一篇（#17）讲A 股公司基本面——用 /hs/gs/gsjj（公司简介）+ /hs/gs/cwzb（财务指标）+ /hs/gs/sdgd（十大股东）+ /hs/gs/ltgd（流通股东）+ /hs/gs/jjcg（基金持仓）把视野从资金面拉到公司面，做一张「个股基本面画像」。

免费领取证书

数据来自 智兔数服（www.zhituapi.com）：零 SDK、纯 GET、免费版即可起步。

领取路径：进入 www.zhituapi.com → 点击「请求证书」→「证书获取」→「免费版」（邮箱验证 3 步即可拿到 token）。

把代码里的 你的智兔token 换成你拿到的真实 token，上面的脚本就能直接打印港股通资金与持股数据。

免责声明

本文仅演示公开数据接口的用法，所有代码示例均以占位 token 自验，未含任何真实数据；文中合成数据仅为逻辑自验用途，不构成投资建议，亦不承诺收益。