SFI External API — Algo Trading

0 Luồng dữ liệu — đọc trước

API có đúng hai đường ra. REST trả ảnh chụp: trạng thái hiện tại của thẻ, vị thế, lịch sử — app gọi khi cần. Stream đẩy sự kiện: mỗi lần có gì thay đổi, server gửi ngay một gói nhỏ nói “cái gì vừa đổi”. App ghép hai thứ: mở app thì lấy ảnh chụp một lần, từ đó chỉ sửa màn hình theo sự kiện. Không phải gọi lại REST liên tục.

Vòng đời của app — năm bước

1. Mở app: gọi GET /v1/products (thẻ, kèm hỗ trợ/kháng cự), GET /v1/positions (vị thế đang mở, kèm khối copy), GET /v1/trades (lịch sử, theo trang). Vẽ màn hình.
2. Mở một kết nối stream — SSE /stream/signals hoặc WebSocket /ws/signals ở algo-socket.sfi.com.vn — và giữ nó suốt lúc app mở.
3. Mỗi sự kiện tới: tra bảng dưới, sửa đúng một chỗ trên màn hình. Lưu id của sự kiện cuối cùng đã xử lý.
4. Mất mạng rồi nối lại: mở lại stream kèm ?since_id=<id cuối> — server phát bù mọi sự kiện đã lỡ rồi chạy tiếp realtime. Không còn id cuối, hoặc app tắt quá 7 ngày → quay lại bước 1.
5. Thông báo đẩy không làm trong app: server thông báo của bên app giữ một kết nối stream riêng, chạy 24/7, và đẩy push tới điện thoại — mục 12.

Sự kiện tới → app sửa gì

1 Tóm tắt và phạm vi

Trên một VPS riêng có 10 engine giao dịch tự động chạy liên tục — bạc, đồng, bạch kim, ngô, đậu tương, dầu đậu tương, khô đậu tương, lúa mì, đường #11, cà phê Arabica (bạc có hai thẻ — hợp đồng đầy đủ và mini — nên app thấy 11 thẻ) — và một bảng vận hành hiển thị trạng thái của chúng. API này mang đúng những gì bảng đó đang hiển thị ra cho app, và không kèm một quyền điều khiển nào.

Hai bên: Algo chạy dịch vụ API ngay trên VPS — algo-api (REST) và algo-socket (stream) trỏ thẳng về VPS qua tunnel Cloudflare do IT quản lý, không qua dịch vụ trung gian nào; app vẽ màn hình và làm nút copy lệnh. Người dùng cuối chỉ ở trên app SFI Trade — đây là bên tiêu thụ duy nhất của API.

Những gì API không mang

2 Từ bảng vận hành sang app

Mỗi khối trên bảng đang chạy tương ứng với một phần của API. Số trên app sẽ khớp số trên bảng vì hai bên đọc cùng một lớp dữ liệu.

1 2 3

1Tín hiệu toàn thị trường

GET /v1/products → items[]: mã hợp đồng contract, trạng thái state_label, win_rate, số vị thế open_positions. Hỗ trợ/kháng cự lấy ngay trên mỗi thẻ: items[].zones v1.2 — in vùng đầu mỗi phía dạng lo–hi (mục 11).

Nút copy lệnh nằm đúng chỗ bảng đã dành sẵn: ô “Sao chép” ở mỗi hàng, chỉ bật khi sản phẩm đang có vị thế.

2Vị thế mở

GET /v1/positions và các sự kiện position_*: hợp đồng, chiều Mua/Bán, giá vào, SL kèm nhãn BE khi đã về hoà vốn, TP hoặc “—”, giờ vào, lãi/lỗ tạm tính, và object copy cho nút copy lệnh.

3Lịch sử tín hiệu

GET /v1/trades và sự kiện position_closed: hợp đồng, chiều, giá mở, giá đóng, hiệu suất (pnl_usd), thời gian đóng. Một quyết định của engine bạc sinh lệnh ở cả hai thẻ — short ngày 14/09: SIZ26 −$5.325,00, QIZ26 −$2.662,50.

Trang chi tiết một sản phẩm

App lấy gì

• một lần /v1/products, /v1/positions khi mở màn hình (mục 0);
• một kết nối stream cho mọi thay đổi sau đó — kể cả thẻ mới, thẻ bị gỡ và vùng hỗ trợ/kháng cự;
• /v1/trades theo trang khi người dùng cuộn lịch sử;
• nút copy lệnh đọc object copy VPS đã tính sẵn.

3 Hai loại dữ liệu · danh mục endpoint

Toàn bộ API chỉ có hai loại dữ liệu. Phân biệt được hai loại này thì phần còn lại đọc rất nhanh.

Danh mục endpoint

4 REST API

4.1 Danh sách thẻ sản phẩm

curl -H "X-API-Key: <key>" \
  "https://algo-api.sfi.com.vn/v1/products"

Response 200 — rút gọn còn 3 thẻ

{
  "snapshot_at": "2026-09-22T02:52:16Z",
  "service": {
    "state": "binh_thuong",
    "label": null,
    "since": null,
    "version": "1.3",
    "data_at": "2026-09-22T02:52:16Z"
  },
  "items": [
    {
      "code": "SI",
      "name": "Bạc",
      "category": "Kim loại",
      "contract": "SIZ26",
      "cqg_symbol": "SIEZ26",
      "cqg_root": "SIE",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 50,
      "win_rate": 0.6,
      "open_positions": 0
    },
    {
      "code": "QI",
      "name": "Bạc mini",
      "category": "Kim loại",
      "contract": "QIZ26",
      "cqg_symbol": "MQIZ26",
      "cqg_root": "MQI",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 63,
      "win_rate": 0.619,
      "open_positions": 0
    },
    {
      "code": "HG",
      "name": "Đồng",
      "category": "Kim loại",
      "contract": "HGZ26",
      "cqg_symbol": "CPEZ26",
      "cqg_root": "CPE",
      "state": "wait_buy",
      "state_label": "Chờ mua",
      "trend": "tang",
      "trades": 77,
      "win_rate": 0.519,
      "open_positions": 0
    }
  ],
  "count": 9
}

{
  "snapshot_at": "2026-09-22T02:52:16Z",
  "service": {
    "state": "binh_thuong",
    "label": null,
    "since": null,
    "version": "1.3",
    "data_at": "2026-09-22T02:52:16Z"
  },
  "items": [
    {
      "code": "SI",
      "name": "Bạc",
      "category": "Kim loại",
      "contract": "SIZ26",
      "cqg_symbol": "SIEZ26",
      "cqg_root": "SIE",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 50,
      "win_rate": 0.6,
      "open_positions": 0
    },
    {
      "code": "QI",
      "name": "Bạc mini",
      "category": "Kim loại",
      "contract": "QIZ26",
      "cqg_symbol": "MQIZ26",
      "cqg_root": "MQI",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 63,
      "win_rate": 0.619,
      "open_positions": 0
    },
    {
      "code": "HG",
      "name": "Đồng",
      "category": "Kim loại",
      "contract": "HGZ26",
      "cqg_symbol": "CPEZ26",
      "cqg_root": "CPE",
      "state": "wait_buy",
      "state_label": "Chờ mua",
      "trend": "tang",
      "trades": 77,
      "win_rate": 0.519,
      "open_positions": 0
    },
    {
      "code": "PL",
      "name": "Bạch kim",
      "category": "Kim loại",
      "contract": "PLV26",
      "cqg_symbol": "PLEV26",
      "cqg_root": "PLE",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 32,
      "win_rate": 0.562,
      "open_positions": 0
    },
    {
      "code": "ZC",
      "name": "Ngô",
      "category": "Nông sản",
      "contract": "ZCZ26",
      "cqg_symbol": "ZCEZ26",
      "cqg_root": "ZCE",
      "state": "watching",
      "state_label": "Đang theo dõi",
      "trend": "di_ngang",
      "trades": 15,
      "win_rate": 0.267,
      "open_positions": 0
    },
    {
      "code": "ZS",
      "name": "Đậu tương",
      "category": "Nông sản",
      "contract": "ZSX26",
      "cqg_symbol": "ZSEX26",
      "cqg_root": "ZSE",
      "state": "wait_buy",
      "state_label": "Chờ mua",
      "trend": "tang",
      "trades": 20,
      "win_rate": 0.8,
      "open_positions": 0
    },
    {
      "code": "ZL",
      "name": "Dầu đậu tương",
      "category": "Nông sản",
      "contract": "ZLZ26",
      "cqg_symbol": "ZLEZ26",
      "cqg_root": "ZLE",
      "state": "wait_sell",
      "state_label": "Chờ bán",
      "trend": "giam",
      "trades": 24,
      "win_rate": 0.625,
      "open_positions": 0
    },
    {
      "code": "ZM",
      "name": "Khô đậu tương",
      "category": "Nông sản",
      "contract": "ZMZ26",
      "cqg_symbol": "ZMEZ26",
      "cqg_root": "ZME",
      "state": "wait_buy",
      "state_label": "Chờ mua",
      "trend": "tang",
      "trades": 34,
      "win_rate": 0.559,
      "open_positions": 0
    },
    {
      "code": "ZW",
      "name": "Lúa mì",
      "category": "Nông sản",
      "contract": "ZWZ26",
      "cqg_symbol": "ZWAZ26",
      "cqg_root": "ZWA",
      "state": "wait_sell",
      "state_label": "Chờ bán",
      "trend": "giam",
      "trades": 52,
      "win_rate": 0.308,
      "open_positions": 0
    }
  ],
  "count": 9
}

Field cấp ngoài

4.2 Chi tiết một thẻ

curl -H "X-API-Key: <key>" \
  "https://algo-api.sfi.com.vn/v1/products/SI"

Response 200 — bạc, số thật

{
  "code": "SI",
  "name": "Bạc",
  "category": "Kim loại",
  "contract": "SIZ26",
  "cqg_symbol": "SIEZ26",
  "cqg_root": "SIE",
  "state": "watching",
  "state_label": "Đang theo dõi",
  "trend": "di_ngang",
  "trades": 50,
  "win_rate": 0.6,
  "open_positions": 0,
  "zones": {
    "support": [
      {
        "price": 66.2,
        "lo": 65.82,
        "hi": 66.2
      },
      {
        "price": 65.465,
        "lo": 65.06,
        "hi": 65.465
      }
    ],
    "resistance": [
      {
        "price": 67.035,
        "lo": 67.035,
        "hi": 67.485
      },
      {
        "price": 67.685,
        "lo": 67.685,
        "hi": 68.08
      }
    ],
    "support_note": null,
    "resistance_note": null
  },
  "positions": [],
  "recent_trades": [
    {
      "id": 1041,
      "key": "SI:short:2026-09-16T18:15:00Z",
      "product": "SI",
      "contract": "SIZ26",
      "side": "short",
      "quantity": 1,
      "entry_time": "2026-09-16T18:15:00Z",
      "entry_price": 64.13,
      "exit_time": "2026-09-16T18:45:00Z",
      "exit_price": 64.645,
      "pnl_usd": -2575.01
    },
    {
      "id": 1017,
      "key": "SI:short:2026-09-14T09:30:00Z",
      "product": "SI",
      "contract": "SIZ26",
      "side": "short",
      "quantity": 1,
      "entry_time": "2026-09-14T09:30:00Z",
      "entry_price": 63.05,
      "exit_time": "2026-09-14T16:47:08Z",
      "exit_price": 64.115,
      "pnl_usd": -5325.0
    }
  ]
}

4.3 Vị thế đang mở

curl -H "Authorization: Bearer <key>" \
  "https://algo-api.sfi.com.vn/v1/positions?products=SI,QI"

Response 200 — minh hoạ

{
  "snapshot_at": "2026-09-14T10:05:00Z",
  "service": {
    "state": "binh_thuong",
    "label": null,
    "since": null,
    "version": "1.3",
    "data_at": "2026-09-22T02:52:16Z"
  },
  "items": [
    {
      "id": "SI:short:2026-09-14T09:30:00Z",
      "product": "SI",
      "contract": "SIZ26",
      "side": "short",
      "entry_time": "2026-09-14T09:30:00Z",
      "entry_price": 63.05,
      "stop_price": 64.115,
      "take_profit": null,
      "breakeven_locked": false,
      "quantity": 1,
      "unrealized_pnl_usd": -1000.0,
      "pnl_basis": "live",
      "copy": {
        "contract": "SIZ26",
        "cqg_symbol": "SIEZ26",
        "side": "sell",
        "quantity": 1,
        "entry_ref": 63.05,
        "stop_price": 64.115,
        "take_profit": null,
        "tick_size": 0.005
      }
    },
    {
      "id": "QI:short:2026-09-14T09:30:00Z",
      "product": "QI",
      "contract": "QIZ26",
      "side": "short",
      "entry_time": "2026-09-14T09:30:00Z",
      "entry_price": 63.05,
      "stop_price": 64.115,
      "take_profit": null,
      "breakeven_locked": false,
      "quantity": 1,
      "unrealized_pnl_usd": -500.0,
      "pnl_basis": "live",
      "copy": {
        "contract": "QIZ26",
        "cqg_symbol": "MQIZ26",
        "side": "sell",
        "quantity": 1,
        "entry_ref": 63.05,
        "stop_price": 64.125,
        "take_profit": null,
        "tick_size": 0.0125
      }
    }
  ],
  "count": 2
}

4.4 Lịch sử lệnh

App hiện đúng như bảng vận hành: mã hợp đồng, chiều lệnh, giá mở, giá đóng, hiệu suất và thời gian đóng. Bảng không hiện lệnh thoát bằng gì, nên API cũng không trả lý do thoát.

Ví dụ

# 20 lệnh đóng gần nhất, mọi sản phẩm — cũng là cách poll
GET /v1/trades?limit=20

# Poll vòng sau: chỉ những lệnh mới hơn con trỏ đã lưu
GET /v1/trades?since_id=1043

# Lệnh bạc (thẻ SI và thẻ QI) trong tháng 9
GET /v1/trades?products=SI,QI&from=2026-09-01&to=2026-09-30

# Lật tiếp về quá khứ: dùng next_before_id của trang trước
GET /v1/trades?limit=20&before_id=1041

Response 200 — ba lệnh thật, id minh hoạ

{
  "items": [
    {
      "id": 1043,
      "key": "ZL:short:2026-08-10T11:45:00Z",
      "product": "ZL",
      "contract": "ZLQ26",
      "side": "short",
      "quantity": 1,
      "entry_time": "2026-08-10T11:45:00Z",
      "entry_price": null,
      "exit_time": "2026-08-10T12:15:00Z",
      "exit_price": null,
      "pnl_usd": -114.0
    },
    {
      "id": 1042,
      "key": "QI:short:2026-09-14T09:30:00Z",
      "product": "QI",
      "contract": "QIZ26",
      "side": "short",
      "quantity": 1,
      "entry_time": "2026-09-14T09:30:00Z",
      "entry_price": 63.05,
      "exit_time": "2026-09-14T16:47:08Z",
      "exit_price": 64.115,
      "pnl_usd": -2662.5
    },
    {
      "id": 1041,
      "key": "SI:short:2026-09-14T09:30:00Z",
      "product": "SI",
      "contract": "SIZ26",
      "side": "short",
      "quantity": 1,
      "entry_time": "2026-09-14T09:30:00Z",
      "entry_price": 63.05,
      "exit_time": "2026-09-14T16:47:08Z",
      "exit_price": 64.115,
      "pnl_usd": -5325.0
    }
  ],
  "next_since_id": 1043,
  "next_before_id": 1041,
  "count": 3
}

4.5 Đọc bù sự kiện

Stream tự nối lại nhưng không tự phát lại phần đã lỡ. Hai cách bù: mở stream kèm ?since_id= v1.2 (mục 5.1), hoặc sau mỗi lần nối lại gọi endpoint này từ id cuối cùng đã xử lý. Sự kiện được giữ 7 ngày.

# Vừa nối lại stream: đọc bù mọi sự kiện sau id cuối đã xử lý
GET /v1/events?since_id=58213

# Chỉ sự kiện của bạc
GET /v1/events?since_id=58213&products=SI,QI

Response 200

{
  "items": [
    {
      "id": 58190,
      "event": "position_opened",
      "at": "2026-09-14T09:30:01Z",
      "product": "SI",
      "data": {
        "id": "SI:short:2026-09-14T09:30:00Z",
        "product": "SI",
        "contract": "SIZ26",
        "side": "short",
        "entry_time": "2026-09-14T09:30:00Z",
        "entry_price": 63.05,
        "stop_price": 64.115,
        "take_profit": null,
        "breakeven_locked": false,
        "quantity": 1,
        "unrealized_pnl_usd": 0.0,
        "pnl_basis": "live",
        "copy": {
          "contract": "SIZ26",
          "cqg_symbol": "SIEZ26",
          "side": "sell",
          "quantity": 1,
          "entry_ref": 63.05,
          "stop_price": 64.115,
          "take_profit": null,
          "tick_size": 0.005
        }
      }
    },
    {
      "id": 58213,
      "event": "position_closed",
      "at": "2026-09-14T16:47:08Z",
      "product": "SI",
      "data": {
        "position_id": "SI:short:2026-09-14T09:30:00Z",
        "trade": {
          "id": 1041,
          "key": "SI:short:2026-09-14T09:30:00Z",
          "product": "SI",
          "contract": "SIZ26",
          "side": "short",
          "quantity": 1,
          "entry_time": "2026-09-14T09:30:00Z",
          "entry_price": 63.05,
          "exit_time": "2026-09-14T16:47:08Z",
          "exit_price": 64.115,
          "pnl_usd": -5325.0
        }
      }
    }
  ],
  "next_since_id": 58213,
  "count": 2
}

5 Realtime stream

Stream đẩy sự kiện ngay khi VPS phát hiện. Stream không có tiền tố phiên bản; nội dung sự kiện theo đúng đối tượng Event.

Xác thực

Trình duyệt không gắn được header vào EventSource hay WebSocket, nên stream nhận thêm ?key=<key>. Key thiếu, sai, đã thu hồi hoặc không có scope algo:stream: SSE trả 401, WebSocket đóng với mã 4401.

5.1 Server-Sent Events

Tham số products lọc theo mã thẻ, giống REST. v1.2: tham số since_id — server phát bù ngay trong kết nối mọi sự kiện có id lớn hơn (tối đa 1.000), rồi chạy realtime. Dùng được cho cả SSE lẫn WebSocket, thay cho bước gọi /v1/events lúc nối lại.

Khung sự kiện trên dây — lệnh thật 14/09, rút gọn

: connected
retry: 3000

data: {"id": 58213, "event": "position_closed", "at": "2026-09-14T16:47:08Z", "product": "SI", "data": {"position_id": "SI:short:2026-09-14T09:30:00Z", "trade": {"id": 1041, "side": "short", "entry_price": 63.05, "exit_price": 64.115, "pnl_usd": -5325.0}}}

: keepalive

Ví dụ — curl

curl -N -H "Authorization: Bearer <key>" \
  "https://algo-socket.sfi.com.vn/stream/signals?products=SI,QI"

Ví dụ — JavaScript

const API = 'https://algo-api.sfi.com.vn';
const SOCKET = 'https://algo-socket.sfi.com.vn';
const daXuLy = new Set();                  // giao ít nhất một lần → tự khử trùng theo id
let idCuoi = Number(localStorage.getItem('algo_id_cuoi') || 0);

function xuLy(ev) {
  if (daXuLy.has(ev.id)) return;
  daXuLy.add(ev.id);
  idCuoi = Math.max(idCuoi, ev.id);
  localStorage.setItem('algo_id_cuoi', idCuoi);
  switch (ev.event) {
    case 'position_opened':  veViThe(ev.data); break;                     // có lệnh → copy được ngay
    case 'position_updated': veViThe(ev.data); baoNguoiDaCopy(ev); break; // kéo SL, BE, sửa giá vào
    case 'position_closed':  xoaViThe(ev.data.position_id);
                               if (ev.data.trade) themLenh(ev.data.trade); break;  // v1.2: null = vào sớm bị huỷ
    case 'trade_corrected':  suaLenh(ev.data.trade); break;
    case 'product_unavailable': tamNgungThe(ev.data.code, ev.data.unavailable); break; // mờ thẻ, tắt copy thẻ đó
    case 'product_available':   thayThe(ev.data); break;                  // thẻ đầy đủ, app thay nguyên thẻ
    case 'product_updated':   thayThe(ev.data); break;                  // v1.1: thẻ đổi trạng thái, xu hướng, winrate, vùng…
    case 'product_added':     themThe(ev.data); break;                  // v1.2: thẻ mới — ProductCard đầy đủ
    case 'product_removed':   goThe(ev.data.code); break;               // v1.2: gỡ thẻ + vị thế + lịch sử
    case 'service_changed':  datTrangThaiDichVu(ev.data); break;          // màn hình bảo trì bật/tắt
  }
}

async function docBu() {                   // EventSource tự nối lại nhưng KHÔNG bù phần đã lỡ
  const r = await fetch(`${API}/v1/events?since_id=${idCuoi}`, { headers: { 'X-API-Key': KEY } });
  (await r.json()).items.forEach(xuLy);
}

const es = new EventSource(`${SOCKET}/stream/signals?key=${KEY}`);
es.onopen = docBu;
es.onmessage = (e) => xuLy(JSON.parse(e.data));

5.2 WebSocket

Mã đóng kết nối

Ví dụ — JavaScript

function noi() {
  const ws = new WebSocket(`wss://algo-socket.sfi.com.vn/ws/signals?key=${KEY}`);
  ws.onopen = docBu;                        // cùng hàm đọc bù như SSE
  ws.onmessage = (e) => {
    const m = JSON.parse(e.data);
    if (m.event === 'ping') return;         // keepalive 20 giây
    xuLy(m);
  };
  ws.onclose = (e) => {
    if (e.code === 4401) return;            // key sai / thu hồi — nối lại vô nghĩa
    setTimeout(noi, backoff());             // 1013 và mọi trường hợp khác
  };
}
noi();

5.3 Các loại sự kiện

App gặp event lạ thì bỏ qua — VPS có thể thêm loại sự kiện mới mà không làm app cũ lỗi.

Minh hoạ — có lệnh là copy được

{
  "id": 58190,
  "event": "position_opened",
  "at": "2026-09-14T09:30:01Z",
  "product": "SI",
  "data": {
    "id": "SI:short:2026-09-14T09:30:00Z",
    "product": "SI",
    "contract": "SIZ26",
    "side": "short",
    "entry_time": "2026-09-14T09:30:00Z",
    "entry_price": 63.05,
    "stop_price": 64.115,
    "take_profit": null,
    "breakeven_locked": false,
    "quantity": 1,
    "unrealized_pnl_usd": 0.0,
    "pnl_basis": "live",
    "copy": {
      "contract": "SIZ26",
      "cqg_symbol": "SIEZ26",
      "side": "sell",
      "quantity": 1,
      "entry_ref": 63.05,
      "stop_price": 64.115,
      "take_profit": null,
      "tick_size": 0.005
    }
  }
}

6 Đối tượng dữ liệu

Quy tắc chung để VPS thêm sản phẩm mới mà không phải phát hành lại app: mọi danh sách mã và mọi field dạng liệt kê (state, event, service.state) đều có thể có thêm giá trị. Gặp giá trị lạ, app hiện nhãn *_label do server trả; gặp event lạ thì bỏ qua; sản phẩm chưa có biểu tượng thì dùng hình mặc định.

ProductCard

Zone

Position

Copy lệnh — Position.copy

Phần duy nhất app phải làm thêm là nút copy lệnh. Mọi con số trong object này do VPS tính sẵn — app chỉ hiện và cho copy, không tự ghép mã hay làm tròn giá.

Trade

Event

ServiceState

7 Bảo trì và nâng cấp

Cập nhật engine và nâng cấp định kỳ là việc thường xuyên của cụm. Có hai việc khác hẳn nhau, và app hiện chúng khác hẳn nhau:

7.1 Nâng cấp một sản phẩm

Đây là việc thường xuyên nhất: một sản phẩm được sửa logic, chạy thử, rồi thay vào — trong khi các sản phẩm khác vẫn giao dịch bình thường. Thẻ đó không rời danh sách, chỉ tạm không có số; lịch sử lệnh của thẻ vẫn giữ nguyên.

Ví dụ — sự kiện lúc bắt đầu

{
  "id": 58251,
  "event": "product_unavailable",
  "at": "2026-09-14T08:41:07Z",
  "product": "ZS",
  "data": {
    "code": "ZS",
    "unavailable": {
      "label": "Đang nâng cấp engine",
      "since": "2026-09-14T08:41:02Z"
    }
  }
}

Ví dụ — thẻ trong ảnh chụp lúc đang nâng cấp

{
  "code": "ZS",
  "name": "Đậu tương",
  "category": "Nông sản",
  "contract": "ZSX26",
  "cqg_symbol": "ZSEX26",
  "cqg_root": "ZSE",
  "unavailable": {
    "label": "Đang nâng cấp engine",
    "since": "2026-09-14T08:41:02Z"
  }
}

Phần nhận dạng của thẻ vẫn còn; các field số thì vắng. App giữ nguyên số cuối cùng nó đang có, làm mờ đi, hiện unavailable.label, và tắt nút copy của riêng thẻ đó.

7.2 Nâng cả hệ thống

Khi nâng phần dùng chung, cả cụm dừng một lúc. Bảng vận hành trên web lúc đó bị thay bằng trang “đang nâng cấp”; app làm đúng như vậy: nhận service_changed với state = "bao_tri" thì hiện màn hình bảo trì thay cả màn, và nhận service_changed với binh_thuong thì tải lại số mới trong một lần. Trang bảo trì của bảng vận hành đếm số phút đã trôi chứ không hứa thời điểm xong — app làm y vậy.

Ví dụ — service lúc đang nâng cả hệ thống

{
  "state": "bao_tri",
  "label": "Đang nâng cấp hệ thống",
  "since": "2026-09-14T08:41:02Z",
  "version": "1.3",
  "data_at": "2026-09-14T08:40:55Z"
}

Ví dụ — sự kiện đẩy khi trạng thái đổi

{
  "id": 58240,
  "event": "service_changed",
  "at": "2026-09-14T08:41:04Z",
  "product": null,
  "data": {
    "state": "bao_tri",
    "label": "Đang nâng cấp hệ thống",
    "since": "2026-09-14T08:41:02Z",
    "version": "1.3",
    "data_at": "2026-09-14T08:40:55Z"
  }
}

7.3 Ai đặt trạng thái nào

Ví dụ — mất kết nối với VPS

{
  "state": "mat_ket_noi",
  "label": "Chưa nhận được số mới",
  "since": "2026-09-14T08:46:10Z",
  "version": "1.3",
  "data_at": "2026-09-14T08:45:05Z"
}

7.4 App hiện gì

Nguyên tắc: không bao giờ để màn hình đứng im mà không nói lý do, và cũng không làm người dùng hoảng. Số cũ vẫn là số đúng — chỉ là đúng tại một thời điểm đã qua, nên app nói rõ thời điểm đó thay vì xoá đi hay để nguyên như thật.

Ba màn hình trên chỉ minh hoạ hành vi; bố cục và màu thuộc về đội app.

Ba chi tiết đáng giữ

• Đếm lên, không đếm ngược. Không ai biết trước một lần nâng cấp mất bao lâu, nên app hiện số phút đã trôi, không hứa thời điểm xong.
• Tắt nút copy là quyết định về an toàn, không phải về giao diện. Giá trị của nút copy nằm ở chỗ nó luôn kèm SL và TP hiện tại. Lúc app không chắc mình đang thấy mức mới nhất thì thà không cho copy còn hơn cho copy một mức đã cũ.
• Câu chữ do server gửi. App hiển thị label, chỉ tự tính phần định dạng (số phút đã trôi, giờ địa phương). Đổi câu chữ không cần phát hành lại app.

// App: một chỗ duy nhất quyết định màn hình đang ở trạng thái nào.
function datTrangThaiDichVu(sv) {
  const dungDuoc = sv.state === 'binh_thuong';
  bangBao.hien   = !dungDuoc;
  bangBao.chu    = sv.label;                       // câu do server gửi, app không tự chế
  bangBao.dem    = sv.since;                       // app đếm số phút ĐÃ trôi, không hứa lúc xong
  bangBao.ban    = sv.state === 'bao_tri' ? sv.version : null;
  bangBao.soLuc  = sv.data_at;                     // "số liệu giữ ở lúc ..."
  batNutCopy(dungDuoc);                            // tắt copy: SL có thể đã đổi mà app không thấy
  batThongBaoDay(dungDuoc);
}

8 Quy ước số liệu

• Một quyết định, nhiều thẻ. Khi engine bạc vào cả hợp đồng lớn và mini, VPS phát hai vị thế ở hai thẻ: SI (1 HĐ SIZ26, 5.000 oz) và QI (1 HĐ QIZ26, 2.500 oz). Tiền mỗi thẻ là phần của đúng hợp đồng đó. Ví dụ thật 14/09: SIZ26 −$5.325,00 và QIZ26 −$2.662,50, cộng lại −$7.987,50.
• Chưa trừ phí. Mọi con số lãi/lỗ là tiền của lệnh trên chính thẻ đó và chưa trừ phí giao dịch. App hiện đúng con số VPS gửi, không tự trừ thêm.
• Hoà tính là thắng trong mọi win_rate — quy ước chung của cả 10 engine.
• Lệnh hiện lúc nào. Tuỳ sản phẩm, lệnh hiện ngay lúc nến vào lệnh mở, hoặc lúc nến đó đóng. App không cần phân biệt — hiện khi nhận position_opened. Nếu VPS sửa giá vào sau khi đối chiếu sổ, app nhận position_updated và báo cho người đã copy.
• Kéo SL và BE. Mỗi lần SL được kéo, VPS gửi position_updated với mức mới trong copy.stop_price. SL lên hoà vốn thì breakeven_locked = true và app hiện BE.
• Đóng lệnh ngay khi chạm SL. Với một số sản phẩm, lệnh đóng được gửi ngay lúc giá chạm SL và sổ đối chiếu sau; nếu ra giá hoặc tiền khác, VPS gửi trade_corrected và app sửa dòng lịch sử.
• Chưa có thì là null, và app nói rõ. Lãi/lỗ tạm tính chưa có giá thì null, không phải 0. Giá vào/ra không được ghi thì null và app hiện “chưa ghi”. Một phía không có vùng hỗ trợ/kháng cự thì app in câu trong *_note.
• Không có giá thị trường live — theo quy định từ 04/09/2026. Lãi/lỗ tạm tính vẫn có.
• Thẻ chỉ tồn tại khi VPS công bố. VPS gỡ một thẻ thì thẻ đó và lịch sử lệnh của nó rời khỏi app; engine lỗi, mất feed hay đang nâng cấp thì thẻ vẫn còn.

9 Thay đổi v1.2, v1.1 và các mục đã chốt

Thay đổi v1.2 · 09/10/2026

Chỉ thêm. “Nay mới ghi” = server đã chạy như vậy từ v1.1, tài liệu giờ mới viết ra. Giờ là giờ Việt Nam.

Thay đổi v1.1 · 07/10/2026

Bản v1.1 chỉ thêm — không đổi nghĩa hay bỏ field nào của v1. Mọi mục dưới đây đã chạy trên VPS và kiểm qua hai tên miền ngày 07/10/2026.

Đã chốt

• Hạ tầng — không có dịch vụ trung gian. algo-api.sfi.com.vn (REST) và algo-socket.sfi.com.vn (SSE + WebSocket) trỏ thẳng về VPS qua tunnel Cloudflare do IT quản lý.
• Key — một key riêng cho app, môi trường thật, scope algo:read + algo:stream; đội Algo cấp và giữ. Gửi riêng qua kênh bảo mật, không đăng trên tài liệu.
• Ngưỡng mất kết nối — 60 giây không có ảnh chụp mới từ VPS thì service_changed chuyển sang mat_ket_noi.
• Nút copy trong lúc bảo trì — tắt hẳn, như mục 7.
• Hệ mã và làm tròn — contract là mã sàn, cqg_symbol là mã CQG; SL/TP làm tròn “kích hoạt y hệt luật” trên bước giá của hợp đồng copy.
• Giá trị category — Kim loại (SI, QI, HG, PL) · Nông sản (ZC, ZW, ZS, ZL, ZM) · Nguyên liệu công nghiệp (SB, KC).
• Lưu lịch sử — giữ toàn bộ, từ ngày bắt đầu của từng sản phẩm; app nạp bằng /v1/trades lúc khởi tạo rồi theo dòng sự kiện.
• Gỡ thẻ thì lịch sử rời app — xác nhận: thẻ bị gỡ thì lệnh cũ của nó không còn trong /v1/trades.
• Giới hạn nhịp gọi — chưa đặt. App nên dùng stream cho cập nhật và chỉ gọi REST lúc mở app, lúc nối lại và khi đọc bù. Nếu cần giới hạn, đội Algo báo trước.
• Thu hồi key — báo đội Algo; key bị thu hồi mất hiệu lực sau vài giây (REST trả 401, WebSocket đóng mã 4401) và key mới được gửi riêng.
• Thông báo đẩy — v1.2 xem mục 12: đẩy position_opened, position_updated (khi SL đổi), position_closed; không đẩy trade_corrected.

10 Thêm và gỡ sản phẩm — app tự cập nhật

Đội Algo thêm hay gỡ sản phẩm ở phía VPS. Từ v1.2 server báo ngay bằng hai sự kiện; app không phải tự dò, cũng không cần ra bản app mới.

product_removed chỉ phát khi sản phẩm bị gỡ khỏi cấu hình VPS. Engine chết, router hay API khởi động lại đều không sinh sự kiện này — đã kiểm cả trường hợp khe bạc chết làm thẻ Bạc mini tạm vắng khỏi dữ liệu.

Ví dụ — hai sự kiện (mã RC là minh hoạ)

{"id": 402, "event": "product_added", "at": "2026-10-20T03:00:05Z", "product": "RC",
 "data": {"code": "RC", "name": "Cà phê Robusta", "category": "Nguyên liệu công nghiệp",
          "contract": "RCF27", "cqg_symbol": "LRCF27", "state": "watching", ...}}

{"id": 517, "event": "product_removed", "at": "2026-11-02T03:00:04Z", "product": "RC",
 "data": {"code": "RC"}}

Lưới an toàn — vẫn nên có

• Lấy lại GET /v1/products lúc mở app, và lúc nối lại stream mà không bù được (không còn id cuối, hoặc quá 7 ngày). So với danh sách đang hiện: mã mới → thêm, mã biến mất → gỡ, mã còn lại → thay nguyên thẻ.
• Sự kiện mang một mã app chưa có mà không phải product_added (ví dụ app vừa mở lại): không văng lỗi — lấy lại danh sách trước rồi mới xử lý; lấy lại xong vẫn không có thì bỏ qua sự kiện đó.
• Giá trị lạ trên thẻ mới theo mục 6: category mới → nhóm mới, đúng chữ server trả; icon_url null → ảnh mặc định.

Mẫu JavaScript

case 'product_added':   themThe(ev.data); napLichSu(ev.data.code); break;  // thẻ mới
case 'product_removed': goThe(ev.data.code); break;                         // bỏ thẻ + vị thế + lịch sử

Cách thử

Khi đội Algo thêm sản phẩm thật, hai bên hẹn giờ: app mở sẵn, thẻ mới phải tự hiện mà không tải lại app.

11 Hỗ trợ / kháng cự dạng vùng

Thay đổi phía server

Hiện trên app

• Cột Hỗ trợ / Kháng cự của bảng tổng: in vùng đầu mỗi phía dạng lo–hi — zones.support[0] và zones.resistance[0]. Ví dụ ZL: 67,68–67,91 / 68,19–68,42.
• Vùng có lo = hi → in một số.
• Vùng chỉ đổi phía khi một nến 15 phút đóng xuyên qua nó. Hỗ trợ vẫn là hỗ trợ khi giá chạm, đi vào trong, hay chọc thủng trong lúc nến 15 phút còn chạy; chỉ khi nến đó đóng dưới lo thì vùng mới chuyển sang kháng cự (kháng cự ngược lại). Vì vậy giá hiện tại có lúc nằm trong [lo, hi], hoặc vượt qua mép vùng vài phút. Đó là chủ đích để vùng không nhảy theo từng nhịp giá — app in nguyên thứ tự server gửi, không tự lọc hay xếp lại vùng theo giá.
• Phía không có vùng → support / resistance là mảng rỗng và *_note có câu giải thích (ví dụ “Giá đang ở vùng cao nhất của dữ liệu — chưa có kháng cự phía trên.”) → in “—”, câu note để ở dòng phụ hoặc khi chạm vào.
• Trang chi tiết giữ như cũ (GET /v1/products/{code} → zones), nên in cả hai vùng mỗi phía dạng lo–hi.
• Số đã nằm đúng bước giá của hợp đồng — app in nguyên, không làm tròn lại.

Ví dụ — một thẻ trong GET /v1/products

{
  "code": "ZL", "name": "Dầu đậu tương", "category": "Nông sản",
  "contract": "ZLZ26", "state": "watching", "state_label": "Đang theo dõi",
  "trend": "di_ngang", "trades": 29, "win_rate": 0.621, "open_positions": 0,
  "stale_since": null, "icon_url": null,
  "zones": {
    "support":    [{"price": 67.91, "lo": 67.68, "hi": 67.91},
                   {"price": 67.64, "lo": 67.42, "hi": 67.64}],
    "resistance": [{"price": 68.19, "lo": 68.19, "hi": 68.42},
                   {"price": 68.46, "lo": 68.46, "hi": 68.68}],
    "support_note": null,
    "resistance_note": null
  }
}

Mẫu JavaScript

function vung(z) {                              // {lo, hi} -> "67.68–67.91"
  return z.lo === z.hi ? fmt(z.lo) : fmt(z.lo) + '–' + fmt(z.hi);
}

function oHoTroKhangCu(the) {
  const z = the.zones;
  if (!z) return '';                             // thẻ unavailable: giữ ô cũ, làm mờ
  const ht = z.support[0]    ? vung(z.support[0])    : '—';
  const kc = z.resistance[0] ? vung(z.resistance[0]) : '—';
  return ht + ' / ' + kc;                        // note (*_note) đặt ở dòng phụ khi phía đó là "—"
}

// product_updated / product_available: thay nguyên thẻ -> ô tự vẽ lại với zones mới.

12 Thông báo đẩy

Các thông báo trên layout của app — vị thế mở mới, dời SL, đóng vị thế — dùng được ngay các sự kiện mục 5.3, không cần API mới. Điểm mấu chốt: người nghe stream là server thông báo của app, không phải app trên điện thoại. App tắt thì không nghe được gì, mà thông báo đẩy vẫn phải tới.

Server thông báo làm gì

• Giữ một kết nối cho cả hệ tới algo-socket.sfi.com.vn — WebSocket /ws/signals hoặc SSE /stream/signals — bằng key (scope algo:stream). Hoặc gọi GET /v1/events?since_id=<id cuối> vài giây một lần (limit tối đa 100).
• Lưu id sự kiện cuối vào chỗ bền (cơ sở dữ liệu). Nối lại hay server khởi động lại thì mở stream kèm ?since_id=<id cuối> — không sót thông báo nào.
• Khử trùng theo id — stream giao ít nhất một lần.

Ghép thông báo với sự kiện

position_updated còn phát khi TP, giá vào hay khối lượng đổi. Chỉ đẩy khi stop_price đổi.

Không đẩy

• trade_corrected — sửa lịch sử, có thể đến hàng loạt (07/10: 53 lần một lượt; 09/10: 51 lần). Chỉ cập nhật dòng lịch sử.
• product_* (kể cả product_added / product_removed) — cập nhật thẻ trong app; muốn báo “có sản phẩm mới” thì app tự quyết.
• service_changed — hiện băng bảo trì trong app (mục 7).

Tên hiển thị

Dùng name + mã CQG, ví dụ “Ngô ZCEZ26”, “Bạc SIEZ26” — cùng mã bảng vận hành đang hiện. contract là mã sàn (ZCZ26); mã CQG nằm ở copy.cqg_symbol của vị thế và cqg_symbol của thẻ. Không dùng dạng “ZCE/USD”. Giá in nguyên số server gửi.

Ví dụ — một position_opened thật (ZL, 08/10/2026)

{"id": 199, "event": "position_opened", "at": "2026-10-08T16:30:00Z", "product": "ZL",
 "data": {"id": "ZL:short:2026-10-08T16:30:00Z", "product": "ZL", "contract": "ZLZ26",
          "side": "short", "entry_time": "2026-10-08T16:30:00Z", "entry_price": 67.86,
          "stop_price": 68.26, "take_profit": null, "breakeven_locked": false, "quantity": 1,
          "copy": {"contract": "ZLZ26", "cqg_symbol": "ZLEZ26", "side": "sell", "quantity": 1,
                   "entry_ref": 67.86, "stop_price": 68.26, "take_profit": null, "tick_size": 0.01}}}

Mẫu — server thông báo (Node.js, thư viện ws)

import WebSocket from 'ws';

let idCuoi = await docIdCuoi();                   // lưu bền (DB), không phải bộ nhớ
const viThe = new Map();                          // id vị thế -> {sl đã báo, mã CQG}
const tenThe = new Map();                         // code -> name, nạp từ GET /v1/products

function xuLy(ev) {
  if (ev.id <= idCuoi) return;                  // khử trùng: giao ít nhất một lần
  idCuoi = ev.id; luuIdCuoi(idCuoi);
  const d = ev.data, ten = tenThe.get(ev.product) ?? ev.product;
  switch (ev.event) {
    case 'position_opened':
      viThe.set(d.id, { sl: d.stop_price, ma: d.copy.cqg_symbol });
      return day(`${ten} ${d.copy.cqg_symbol}`,
                 `${d.side === 'long' ? 'Mua' : 'Bán'} @ ${d.entry_price} · SL ${d.stop_price}`);
    case 'position_updated': {
      const cu = viThe.get(d.id)?.sl;
      if (d.stop_price === cu) return;             // đổi TP / giá vào / khối lượng: không đẩy
      viThe.set(d.id, { sl: d.stop_price, ma: d.copy.cqg_symbol });
      return day(`${ten} ${d.copy.cqg_symbol}`,
                 `Dời SL ${cu ?? '—'} → ${d.stop_price}${d.breakeven_locked ? ' (hoà vốn)' : ''}`);
    }
    case 'position_closed': {
      const v = viThe.get(d.position_id);
      viThe.delete(d.position_id);
      if (!d.trade) return;                        // vào sớm bị huỷ: không đẩy
      return day(`${ten} ${v?.ma ?? d.trade.contract}`,
                 `Đóng @ ${d.trade.exit_price} · ${d.trade.pnl_usd >= 0 ? '+' : ''}${d.trade.pnl_usd} USD`);
    }
    case 'product_added': tenThe.set(d.code, d.name); return;
    // trade_corrected, product_*, service_changed: cập nhật dữ liệu, KHÔNG đẩy
  }
}

function noi() {
  const ws = new WebSocket(`wss://algo-socket.sfi.com.vn/ws/signals?since_id=${idCuoi}`,
                           { headers: { Authorization: `Bearer ${KEY}` } });
  ws.on('message', (b) => { const m = JSON.parse(b); if (m.event !== 'ping') xuLy(m); });
  ws.on('close', (code) => { if (code !== 4401) setTimeout(noi, 3000); });  // 4401: key sai, đừng nối lại
}
noi();

13 Hỏi đáp

“Giá lệnh chờ” (ví dụ “Bán @661.5”) lấy ở đâu?

• Hệ không đặt lệnh chờ, nên không có giá này. state = wait_buy / wait_sell (“Chờ mua / Chờ bán”) nghĩa là engine đang chờ điều kiện vào lệnh — chưa có giá.
• Khi thẻ có vị thế, khách bấm Copy là vào lệnh thị trường, SL theo lệnh đang chạy — lấy từ copy của vị thế (GET /v1/positions hoặc sự kiện position_*): cqg_symbol, side, quantity, stop_price, take_profit, tick_size. Giá khớp của khách có thể khác giá vào của engine; entry_ref chỉ để tham chiếu.
• Cột “Lệnh mở” của bảng tổng: thẻ không có vị thế → “—”; có vị thế → chiều + entry_price từ /v1/positions.

Vì sao take_profit thường là null?

• take_profit là field có thể null (mục 4.3). Hiện các engine kéo SL theo giá (trail) nên TP là null; ZL, ZM có TP. TP có thể xuất hiện sau khi mở lệnh, qua một position_updated — ví dụ vị thế ZL ngày 08/10 mở với TP null, sau đó cập nhật TP 66,93.
• App cứ giữ field này. Khi nâng cấp, server điền TP vào đúng field đó, không đổi khuôn.

App tắt lâu rồi mở lại thì sao?

Làm lại bước 1 của mục 0: lấy ảnh chụp REST, rồi mở stream. Nếu còn id cuối và chưa quá 7 ngày, mở stream kèm ?since_id= để nhận lại các sự kiện đã lỡ (cần cho lịch sử thông báo); không thì ảnh chụp REST là đủ.

App có cần gọi REST định kỳ không?

Không bắt buộc. Stream đã mang mọi thay đổi, kể cả thẻ mới, thẻ bị gỡ và vùng hỗ trợ/kháng cự. REST chỉ cần lúc mở app, lúc người dùng kéo làm mới, và lúc nối lại mà không bù được.