# 获取 ETF 实时行情

本文档描述接口：按 code 获取单只（GET /etf/realtime/{code}）。出参 data 为单个 ETFRealtimeVO，字段定义见下方「data 列表元素」。

---

## 按 code 获取单只
https://tools.zhangjianyong.top/api/etf/realtime/159796

### 接口基本信息

| 项 | 说明 |
|----|------|
| 名称 | 按 code 获取单只 ETF 实时行情 |
| 方法 | GET |
| 路径 | `/etf/realtime/{code}` |
| 说明 | 不查 etf 表，仅用路径参数 code 请求实时行情并落库返回单个 VO。成功时 name 来自数据源，失败时 name 为 null。始终返回 200，data 为单个 ETFRealtimeVO。（后端数据源已迁移为雪球。） |

### 入参

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| code | Path | String | 是 | ETF 代码。兼容格式：纯数字（如 15979、159791）或带 sh/sz 前缀（如 sh159791、sz15979），大小写不限；内部会转为雪球 symbol（如 SZ159796）后请求。 |

### 出参

统一包装为 **ApiResponse**：

| 字段 | 类型 | 说明 |
|------|------|------|
| code | Integer | 状态码，成功为 200 |
| message | String | 提示信息，成功为「成功」 |
| data | Object | **单个** ETFRealtimeVO，字段定义见下方「data 列表元素」 |

---

## 出参 data 列表元素（ETFRealtimeVO）

### data 列表元素（ETFRealtimeVO）

- **必有**：`success`（Boolean）、`code`（String）。失败时必有 `error`（String），可选 `name`（String）。
- **成功时**（`success=true`）：下表所列行情字段有值（部分可能为 null）。
- **失败时**（`success=false`）：仅 `success`、`error`、`code`、`name` 有值，其余行情字段不保证有值。

| 字段名 | 类型 | 单位/说明 | 成功时有值 | 失败时有值 |
|--------|------|-----------|------------|------------|
| success | Boolean | 是否拉取成功 | 是 | 是 |
| error | String | 失败时的错误原因 | 通常为空 | 是 |
| code | String | ETF 代码 | 是 | 是 |
| name | String | 证券名称 | 是 | 可选 |
| latestPrice | BigDecimal | 最新价（元） | 是 | 否 |
| open | BigDecimal | 今开（元） | 是 | 否 |
| high | BigDecimal | 最高价（元） | 是 | 否 |
| low | BigDecimal | 最低价（元） | 是 | 否 |
| prevClose | BigDecimal | 昨收（元） | 是 | 否 |
| changeAmount | BigDecimal | 涨跌额（元） | 是 | 否 |
| changePercent | BigDecimal | 涨幅（%） | 是 | 否 |
| turnoverRate | BigDecimal | 换手率（%） | 是 | 否 |
| amplitude | BigDecimal | 振幅（%） | 是 | 否 |
| volume | String | 成交量（手） | 是 | 否 |
| amount | String | 成交金额（元） | 是 | 否 |
| timestamp | String | 时间戳 | 是 | 否 |
| avgPrice | BigDecimal | 均价（元） | 是 | 否 |
| limitUpPrice | BigDecimal | 涨停价（元） | 是 | 否 |
| limitDownPrice | BigDecimal | 跌停价（元） | 是 | 否 |
| volumeRatio | BigDecimal | 量比（倍数） | 是 | 否 |
| outerVolume | String | 外盘（手） | 是 | 否 |
| innerVolume | String | 内盘（手） | 是 | 否 |
| bidAskDiff | String | 委差（手） | 是 | 否 |
| currentVolume | String | 现手（手，绝对值） | 是 | 否 |
| marketType | String | 市场/类型 | 是 | 否 |
| bid1Price ~ bid5Price | BigDecimal | 买一～买五价（元） | 是 | 否 |
| bid1Volume ~ bid5Volume | String | 买一～买五量（手） | 是 | 否 |
| ask1Price ~ ask5Price | BigDecimal | 卖一～卖五价（元） | 是 | 否 |
| ask1Volume ~ ask5Volume | String | 卖一～卖五量（手） | 是 | 否 |

## 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "success": true,
    "code": "159791",
    "name": "港股通互联网ETF",
    "latestPrice": 0.652,
    "open": 0.648,
    "high": 0.655,
    "low": 0.647,
    "prevClose": 0.650,
    "changeAmount": 0.002,
    "changePercent": 0.31,
    "turnoverRate": 1.25,
    "amplitude": 1.23,
    "volume": "1234567",
    "amount": "802345.00",
    "timestamp": "1707890123456",
    "avgPrice": 0.651,
    "limitUpPrice": 0.715,
    "limitDownPrice": 0.585,
    "volumeRatio": 1.02,
    "outerVolume": "600000",
    "innerVolume": "634567",
    "bidAskDiff": "-100",
    "currentVolume": "500",
    "marketType": "0",
    "bid1Price": 0.651,
    "bid1Volume": "1200",
    "bid2Price": 0.650,
    "bid2Volume": "2300",
    "bid3Price": 0.649,
    "bid3Volume": "1800",
    "bid4Price": 0.648,
    "bid4Volume": "900",
    "bid5Price": 0.647,
    "bid5Volume": "1500",
    "ask1Price": 0.652,
    "ask1Volume": "800",
    "ask2Price": 0.653,
    "ask2Volume": "1100",
    "ask3Price": 0.654,
    "ask3Volume": "2000",
    "ask4Price": 0.655,
    "ask4Volume": "700",
    "ask5Price": 0.656,
    "ask5Volume": "1300"
  }
}
```