逻辑龙虾 API v1.0

• 最后更新：2026-08-11
• 官网：https://luojilongxia.com
• Base URL：https://api.luojilongxia.com/api/v1
• 创建 API Key：Dashboard

逻辑龙虾 API 提供结构化金融事件与辅助日线数据。v1.0 包含 4 个只读 GET 接口：

事件接口返回结构化摘要，不是新闻全文；日线不是盘中实时行情。接口不输出交易方向或投资建议。

1. 鉴权

在请求头中携带 API Key：

X-API-Key: lx_live_<key_id>_<secret>

请先在 Dashboard 创建 Key。完整密钥仅在创建时显示一次。

export LUOJILONGXIA_API_KEY='lx_live_xxx_xxx'

• 只在服务端保存 Key，不要写入前端、URL、Git 或日志。
• 每个服务器或部署环境建议使用独立 Key。
• 同一 Key 默认允许两个活跃出口 IP；60 秒窗口内出现更多出口 IP 时返回 403 api_key_ip_conflict。

2. 标的 ID 格式

事件与日线接口都使用统一的 instrument_id。不知道标准 ID 时，先调用 GET /instruments/search。

请原样传递 instrument_id，不要改写大小写或交易所前缀。

3. 快速开始

# 1) 扫描最近 30 分钟事件
curl -G 'https://api.luojilongxia.com/api/v1/recent-events' \
  -H "X-API-Key: $LUOJILONGXIA_API_KEY" \
  --data-urlencode 'since_minutes=30' \
  --data-urlencode 'page_size=20'

# 2) 按名称查找标准标的 ID
curl -G 'https://api.luojilongxia.com/api/v1/instruments/search' \
  -H "X-API-Key: $LUOJILONGXIA_API_KEY" \
  --data-urlencode 'q=宁德时代' \
  --data-urlencode 'limit=10'

# 3) 查询标的事件
curl -G 'https://api.luojilongxia.com/api/v1/instrument-events' \
  -H "X-API-Key: $LUOJILONGXIA_API_KEY" \
  --data-urlencode 'instrument_id=cn:SZSE.300750' \
  --data-urlencode 'start_datetime=2026-08-01T00:00:00+08:00' \
  --data-urlencode 'end_datetime=2026-08-08T00:00:00+08:00' \
  --data-urlencode 'page_size=20'

# 4) 查询日线
curl -G 'https://api.luojilongxia.com/api/v1/instrument-daily-bars' \
  -H "X-API-Key: $LUOJILONGXIA_API_KEY" \
  --data-urlencode 'instrument_id=cn:SZSE.300750' \
  --data-urlencode 'start_date=2026-07-01' \
  --data-urlencode 'end_date=2026-08-08' \
  --data-urlencode 'order=asc'

4. 近期事件：GET /api/v1/recent-events

扫描全市场近期事件。

查询参数

时间窗可不传、只传 since_minutes，或成对传入 start_datetime 与 end_datetime。

响应示例

{
  "start_datetime": "2026-08-08T23:30:00+08:00",
  "end_datetime": "2026-08-09T00:00:00+08:00",
  "since_minutes": 30,
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "count": 1,
  "events": [{
    "event_id": "evt_xxxxxxxxxx",
    "title": "事件标题",
    "summary": "结构化事件摘要",
    "event_family": "announcement",
    "horizon": "short",
    "event_time": "2026-08-08T23:52:10+08:00",
    "subject_ids": ["宁德时代"],
    "instruments_ready": true,
    "instrument_ids": ["cn:SZSE.300750"],
    "instrument_links": [{
      "instrument_id": "cn:SZSE.300750",
      "role": "direct",
      "direction": "positive",
      "impact_strength": 0.37,
      "reason": "事件与标的的关联原因"
    }]
  }]
}

顶层响应字段

events[]

instrument_links[]

5. 标的事件：GET /api/v1/instrument-events

按 instrument_id 查询指定时间范围内的相关事件。

查询参数

响应示例

{
  "instrument_id": "cn:SZSE.300750",
  "start_datetime": "2026-08-01T00:00:00+08:00",
  "end_datetime": "2026-08-08T00:00:00+08:00",
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "events": [{
    "event_id": "evt_xxxxxxxxxx",
    "title": "事件标题",
    "summary": "结构化事件摘要",
    "impact_label": "合同签署",
    "event_family": "announcement",
    "event_time": "2026-08-07T03:10:00+08:00",
    "relation_role": "direct",
    "relation_direction": "positive",
    "impact_strength": 0.37,
    "relation_reason": "事件与目标公司的关联原因",
    "mechanism_text": "事件影响标的的作用机制",
    "mechanism_scope": "company",
    "history_hit_rate": 0.67,
    "history_sample_size": 12,
    "related_instruments": [{
      "instrument_id": "hk:03750",
      "role": "direct",
      "direction": "positive",
      "impact_strength": 0.35,
      "reason": "同集团相关标的"
    }],
    "similar_events": [{
      "title": "历史相似事件",
      "similarity_score": 0.81,
      "event_date": "2025-11-01",
      "returns": {"ret_1d": 0.012, "ret_3d": 0.036}
    }]
  }]
}

顶层响应字段

events[]

related_instruments[]

similar_events[]

6. 容易误解的事件字段

6.1 instruments_ready（仅 recent-events）

含义：标的关联是否已经完成。新事件可能先出现在扫新结果里，标的列表稍后再补齐。

• true：可以读取 instrument_ids / instrument_links。
• false：事件已经可见，但标的列表可能仍为空，这是正常现象。
• 处理建议：稍后使用同一 event_id 再查询，或改用 instrument-events 按标的补查。

6.2 关系字段（relation_* / instrument_links / related_instruments）

这些字段回答“某个标的与事件是什么关系”：直接还是间接、影响倾向、关联强度及判断理由。

• 在 instrument-events 中，relation_* 只描述当前查询的标的。
• related_instruments 是同一事件下的其他相关标的。
• direction / impact_strength 是研究用标签，可用于筛选和排序，不要直接当作交易信号。

6.3 history_hit_rate / history_sample_size

history_hit_rate 表示历史相似情形中，当时的影响倾向与事后价格变化方向一致的比例；history_sample_size 是该比例参考的样本数。

• 样本数少于 5 时两者均为 null，不要将空值理解为 0。
• 这是历史对照统计，不是对未来结果的保证。
• 样本较少时应更谨慎解读，不要直接当作交易信号。

6.4 similar_events 与 returns

这些字段提供若干历史相似事件及其之后已能观察到的价格变化，用于对照研究。

• 只返回发生时间早于当前事件的相似事件。
• returns 中某个 N 日变化，只有在当前事件发生时该 N 日观察窗口已经结束时才会出现。
• 很新的事件上，similar_events 或 returns 为空是正常现象。
• 相似事件不返回其 event_id。
• returns 是历史价格变化对照，不要直接当作交易信号，也不要外推为未来表现。

6.6 event_time 与 event_date

7. 日线行情：GET /instrument-daily-bars

查询日线 OHLCV。当前覆盖 A 股与国内商品期货，对应市场收盘后更新。

查询参数

响应示例

{
  "instrument_id": "cn:SZSE.300750",
  "interval": "1d",
  "timezone": "Asia/Shanghai",
  "start_date": "2026-07-01",
  "end_date": "2026-08-08",
  "order": "asc",
  "page": 1,
  "page_size": 100,
  "has_more": false,
  "bars": [{
    "trade_date": "2026-07-01",
    "open": 198.46,
    "high": 205.21,
    "low": 194.37,
    "close": 202.63,
    "volume": 36451200
  }]
}

volume 在无可靠值时可能为 null。

8. 标的搜索：GET /instruments/search

按名称、代码、别名或部分 ID 查找标准 instrument_id。该接口需具备搜索权限的 Key（控制台创建的 Key 默认已包含）。本接口只做标的识别，不返回事件或行情。

查询参数

响应示例

{
  "query": "宁德时代",
  "count": 1,
  "results": [{
    "instrument_id": "cn:SZSE.300750",
    "zh": "宁德时代",
    "en": "CATL",
    "aliases": ["300750"]
  }]
}

空结果不是错误。若有多个候选，请结合市场与名称确认后使用返回的 instrument_id。

9. 分页与限流

• has_more=true 时请求下一页。
• 事件接口 page_size 默认 50、最大 100；日线默认 100、最大 400。
• 近期事件建议每 10–15 分钟轮询，时间窗略微重叠，并按 event_id 去重。

默认每分钟请求上限：/recent-events 60 次，/instrument-events 300 次，/instrument-daily-bars 120 次，/instruments/search 60 次。限制按账号和 API Key 同时检查，最终以响应头与 Dashboard 为准。

常用响应头：

10. 错误码

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_xxxxxxxxxx"
  }
}

建议仅重试 429、502、503，并记录 X-Request-Id。

11. 限制与边界

• 事件历史自 2025 年 6 月起。
• 最新事件常见端到端延迟约 5–15 分钟（约 90% 情况）。
• recent-events 单次最长 7 天；instrument-events 单次最长 90 天；日线单次最长 400 天。
• 日线当前覆盖 A 股与国内商品期货。
• 空结果不代表标的不存在，也不代表从未发生相关事件。

12. Python 示例

import os
import requests

response = requests.get(
    "https://api.luojilongxia.com/api/v1/instrument-events",
    headers={"X-API-Key": os.environ["LUOJILONGXIA_API_KEY"]},
    params={
        "instrument_id": "cn:SZSE.300750",
        "start_datetime": "2026-08-01T00:00:00+08:00",
        "end_datetime": "2026-08-08T00:00:00+08:00",
        "page": 1,
        "page_size": 20,
    },
    timeout=20,
)
response.raise_for_status()
for event in response.json()["events"]:
    print(event["event_time"], event["title"])

13. 获取帮助

反馈问题时请提供：接口路径、请求时间（含时区）、HTTP 状态码、错误 code、X-Request-Id 和脱敏参数。不要发送完整 API Key 或其他敏感凭证。

联系邮箱：contact@logicduo.com

更多资源：

• Agent Skill：https://luojilongxia.com/SKILL.md