API 文件

AI股探 API 文件

開放給外部程式直接呼叫的介面，僅有登入與 WebSocket 通知兩項。

Base URLhttp://localhost:3001

概覽

AI股探對外開放的使用者介面只有兩項：

登入

呼叫登入端點取得 JWT Token，用於建立 WebSocket 連線。

WebSocket 通知

帶入登入取得的 JWT Token 建立 Socket.IO 連線，接收屬於你帳號的規則觸發通知。

規則管理、帳號設定、通知管道綁定、AI 對話等其他功能，仍由伺服器提供並持續運作，但僅供官方網站的儀表板本身呼叫使用， 不開放作為外部程式可直接呼叫的公開 API。

認證方式

先呼叫登入端點取得 JWT Token，再將 Token 帶入 WebSocket 連線的認證欄位：

http
Authorization: Bearer <你的 JWT Token>

錯誤格式

所有錯誤回應均使用以下格式，HTTP 狀態碼反映錯誤類型（400、401、403、404、409、500）：

json
{ "error": "錯誤描述訊息" }

身份驗證

POST/api/auth/login

登入

驗證帳號密碼，回傳有效期 7 天的 JWT Token。此 Token 用於建立 WebSocket 連線以接收通知。

Request

json
{
  "username": "myuser",
  "password": "mypass123"
}

Response

json
{
  "token": "eyJhbGci...",
  "user": {
    "id": "clxxxxxxxx",
    "username": "myuser"
  }
}

WebSocket API

使用 Socket.IO v4 客戶端連線。必須在連線時帶入登入取得的 JWT Token，否則連線會被拒絕。

WSws://localhost:3001

建立連線

Token 驗證成功後自動加入 user:<id> 房間，即可接收 notification 事件。缺少或無效的 Token 會導致連線被拒絕。

JavaScript / TypeScript

typescript
import { io } from 'socket.io-client';

const TOKEN = 'eyJhbGci...'; // 登入取得的 JWT Token

const socket = io('http://localhost:3001', {
  auth: { token: `Bearer ${TOKEN}` },
  transports: ['websocket'],
});

socket.on('connect', () => {
  console.log('已連線，Socket ID:', socket.id);
});

socket.on('connect_error', (err) => {
  console.error('連線失敗（Token 缺失或無效）:', err.message);
});

Python

python
import socketio

sio = socketio.Client()
TOKEN = 'eyJhbGci...'

@sio.event
def connect():
    print('已連線')

sio.connect(
    'http://localhost:3001',
    auth={'token': f'Bearer {TOKEN}'},
    transports=['websocket']
)
sio.wait()
ON接收通知
notification 需要 JWT 認證

屬於你帳號的規則觸發通知，只有你能收到。

typescript
socket.on('notification', (data) => {
  /*
  {
    ruleId:      "clxxxxxxxx",
    ruleName:    "台積電突破均線",
    triggerId:   "clxxxxxxxx",
    symbol:      "2330",
    signal:      "BUY",
    price:       920,
    message:     "2330 股價突破20日均線",
    triggeredAt: "2026-07-01T10:30:00Z"
  }
  */
  console.log(`訊號：${data.signal} ${data.symbol} @ ${data.price}`);
});

事件一覽表

事件名稱方向說明是否需認證
notification接收帳號專屬規則觸發通知是

AI股探 API · Base URL: http://localhost:3001