feat(api): Add documentation for policy-triggered server push functionality

The API documentation for strategy triggering (server push - strategy triggered) has been added, Including JSON-RPC response format, parameter descriptions, field definitions, and usage examples.
2026-05-29 15:03:05 +08:00
parent f20d81ce4e
commit 6cbbd7412f
4 changed files with 252 additions and 0 deletions
@@ -401,6 +401,69 @@ For news with AI analysis (if subscribed):
 }
 ```

+### Server Push - Strategy Triggered
+
+> **Requires Max subscription.** Create and manage your strategies at [https://www.newsliquid.com/strategy](https://www.newsliquid.com/strategy).
+
+When a user-defined strategy is triggered (e.g., price alert, keyword match), the server pushes:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "strategy.triggered",
+  "params": {
+    "id": 1234567890,
+    "newsType": "strategy",
+    "engineType": "market",
+    "text": "BTC funding rate 0.15%",
+    "link": "",
+    "source": "binance",
+    "description": "{...}",
+    "coins": [
+      {
+        "symbol": "BTC",
+        "market_type": "cex"
+      }
+    ],
+    "ts": "2025-01-15T08:30:00Z",
+    "strategy": {
+      "id": 42,
+      "name": "BTC Funding Rate Alert",
+      "sourceType": "market",
+      "soundId": "alert-1",
+      "bgColor": "#FF6B35",
+      "metrics": {
+        "funding_rate_high": {
+          "value": 0.15,
+          "unit": "%"
+        }
+      }
+    },
+    "aiRating": {
+      "score": 85
+    }
+  }
+}
+```
+
+**Strategy Params Fields**:
+- `id`: News/event ID
+- `engineType`: Source engine type (`market`, `news`, `onchain`)
+- `text`: Human-readable event description
+- `coins`: Related coins
+- `ts`: Event timestamp
+- `strategy.id`: User strategy ID
+- `strategy.name`: Strategy name
+- `strategy.sourceType`: Strategy source type
+- `strategy.soundId`: Notification sound ID
+- `strategy.bgColor`: Notification background color
+- `strategy.metrics`: Triggered metric values with units
+- `aiRating` (optional): Present when the news has an AI score. Contains:
+  - `score`: 0-100 impact score
+- `relatedAddress` (optional): Related wallet address if applicable
+
+**Note**: Strategy triggered events are pushed per-user via NATS. No explicit subscription is required — events are automatically delivered to the connected user who owns the strategy.
+
 **Note**: Each coin in the `coins` array now includes individual AI ratings:
 - `score`: 0-100 impact score for this specific coin
 - `signal`: `long` / `short` / `neutral` for this coin
@@ -408,6 +408,69 @@ AI 分析付きニュース（購読している場合）：

 トップレベルの `aiRating.score` は全コイン中の最高スコアを表します。

+### サーバープッシュ - ストラテジートリガー
+
+> **Max サブスクリプションが必要です。** [https://www.newsliquid.com/strategy](https://www.newsliquid.com/strategy) でストラテジーを作成・管理できます。
+
+ユーザー定義のストラテジーがトリガーされた場合（例：価格アラート、キーワードマッチ）、サーバーがプッシュします：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "strategy.triggered",
+  "params": {
+    "id": 1234567890,
+    "newsType": "strategy",
+    "engineType": "market",
+    "text": "BTC ファンディングレート 0.15%",
+    "link": "",
+    "source": "binance",
+    "description": "{...}",
+    "coins": [
+      {
+        "symbol": "BTC",
+        "market_type": "cex"
+      }
+    ],
+    "ts": "2025-01-15T08:30:00Z",
+    "strategy": {
+      "id": 42,
+      "name": "BTC ファンディングレートアラート",
+      "sourceType": "market",
+      "soundId": "alert-1",
+      "bgColor": "#FF6B35",
+      "metrics": {
+        "funding_rate_high": {
+          "value": 0.15,
+          "unit": "%"
+        }
+      }
+    },
+    "aiRating": {
+      "score": 85
+    }
+  }
+}
+```
+
+**ストラテジープッシュフィールド説明**：
+- `id`：ニュース/イベント ID
+- `engineType`：ソースエンジンタイプ（`market`、`news`、`onchain`）
+- `text`：イベントの説明
+- `coins`：関連コイン
+- `ts`：イベントタイムスタンプ
+- `strategy.id`：ユーザーストラテジー ID
+- `strategy.name`：ストラテジー名
+- `strategy.sourceType`：ストラテジーソースタイプ
+- `strategy.soundId`：通知サウンド ID
+- `strategy.bgColor`：通知背景色
+- `strategy.metrics`：トリガーされた指標値と単位
+- `aiRating`（オプション）：ニュースに AI スコアがある場合に存在：
+  - `score`：影響スコア（0-100）
+- `relatedAddress`（オプション）：関連ウォレットアドレス
+
+**注意**：ストラテジートリガーイベントは NATS を通じてユーザーごとにプッシュされます。追加のサブスクリプションは不要で、接続後に自動的にそのユーザーのストラテジーイベントを受信します。
+
 ---

 ## データ構造
@@ -408,6 +408,69 @@ AI 분석이 있는 뉴스 (구독한 경우):

 최상위 `aiRating.score`는 모든 코인 중 최고 점수를 나타냅니다.

+### 서버 푸시 - 전략 트리거
+
+> **Max 구독이 필요합니다.** [https://www.newsliquid.com/strategy](https://www.newsliquid.com/strategy)에서 전략을 생성하고 관리하세요.
+
+사용자 정의 전략이 트리거되면(예: 가격 알림, 키워드 매칭) 서버가 푸시합니다:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "strategy.triggered",
+  "params": {
+    "id": 1234567890,
+    "newsType": "strategy",
+    "engineType": "market",
+    "text": "BTC 펀딩비율 0.15%",
+    "link": "",
+    "source": "binance",
+    "description": "{...}",
+    "coins": [
+      {
+        "symbol": "BTC",
+        "market_type": "cex"
+      }
+    ],
+    "ts": "2025-01-15T08:30:00Z",
+    "strategy": {
+      "id": 42,
+      "name": "BTC 펀딩비율 알림",
+      "sourceType": "market",
+      "soundId": "alert-1",
+      "bgColor": "#FF6B35",
+      "metrics": {
+        "funding_rate_high": {
+          "value": 0.15,
+          "unit": "%"
+        }
+      }
+    },
+    "aiRating": {
+      "score": 85
+    }
+  }
+}
+```
+
+**전략 푸시 필드 설명**:
+- `id`: 뉴스/이벤트 ID
+- `engineType`: 소스 엔진 유형 (`market`, `news`, `onchain`)
+- `text`: 이벤트 설명
+- `coins`: 관련 코인
+- `ts`: 이벤트 타임스탬프
+- `strategy.id`: 사용자 전략 ID
+- `strategy.name`: 전략 이름
+- `strategy.sourceType`: 전략 소스 유형
+- `strategy.soundId`: 알림 사운드 ID
+- `strategy.bgColor`: 알림 배경색
+- `strategy.metrics`: 트리거된 지표 값 및 단위
+- `aiRating` (선택): 뉴스에 AI 점수가 있을 때 존재:
+  - `score`: 영향력 점수 (0-100)
+- `relatedAddress` (선택): 관련 지갑 주소
+
+**참고**: 전략 트리거 이벤트는 NATS를 통해 사용자별로 푸시됩니다. 별도의 구독이 필요 없으며, 연결 후 해당 사용자의 전략 이벤트를 자동으로 수신합니다.
+
 ---

 ## 데이터 구조
@@ -408,6 +408,69 @@ $env:OPENNEWS_TOKEN = "<your-token>"

 顶层 `aiRating.score` 代表所有币种中的最高分。

+### 服务器推送 - 策略命中
+
+> **需要 Max 订阅套餐。** 在 [https://www.newsliquid.com/strategy](https://www.newsliquid.com/strategy) 创建和管理您的策略。
+
+当用户自定义策略被触发时（如价格预警、关键词匹配），服务器推送：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "strategy.triggered",
+  "params": {
+    "id": 1234567890,
+    "newsType": "strategy",
+    "engineType": "market",
+    "text": "BTC 资金费率 0.15%",
+    "link": "",
+    "source": "binance",
+    "description": "{...}",
+    "coins": [
+      {
+        "symbol": "BTC",
+        "market_type": "cex"
+      }
+    ],
+    "ts": "2025-01-15T08:30:00Z",
+    "strategy": {
+      "id": 42,
+      "name": "BTC 资金费率预警",
+      "sourceType": "market",
+      "soundId": "alert-1",
+      "bgColor": "#FF6B35",
+      "metrics": {
+        "funding_rate_high": {
+          "value": 0.15,
+          "unit": "%"
+        }
+      }
+    },
+    "aiRating": {
+      "score": 85
+    }
+  }
+}
+```
+
+**策略推送字段说明**：
+- `id`：新闻/事件 ID
+- `engineType`：来源引擎类型（`market`、`news`、`onchain`）
+- `text`：可读的事件描述
+- `coins`：相关币种
+- `ts`：事件时间戳
+- `strategy.id`：用户策略 ID
+- `strategy.name`：策略名称
+- `strategy.sourceType`：策略来源类型
+- `strategy.soundId`：通知音效 ID
+- `strategy.bgColor`：通知背景色
+- `strategy.metrics`：触发的指标值及单位
+- `aiRating`（可选）：当新闻有 AI 评分时存在，包含：
+  - `score`：影响力评分（0-100）
+- `relatedAddress`（可选）：相关钱包地址
+
+**注意**：策略命中事件通过 NATS 按用户推送，无需额外订阅，连接后自动接收属于该用户的策略事件。
+
 ---

 ## 数据结构