--- name: use-luojilongxia-api description: Use the Luojilongxia API to retrieve structured financial-market events, instrument event timelines, and daily OHLCV bars for China A-shares and domestic commodity futures. --- # Use the Luojilongxia API Base URL: `https://api.luojilongxia.com/api/v1` Docs: `https://luojilongxia.com/docs` Auth header: `X-API-Key: lx_live__` Read the key from `LUOJILONGXIA_API_KEY` or another secret store. Never put it in source code, URLs, browser-side code, logs, chat, or git. If no key exists, ask the user to create one in the dashboard; do not ask them to paste the secret into chat. Use one key per server or deployment. A key permits two active outbound IPs by default; additional IPs within the 60-second window return `403 api_key_ip_conflict`. ## Instrument IDs Preserve IDs exactly. Common forms: - A-share: `cn:SSE.600519`, `cn:SZSE.300750` - HK: `hk:00700` - US: `us:TSLA` - China futures continuous: `cn:KQ.i@SHFE.au` - Index: `cn:idx.000300`, `us:idx.SPX` If the ID is unknown, call `GET /instruments/search?q=...` first. ## Endpoints ### `GET /api/v1/recent-events` Scan recent market-wide events. Max window 7 days. - `since_minutes`: optional, 1–10080, default 10 - `start_datetime` + `end_datetime`: optional pair that replaces `since_minutes` - `page`, `page_size`: page defaults to 1; page_size 1–100, default 50 Top-level response fields: | Field | Interpret as | | --- | --- | | `start_datetime` / `end_datetime` | Effective query window in Beijing time (UTC+8). For a relative query, `end_datetime` is approximately now. | | `since_minutes` | Requested relative window; `null` when absolute start/end times were used. | | `page` / `page_size` | Current 1-based page and requested page size. | | `has_more` | Continue paging when `true`; never treat one page as the complete result set. | | `count` | Number of events on this page, not a total count. | | `events` | Event objects described below. | Interpret each item in `events[]` as follows: | Field | Interpret as | | --- | --- | | `event_id` | Stable event identifier. Dedupe and merge repeated appearances by this field. | | `title` | Normalized event title, not necessarily an original news headline. | | `summary` | Structured summary, not full news text. | | `event_family` | Category such as `rating`, `earnings`, `industry_data`, or `policy`. | | `horizon` | Impact horizon. Treat a missing value as `short`. | | `event_time` | Time the event is considered to have appeared, usually near the earliest public information time; it is not the instrument-linking completion time. | | `subject_ids` | Mentioned entities such as companies or institutions; these are names/identifiers, not tradable instrument IDs. | | `instruments_ready` | Whether instrument linking is complete. Follow the rules below. | | `instrument_ids` | Linked instrument IDs. An empty array is normal while `instruments_ready=false`. | | `instrument_links` | Detailed per-instrument relation objects. | Each `instrument_links[]` item contains: - `instrument_id`: canonical ID such as `us:TSLA` or `cn:SSE.600519`. - `role`: `direct` or `indirect`. - `direction`: `positive`, `negative`, or `neutral`. Treat it as a research label, never a trading signal. - `impact_strength`: approximate 0–1 relation/impact strength. Use it only for research filtering or ranking, never as a trading signal. - `reason`: short explanation for manual verification. ### `GET /api/v1/instrument-events` Events for one instrument. Max window 90 days. Required: `instrument_id`, `start_datetime`, `end_datetime` Optional: `page`, `page_size` (1–100, default 50), `sort=first_seen_at|score` Top-level response fields: - `instrument_id`: queried instrument, identical to the request. - `start_datetime` / `end_datetime`: effective query window in Beijing time (UTC+8). - `page` / `page_size`: current 1-based page and requested page size. - `has_more`: continue paging when `true`. - `events`: related event objects described below. Interpret each item in `events[]` as follows: | Field | Interpret as | | --- | --- | | `event_id`, `title`, `summary`, `event_family` | Same semantics as `recent-events`; dedupe by `event_id`. | | `impact_label` | Short scan label such as “valuation pressure” or “data release”; use only for browsing/filtering, never as a trading signal. | | `event_time` | Main event time. This is the only time field for the main event. | | `relation_role` | Whether the queried instrument is `direct` or `indirect`. | | `relation_direction` | `positive`, `negative`, or `neutral` for the queried instrument; never treat it as a trading signal. | | `impact_strength` | Approximate 0–1 strength for this instrument-event pair, not one global score for the event; never treat it as a trading signal. | | `relation_reason` | Why the queried instrument is related; use it for manual verification. | | `mechanism_text` | Explanatory impact mechanism; may be `null` and is not a trading signal. | | `mechanism_scope` | Scope such as company or industry; may be `null`. | | `history_hit_rate` / `history_sample_size` | Historical directional-agreement rate and its sample count. Both are `null` when fewer than 5 samples exist. | | `related_instruments` | Other instruments linked to the same event. | | `similar_events` | Earlier similar events for point-in-time historical comparison. | Treat each `related_instruments[]` item like an `instrument_links[]` item: read `instrument_id`, `role`, `direction`, `impact_strength`, and `reason` with the same cautions. Each `similar_events[]` item contains: - `title`: similar event title; no `event_id` is returned. - `similarity_score`: similarity only; a larger value means more similar. - `event_date`: date only, formatted `YYYY-MM-DD`. - `returns`: observed historical changes such as `ret_1d`, `ret_3d`, or `ret_7d`; fields may be absent for recent main events. Never treat these returns as a forecast or trading signal. ## Event interpretation rules ### Instrument readiness - Treat an event as valid even when `instruments_ready=false`. - Read `instrument_ids` and `instrument_links` when readiness is `true`. - Accept empty instrument arrays while readiness is `false`; retry the same `event_id` later or query `instrument-events` by instrument. ### Relation fields - Interpret `relation_*` in `instrument-events` as applying only to the queried instrument. - Interpret `related_instruments` as other instruments related to the same event. - Use `direction` and `impact_strength` only for research filtering/ranking, never as trading signals. ### Historical hit rate - Interpret `history_hit_rate` as the historical share of similar cases where the labeled direction agreed with the later price direction. - Read it together with `history_sample_size`. When the sample count is below 5, both values are `null`; never convert `null` to zero. - Treat the statistic as historical context, not a guarantee of future performance or a trading signal. ### Similar events and returns - Expect only similar events that occurred before the main event. - Expect an N-day return only when that N-day observation window had already completed by the main event time. - Accept empty `similar_events` or `returns` for recent events. - Do not expect similar-event `event_id` values. - Use returns only as historical comparisons; never extrapolate them as future performance. ### Event time versus event date - Read main-event `event_time` as a timestamp in Beijing time (UTC+8). - Read similar-event `event_date` as a date only. ### `GET /instrument-daily-bars` Daily OHLCV for China A-shares and domestic commodity futures. Updates after market close. Max window 400 days. Required: `instrument_id`, `start_date`, `end_date` Optional: `page`, `page_size` (1–400, default 100), `order=asc|desc` Bars include `trade_date`, `open`, `high`, `low`, `close`, `volume` (`volume` may be null). ### `GET /instruments/search` Resolve name/code/alias to `instrument_id`. Keys created in the dashboard include search permission by default. - `q`: required, 1–100 chars - `limit`: optional, 1–50, default 10 Empty results are not API errors. This endpoint does not return events or bars. ## Pagination, rate limits, errors - Continue while `has_more=true`. - Poll recent events every 10–15 minutes with a slightly overlapping window; dedupe by `event_id`. - Default per-minute limits: recent-events 60, instrument-events 300, daily-bars 120, search 60. Limits are checked by both account and API key; trust response headers and the dashboard. Useful headers: `X-Request-Id`, `X-Subscription-Ends-At`, `X-RateLimit-Limit`, `X-RateLimit-Reset`, `Retry-After`. Error shape: ```json {"error":{"code":"rate_limited","message":"Too many requests","request_id":"req_xxxxxxxxxx"}} ``` - `400 invalid_request`: fix parameters - `401 unauthorized`: configure a valid key - `402 subscription_required`: subscribe or renew in the dashboard - `403 insufficient_scope`: key lacks endpoint permission - `403 api_key_ip_conflict`: use separate keys per deployment; obey `Retry-After` - `429 rate_limited`: obey `Retry-After` - `502 upstream_unavailable` / `503 risk_control_unavailable`: retry later Retry only 429, 502, and 503. ## Limits - Event history starts June 2025. - Latest-event end-to-end latency is commonly about 5–15 minutes (about 90% of cases). - Windows: recent-events 7 days, instrument-events 90 days, daily-bars 400 days. - An empty result does not prove that an instrument or event does not exist.