npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ssi.developer/ssi-sdk

v3.3.2

Published

SSI SDK for Node.js – market data, trading and real-time streaming

Readme

SSI Node.js SDK

Node.js/TypeScript SDK cho nền tảng giao dịch chứng khoán SSI. Hỗ trợ REST API và WebSocket streaming.

npm version npm downloads Node version Release License

Mục lục


Cài đặt

npm install @ssi.developer/ssi-sdk
# hoặc
yarn add @ssi.developer/ssi-sdk
# hoặc
pnpm add @ssi.developer/ssi-sdk

Cấu hình

Tạo đối tượng Config (hoặc truyền trực tiếp ConfigOptions vào client Auth):

import { Config } from '@ssi.developer/ssi-sdk';

const config = new Config({
  clientId: "YOUR_CLIENT_ID",
  apiKey: "YOUR_API_KEY",
  apiSecret: "YOUR_API_SECRET",
  privateKey: "YOUR_PRIVATE_KEY", // Private key dùng ký lệnh (Base64 XML)
});

Tất cả tuỳ chọn cấu hình:

| Tham số | Kiểu | Mặc định | Mô tả | |---------|------|----------|-------| | clientId | string | "" | Client ID xác thực (bắt buộc cho danh mục đầu tư) | | apiKey | string | "" | API key từ SSI | | apiSecret | string | "" | API secret từ SSI | | privateKey | string | "" | Private key cho ký lệnh giao dịch | | apiUrl | string | "https://api.ssi.com.vn" | URL REST API | | streamingUrl | string | "wss://stream.ssi.com.vn/ws/v3" | URL WebSocket streaming | | timeoutMs | number | 60000 | Timeout request (millisecond) | | maxRetries | number | 5 | Số lần retry tối đa | | retryDelayMs | number | 2000 | Delay cơ sở giữa các lần retry (exponential backoff, millisecond) | | rateLimitPerSecond | number | 10 | Giới hạn request/giây (0 = không giới hạn). SDK còn theo header X-RateLimit-* của server | | tradingApiDomain | string | "https://api.ssi.com.vn" | URL REST giao dịch. Còn mặc định thì đi theo apiUrl; getter tradingApiUrl | | tradingWsDomain | string | "wss://api.ssi.com.vn/ws/v3/trading" | URL trading WebSocket; getter tradingWsUrl | | maxBatchOrders | number | 20 | Số lệnh tối đa cho một batch (placeBatchOrders / cancelBatchOrders) | | userAgent | string | (UA trình duyệt) | User-Agent cho HTTP, WebSocket và payload lệnh | | autoReconnect | boolean | true | Tự kết nối lại streaming khi rớt | | otpPollIntervalMs | number | 5000 | Millisecond giữa các lần poll Smart OTP | | otpPollMaxWaitMs | number | 60000 | Tổng millisecond chờ user approve Smart OTP | | proxy | string | — | Proxy cho HTTP. Không áp dụng cho WebSocket (thư viện ws không hỗ trợ proxy) | | logLevel | string | "INFO" | DEBUG, INFO, WARNING, ERROR, CRITICAL |

URL bỏ trống hoặc rỗng sẽ dùng mặc định; URL WebSocket phải là wss://. Truyền option không tồn tại sẽ ném ConfigurationError. new Auth(config) không sửa config bạn đưa vào. Config, Token và exception không in secret (apiSecret, privateKey, token đều bị che), nhưng đừng tự log chúng.


Kiến trúc Client

SDK sử dụng kiến trúc modular gồm 4 client chuyên biệt:

| Client | Mô tả | Yêu cầu | |--------|-------|---------| | Auth | Xác thực & quản lý token | Config / ConfigOptions | | Data | Dữ liệu thị trường (OHLC, chỉ số, chứng khoán) | Auth (không cần OTP) | | Trading | Giao dịch + danh mục + tài khoản | Auth (cần OTP) | | Stream | Streaming realtime qua WebSocket | Auth (cần OTP) |

Luồng khởi tạo:

Config / ConfigOptions → Auth → authenticate(otp) → Data / Trading / Stream

Auth là client gốc — quản lý REST client và token. Các client Data, Trading, Stream đều nhận Auth làm tham số và chia sẻ chung HTTP connection.

Services được cung cấp bởi mỗi client:

| Client | Service | Truy cập | Mô tả | |--------|---------|---------|-------| | Auth | TokenManager | auth.tokenManager | Xác thực, OTP, refresh token | | Data | MarketDataService | data.marketData | OHLC, chỉ số, chứng khoán, securities summary | | Trading | TradingService | trading.trading | Đặt/sửa/huỷ lệnh, sức mua/bán | | Trading | AccountService | trading.account | Thông tin tài khoản | | Trading | PortfolioService | trading.portfolio | Số dư, vị thế, sổ lệnh, PPMMR | | Stream | StreamingService | stream.streaming | Subscribe/unsubscribe realtime data |

Sử dụng TypeScript/ESM

import { Auth, Data, Trading, Stream, Board } from '@ssi.developer/ssi-sdk';

async function main() {
  const auth = new Auth({
    clientId: "YOUR_CLIENT_ID",
    apiKey: "YOUR_API_KEY",
    apiSecret: "YOUR_API_SECRET",
    privateKey: "YOUR_PRIVATE_KEY",
  });

  // Xác thực (cần OTP cho giao dịch và streaming)
  await auth.authenticate("222222");

  // Dữ liệu thị trường
  const data = new Data(auth);
  const ohlc = await data.marketData.getOhlc1Minute("SSI");
  console.log(ohlc);

  // Giao dịch & danh mục
  const trading = new Trading(auth);
  const accounts = await trading.account.getAccountInfo();
  console.log(accounts);

  // Streaming
  const stream = new Stream(auth);
  stream.streaming.onData = (msg) => console.log('Realtime data:', msg);
  await stream.streaming.connect();
  await stream.streaming.subscribeSymbolTrade(["SSI"]);
  await stream.streaming.ping();
  await stream.streaming.wait();
}

main().catch(console.error);

Chỉ dùng dữ liệu thị trường (không cần OTP)

import { Auth, Data } from '@ssi.developer/ssi-sdk';

const auth = new Auth({
  apiKey: "YOUR_API_KEY",
  apiSecret: "YOUR_API_SECRET",
});

await auth.authenticate(); // Không cần OTP cho market data

const data = new Data(auth);
const ohlc = await data.marketData.getOhlc1Minute("SSI");

1. Xác thực

Dùng Auth. Các method của tokenManager được delegate trực tiếp lên client Auth.

1.1. Xác thực với OTP

// Dùng trực tiếp trên auth (delegate từ tokenManager)
const token = await auth.authenticate("222222");
console.log(`Access token: ${token.accessToken}`);
console.log(`Expires at: ${token.expiresAt}`);

// Hoặc truy cập qua tokenManager
const token2 = await auth.tokenManager.authenticate("222222");

// Smart OTP: truyền transactionId (lấy từ requestOtp) thay vì otp —
// chỉ gọi được sau khi user đã bấm approve trên thiết bị.
const token3 = await auth.authenticate(undefined, "TRANSACTION_ID");

otp và transactionId loại trừ lẫn nhau — chỉ truyền một trong hai.

1.2. Yêu cầu gửi OTP

Cùng một endpoint cho cả 2 loại tài khoản (SMS/email hoặc Smart OTP) — server tự quyết định cách gửi OTP dựa trên cách tài khoản đã đăng ký:

const result = await auth.requestOtp();
console.log(result);

Tài khoản đã kích hoạt Smart OTP có 2 cách để xác thực:

  1. Approve trên app — gọi requestOtp() để bắn yêu cầu lên thiết bị, lấy transactionId, rồi dùng ensureAuthenticated(undefined, transactionId) để SDK tự poll cho đến khi user bấm approve.
  2. Lấy mã trực tiếp trên app — mở app Smart OTP, đọc mã hiển thị sẵn, rồi điền thẳng mã đó vào ensureAuthenticated("123456") (hoặc authenticate("123456")) — không cần gọi requestOtp() trước.

Cần kiểu rõ ràng thì dùng requestOtpTyped() (trả OTPResponse; transactionId chỉ có với Smart OTP):

const otp = await auth.requestOtpTyped();
if (otp.transactionId) await auth.ensureAuthenticated(undefined, otp.transactionId);

1.3. Làm mới token

const token = await auth.refresh();

1.4. Tự động đảm bảo xác thực

// 1) Refresh nếu có refresh token còn dùng được
const accessToken1 = await auth.ensureAuthenticated();

// 2) OTP thường (SMS/email) hoặc mã Smart OTP lấy trực tiếp trên app
const accessToken2 = await auth.ensureAuthenticated("222222");

// 3) Smart OTP dạng push-approval (truyền transactionId lấy từ requestOtp)
const otpResult = await auth.requestOtp();
const transactionId = (otpResult.data as any)?.transactionId;
const accessToken3 = await auth.ensureAuthenticated(
  undefined,
  transactionId,
  5000, // pollIntervalMs (mặc định 5000ms)
  6     // pollMaxRetries (mặc định 6 lần)
);

1.5. Kiểm tra trạng thái token

console.log(auth.getToken());                       // Token object hoặc null
console.log(auth.tokenManager.getAccessToken());   // Access token string hoặc undefined
console.log(auth.tokenManager.isTokenExpired());   // true/false
console.log(auth.tokenManager.hasRefreshToken());  // true/false
console.log(auth.canRefresh);                      // refresh token còn dùng được?

2. Tài khoản

Truy cập qua trading.account (client Trading).

2.1. Lấy danh sách tài khoản

const accounts = await trading.account.getAccountInfo();

for (const acc of accounts) {
  console.log(`${acc.accountNo} - ${acc.accountType}`);
}

Trả về: Promise<Account[]> — mỗi Account có:

  • accountNo: string — Số tài khoản
  • accountType: AccountType — Loại tài khoản (EQUITY, EQUITY_MARGIN, DERIVATIVE)

3. Dữ liệu thị trường

Truy cập qua data.marketData (client Data).

Lưu ý: Data chỉ cần auth.authenticate() (không cần OTP).

Tổng quan method

| Nhóm | Method | Mô tả | |------|--------|-------| | OHLC trong ngày | getOhlc1Minute(symbol) | Nến 1 phút | | | getOhlc3Minute(symbol) | Nến 3 phút | | | getOhlc5Minute(symbol) | Nến 5 phút | | | getOhlc15Minute(symbol) | Nến 15 phút | | | getOhlc1Hour(symbol) | Nến 1 giờ | | OHLC lịch sử | getOhlc1MinuteHistorical(symbol, from, to, page, size) | 1 phút | | | getOhlc3MinuteHistorical(...) | 3 phút | | | getOhlc5MinuteHistorical(...) | 5 phút | | | getOhlc15MinuteHistorical(...) | 15 phút | | | getOhlc1HourHistorical(...) | 1 giờ | | | getOhlc1DayHistorical(...) | 1 ngày | | | getOhlc1WeekHistorical(...) | Ngừng hỗ trợ: ném ValidationError (server từ chối timeframe này) | | | getOhlc1MonthHistorical(...) | Ngừng hỗ trợ: ném ValidationError | | OHLC mọi trang | iterOhlc(symbol, timeframe, from?, to?, size?) | Async generator, tự lật trang | | | getOhlcAll(symbol, timeframe, from?, to?, size?, ascending?) | Gom toàn bộ nến trong khoảng | | Chỉ số | getIndexes() | Tất cả chỉ số | | | getIndexesByBoard(board) | Chỉ số theo sàn | | Index Summary | getIndexSummary(index) | Summary chỉ số hiện tại | | | getIndexSummaryHistorical(index, tradingDate) | Summary chỉ số lịch sử | | | getBoardSummary(board) | Summary sàn hiện tại | | | getBoardSummaryHistorical(board, tradingDate) | Summary sàn lịch sử | | Chứng khoán | getSecuritiesInfo(symbol) | Thông tin 1 mã | | | getSecuritiesInfoByIndex(index) | Theo chỉ số | | | getSecuritiesInfoByBoard(board) | Theo sàn | | Securities Summary | getSecuritiesSummary(symbol) | Summary mã hiện tại | | | getSecuritiesSummaryHistorical(symbol, from, to) | Summary mã lịch sử | | | getSecuritiesSummaryByIndex(index) | Summary theo chỉ số | | | getSecuritiesSummaryByIndexHistorical(index, from, to) | Summary chỉ số lịch sử | | Master Data | getMasterData() | Giá trần/sàn/tham chiếu tất cả mã hôm nay | | | getMasterDataHistorical(from, to) | Giá trần/sàn/tham chiếu tất cả mã trong khoảng ngày | | Corporate Actions | getCorporateActions(symbol?, language = "vn") | Sự kiện quyền (cổ tức, thưởng, phát hành...) hôm nay | | | getCorporateActionsHistorical(from, to, symbol?, language = "vn") | Sự kiện quyền trong khoảng ngày (tối đa 5 ngày) |

3.1. Dữ liệu OHLC (nến)

SDK cung cấp các method OHLC theo từng timeframe:

Lấy dữ liệu trong ngày (không cần truyền ngày):

// OHLC 1 phút trong ngày
const ohlc = await data.marketData.getOhlc1Minute("SSI");
for (const candle of ohlc) {
  console.log(`${candle.tradingDate}: O=${candle.openPrice} H=${candle.highPrice} L=${candle.lowPrice} C=${candle.closePrice} V=${candle.volume}`);
}

Lấy dữ liệu lịch sử (truyền khoảng ngày + phân trang):

// OHLC 1 ngày lịch sử
const ohlc = await data.marketData.getOhlc1DayHistorical(
  "SSI",
  "2026/03/01 00:00:00",
  "2026/03/27 23:59:59",
  1,
  100
);

Trả về: Promise<OHLCData[]> — mỗi OHLCData có:

  • symbol, tradingDate, openPrice, highPrice, lowPrice, closePrice, volume, value

Tham số historical:

| Tham số | Kiểu | Mặc định | Mô tả | |---------|------|----------|-------| | symbol | string | (bắt buộc) | Mã chứng khoán | | from | string | (bắt buộc) | Ngày bắt đầu (định dạng YYYY/MM/DD hoặc YYYY/MM/DD HH:mm:ss) | | to | string | (bắt buộc) | Ngày kết thúc | | page | number | 1 | Trang hiện tại | | size | number | 1000 | Số bản ghi/trang |

Duyệt toàn bộ nến trong khoảng (tự lật trang):

for await (const bar of data.marketData.iterOhlc("SSI", "1D", "2026/01/01", "2026/03/31")) {
  console.log(bar.tradingDate, bar.closePrice);
}
const all = await data.marketData.getOhlcAll("SSI", "1D", "2026/01/01", "2026/03/31");

from/to chỉ có ngày thì SDK tự bổ sung 00:00:00 / 23:59:59 (server trả 400213 với ngày trần). page/size < 1 bị từ chối ngay ở client. getSecuritiesSummary và getMasterData tự đi theo pagesCount.

3.2. Danh sách chỉ số thị trường

import { Board } from '@ssi.developer/ssi-sdk';

// Lấy tất cả chỉ số
const indices = await data.marketData.getIndexes();

// Lấy theo sàn
const hoseIndices = await data.marketData.getIndexesByBoard(Board.HOSE);

for (const idx of indices) {
  console.log(`${idx.index} - ${idx.indexName}`);
}

Trả về: Promise<MarketIndexes[]> — mỗi item có: index, indexName, board

3.3. Tổng hợp chỉ số (Index Summary)

// Summary hiện tại
const summary = await data.marketData.getIndexSummary("VNINDEX");
if (summary) {
  console.log(`${summary.indexValue} (${summary.indexChange >= 0 ? '+' : ''}${summary.indexChange.toFixed(2)})`);
}

// Summary lịch sử
const summaryHist = await data.marketData.getIndexSummaryHistorical("VNINDEX", "2025/01/15");

// Summary theo sàn
const boardSummary = await data.marketData.getBoardSummary(Board.HOSE);

// Summary sàn lịch sử
const boardSummaryHist = await data.marketData.getBoardSummaryHistorical(Board.HOSE, "2025/01/15");

Trả về: Promise<MarketIndexSummary | null>

3.4. Thông tin chứng khoán

// Lấy thông tin 1 mã
const info = await data.marketData.getSecuritiesInfo("SSI");

// Lấy theo chỉ số
const securities = await data.marketData.getSecuritiesInfoByIndex("VN30");

// Lấy theo sàn
const hoseSecurities = await data.marketData.getSecuritiesInfoByBoard(Board.HOSE);

Trả về: Promise<SecuritiesInfo | null> hoặc Promise<SecuritiesInfo[]>

3.5. Tổng hợp chứng khoán (Securities Summary)

// Summary hiện tại
const summary = await data.marketData.getSecuritiesSummary("SSI");

// Summary lịch sử
const summaryHist = await data.marketData.getSecuritiesSummaryHistorical(
  "SSI",
  "2025/01/01",
  "2025/01/31"
);

// Summary theo chỉ số
const summaryIndex = await data.marketData.getSecuritiesSummaryByIndex("VN30");

// Summary theo chỉ số lịch sử
const summaryIndexHist = await data.marketData.getSecuritiesSummaryByIndexHistorical(
  "VN30",
  "2025/01/01",
  "2025/01/31"
);

Trả về: Promise<SecuritiesSummary[]>

3.6. Master Data (giá trần/sàn/tham chiếu)

SDK tự động gọi hết các trang (API endpoint này phân trang), không cần tự truyền page/size.

// Hôm nay
const result = await data.marketData.getMasterData();

// Khoảng ngày tự chọn
const resultHist = await data.marketData.getMasterDataHistorical(
  "2026/08/05",
  "2026/08/06"
);

for (const item of result) {
  console.log(`${item.board} ${item.symbol}: trần=${item.ceiling} sàn=${item.floor} TC=${item.refPrice}`);
}

Trả về: Promise<MasterData[]> — mỗi MasterData có: board, symbol, tradingDate, ceiling, floor, refPrice.

3.7. Corporate Actions (sự kiện quyền)

GET /api/v3/data/corporateActions. SDK tự gọi hết các trang (pageSize 100). Hai method tách theo thời điểm:

// Hôm nay (mọi mã, hoặc 1 mã)
const today = await data.marketData.getCorporateActions();
const gda = await data.marketData.getCorporateActions("GDA", "en");

// Quá khứ: khoảng ngày tối đa 5 ngày
const past = await data.marketData.getCorporateActionsHistorical(
  "2026/10/08",
  "2026/10/12",
  undefined, // undefined = tất cả mã
  "vn"       // "vn" (mặc định) hoặc "en"
);
for (const e of past) {
  console.log(e.symbol, e.eventTitle, e.exrightDate, e.recordDate, e.issueDate, e.exchange, e.ratio);
}

Trả về: Promise<CorporateAction[]> — symbol, eventTitle, exrightDate, recordDate, issueDate, exchange, ratio. Tất cả là string đúng như server trả (ngày YYYY/MM/DD, ratio không ép kiểu); sự kiện mới công bố có thể có exrightDate / ratio rỗng "". SDK kiểm tra trước khi gọi: ngày đúng YYYY/MM/DD, from <= to, khoảng tối đa 5 ngày, symbol chữ-số tối đa 20 ký tự, language là vn/en (sai thì ValidationError, không gọi mạng).


4. Danh mục đầu tư

Truy cập qua trading.portfolio (client Trading).

Tổng quan method

| Nhóm | Method | Trả về | |------|--------|--------| | Số dư | getEquityBalance(accountNo) | EquityAccountBalance | | | getDerivativeBalance(accountNo) | DerivativeAccountBalance | | Vị thế | getEquityPositions(accountNo) | EquityPosition[] | | | getDerivativePositions(accountNo) | AllDerivativePosition | | | getOpenDerivativePositions(accountNo) | DerivativePosition[] | | | getClosedDerivativePositions(accountNo) | DerivativePosition[] | | Sổ lệnh | getTodayOrders(accountNo) | Order[] | | | getHistoricalOrders(accountNo, from, to) | Order[] | | PPMMR | getEquityPpmmr(accountNo) | EquityPPMMR | | | getDerivativePpmmr(accountNo) | DerivativePPMMR |

4.1. Số dư tài khoản

// Số dư tài khoản cơ sở
const equityBalance = await trading.portfolio.getEquityBalance("1234561");
console.log(`Available cash: ${equityBalance.accountBalance}`);

// Số dư tài khoản phái sinh
const derivativeBalance = await trading.portfolio.getDerivativeBalance("1234568");

4.2. Vị thế (Positions)

// Vị thế cơ sở
const positions = await trading.portfolio.getEquityPositions("1234561");
for (const pos of positions) {
  console.log(`${pos.symbol}: ${pos.quantity} cp | Giá vốn: ${pos.costPrice}`);
}

// Vị thế phái sinh (tất cả vị thế mở/đóng)
const derivativePositions = await trading.portfolio.getDerivativePositions("1234568");

// Chỉ vị thế mở phái sinh
const openPos = await trading.portfolio.getOpenDerivativePositions("1234568");

4.3. Sổ lệnh (Order Book)

// Lệnh trong ngày
const todayOrders = await trading.portfolio.getTodayOrders("1234561");

// Lệnh lịch sử
const historicalOrders = await trading.portfolio.getHistoricalOrders(
  "1234561",
  "2025/01/01",
  "2025/01/31"
);

4.4. PPMMR (Purchasing Power / Margin Maintenance Ratio)

// PPMMR cơ sở
const equityPpmmr = await trading.portfolio.getEquityPpmmr("1234561");
console.log(`Purchasing power: ${equityPpmmr.purchasingPower}`);

// PPMMR phái sinh
const derivativePpmmr = await trading.portfolio.getDerivativePpmmr("1234568");

5. Giao dịch

Truy cập qua trading.trading (client Trading).

Tổng quan method

| Nhóm | Method | Trả về | |------|--------|--------| | Đặt lệnh | placeOrder(accountNo, symbol, side, quantity, price, orderType) | PlaceOrderResponse | | | placeLimitOrder(accountNo, symbol, side, quantity, price) | PlaceOrderResponse | | | placeMarketOrder(accountNo, symbol, side, quantity) | PlaceOrderResponse | | | placeAtoOrder(accountNo, symbol, side, quantity) | PlaceOrderResponse | | | placeAtcOrder(accountNo, symbol, side, quantity) | PlaceOrderResponse | | Sửa lệnh | modifyOrderPrice(accountNo, clientRequestId, price) | ModifyOrderResponse | | | modifyOrderPriceByOrderId(accountNo, orderId, price) | ModifyOrderResponse | | | modifyOrderQuantity(accountNo, clientRequestId, quantity) | ModifyOrderResponse | | | modifyOrderQuantityByOrderId(accountNo, orderId, quantity) | ModifyOrderResponse | | Huỷ lệnh | cancelOrder(accountNo, clientRequestId) | CancelOrderResponse | | | cancelOrderById(accountNo, orderId) | CancelOrderResponse | | Batch | placeBatchOrders(orders) | BatchOrderResponse | | | cancelBatchOrders(orders) | BatchOrderResponse | | Sức mua/bán | getMaxBuySell(accountNo, symbol, price) | MaxBuySellResponse | | | getMaxBuySellAtMarketPrice(accountNo, symbol) | MaxBuySellResponse |

5.1. Đặt lệnh

Mọi method place* nhận thêm clientRequestId (tuỳ chọn, tối đa 20 ký tự) làm idempotency key. Lệnh chỉ được gửi một lần: SDK không bao giờ tự retry khi timeout. Gặp lỗi mạng thì tra sổ lệnh theo clientRequestId trước khi gửi lại. Giá gửi đi là chuỗi thập phân thường (không dạng mũ); quantity phải là số nguyên dương; lệnh LO thiếu giá bị từ chối. Tên cũ modifyOrderPriceById / modifyOrderQuantityById vẫn chạy nhưng đã deprecated.

import { OrderSide, OrderType } from '@ssi.developer/ssi-sdk';

// Lệnh giới hạn (LO)
const result = await trading.trading.placeLimitOrder(
  "1234561",
  "SSI",
  OrderSide.BUY,
  100,
  66000
);
console.log(`Order ID: ${result.orderId}, Status: ${result.status}`);

// Lệnh thị trường (MTL)
const marketOrder = await trading.trading.placeMarketOrder(
  "1234561",
  "SSI",
  OrderSide.BUY,
  100
);

Loại lệnh (OrderType):

| Giá trị | Mô tả | |---------|-------| | OrderType.LO | Lệnh giới hạn (Limit Order) | | OrderType.MTL | Lệnh thị trường (Market To Limit) | | OrderType.MP | Lệnh thị trường (Market Price) | | OrderType.ATO | Lệnh mở cửa (At The Open) | | OrderType.ATC | Lệnh đóng cửa (At The Close) | | OrderType.MOK | Match Or Kill | | OrderType.MAK | Match And Kill | | OrderType.PLO | Post Lunch Order |

5.2. Sửa lệnh

Chỉ có thể sửa giá hoặc số lượng (không đồng thời).

// Sửa giá theo orderId
const result = await trading.trading.modifyOrderPriceByOrderId(
  "1234561",
  "ORD123",
  68000
);

5.3. Huỷ lệnh

// Huỷ lệnh theo orderId
const result = await trading.trading.cancelOrderById("1234561", "ORD123");

5.3a. Lệnh batch

const res = await trading.trading.placeBatchOrders([
  { accountNo: "1234561", symbol: "SSI", side: OrderSide.BUY, quantity: 100, price: 25000, orderType: OrderType.LO },
  { accountNo: "1234561", symbol: "HPG", side: OrderSide.BUY, quantity: 200, price: 27000, orderType: OrderType.LO },
]);
await trading.trading.cancelBatchOrders([{ accountNo: "1234561", orderId: "ORD123" }]);

Tối đa Config.maxBatchOrders (mặc định 20) lệnh mỗi request, ký trên toàn bộ body; một lệnh sai thì cả batch bị từ chối. Khi huỷ, mỗi phần tử cần orderId hoặc clientRequestId.

5.4. Sức mua/bán tối đa

const maxBS = await trading.trading.getMaxBuySell("1234561", "SSI", 66000);
console.log(`Max buy: ${maxBS.maxBuyQuantity}`);

5.5. Lệnh điều kiện (Flexible Conditional Orders - FCO)

SDK hỗ trợ 7 loại lệnh điều kiện linh hoạt FCO, tra cứu danh sách lệnh FCO, nhật ký sổ lệnh FCO và hủy lệnh FCO:

import { FCOOperator, FCOStatus, OrderSide, OrderType, fromBeginningOfDay, fromEndOfDay } from '@ssi.developer/ssi-sdk';

const accountNo = "1234561";
const fromDate = fromBeginningOfDay(); // "YYYY/MM/DD 00:00:00"
const toDate = fromEndOfDay();           // "YYYY/MM/DD 23:59:59"

// 1. Đặt lệnh GTD (Good Till Date)
const gtd = await trading.trading.placeFcoGtd(
  accountNo, "SSI", OrderSide.BUY, 100, 25000, 500, fromDate, toDate
);
console.log(`FCO ID: ${gtd.fcoId}`);

// 2. Đặt lệnh Stop Market
const stop = await trading.trading.placeFcoStop(
  accountNo, "SSI", OrderSide.SELL, 100, 24000, FCOOperator.LESSER_OR_EQUAL, fromDate, toDate
);

// 3. Đặt lệnh Stop Limit
const stopLimit = await trading.trading.placeFcoStopLimit(
  accountNo, "SSI", OrderSide.BUY, 100, 25500, 500, 25000, FCOOperator.GREATER_OR_EQUAL, fromDate, toDate
);

// 4. Đặt lệnh Trailing Stop
const trailing = await trading.trading.placeFcoTrailingStop(
  accountNo, "SSI", OrderSide.BUY, 100, 26000, 1000, fromDate, toDate
);

// 5. Đặt lệnh OCO (One-Cancels-the-Other)
const oco = await trading.trading.placeFcoOco(
  accountNo, "SSI", OrderSide.SELL, 100, 30000, 24000, OrderType.MTL, OrderType.MTL, 500, 500, fromDate, toDate
);

// 6. Tra cứu danh sách lệnh FCO
const fcoList = await trading.trading.getFcoByAccountNo(accountNo, 1, 10);
console.log(`FCO items: ${fcoList.fcoList.length}`);

// 7. Hủy lệnh FCO
await trading.trading.cancelFco(gtd.fcoId);

| Method | Mô tả | |--------|-------| | placeFcoGtd(...) | Đặt lệnh GTD (Good Till Date) | | placeFcoStop(...) | Đặt lệnh Stop Market | | placeFcoStopLimit(...) | Đặt lệnh Stop Limit | | placeFcoTrailingStop(...) | Đặt lệnh Trailing Stop Market | | placeFcoTrailingStopLimit(...) | Đặt lệnh Trailing Stop Limit | | placeFcoOco(...) | Đặt lệnh OCO (One Cancels the Other) | | placeFcoBullBear(...) | Đặt lệnh Bull Bear | | cancelFco(fcoId, code?) | Hủy lệnh FCO theo fcoId | | getFcoByAccountNo(...) | Tra cứu danh sách FCO theo tài khoản | | getFcoBySymbol(...) | Tra cứu FCO lọc theo mã chứng khoán | | getFcoByStatus(...) | Tra cứu FCO lọc theo trạng thái | | getFcoByDate(...) | Tra cứu FCO lọc theo khoảng ngày | | getFcoById(...) | Lấy thông tin 1 lệnh FCO theo ID | | getFcoOrderBook(...) | Lấy lịch sử thực thi (Order Book) của FCO | | getFcoStatusHistory(fcoId) | Các lần chuyển trạng thái của FCO |

Các method placeFco* nhận tham số cuối code? (OTP, tuỳ chọn). Ngày FCO phải dạng YYYY/MM/DD HH:MM:SS, from <= to, cửa sổ tối đa 31 ngày.


6. Streaming realtime

Truy cập qua stream.streaming (client Stream). Cần gọi await stream.streaming.connect() trước.

Tổng quan method

| Nhóm | Method | Mô tả | |------|--------|-------| | Kết nối | connect() | Kết nối WebSocket | | | disconnect() | Ngắt kết nối (async, dừng luôn vòng ping) | | | wait() | Chờ nhận dữ liệu (block) | | Heartbeat | ping(onResponse?, intervalMs?) | Ping server | | Subscribe mã | subscribeSymbol(symbols, onResponse?) | Trade + Quote + Room | | | subscribeSymbolTrade(symbols, onResponse?) | Chỉ trade | | | subscribeSymbolQuote(symbols, onResponse?) | Chỉ quote (bid/ask) | | | subscribeSymbolRoom(symbols, onResponse?) | Chỉ foreign room | | | subscribeSymbolPutThrough(symbols, onResponse?) | Chỉ thoả thuận | | | subscribeSymbolOddLot(symbols, onResponse?) | Chỉ lô lẻ | | | subscribeSymbolOhlcv(symbols, interval, onResponse?) | OHLCV theo timeframe | | Subscribe sàn/chỉ số | subscribeBoard(boards, onResponse?) | Theo sàn | | | subscribeIndex(indices, onResponse?) | Theo chỉ số | | Subscribe giao dịch | subscribeOrderStatus(accountNo?, onResponse?) | Trạng thái lệnh thường & FCO | | | subscribePortfolio(accountNo?, onResponse?) | Portfolio changes | | Subscribe khác | subscribeMarket(symbols, onResponse?) | Kênh market theo mã | | | subscribeMarketFlag(onResponse?) | Cờ phiên (ATO, LO, ATC...) | | | subscribeIndexTrade(indices, interval?, onResponse?) | Tick của chỉ số | | | subscribeIndexSummary(indices, onResponse?) | Tổng hợp chỉ số | | Truy vấn | listSubscription(timeoutMs?) | Các topic đang đăng ký | | Unsubscribe | unsubscribeSymbol(symbols) | Huỷ tất cả kênh cho mã | | | unsubscribeSymbolTrade(symbols) | Huỷ trade | | | unsubscribeSymbolQuote(symbols) | Huỷ quote | | | unsubscribeSymbolRoom(symbols) | Huỷ foreign room | | | unsubscribeSymbolPutThrough(symbols) | Huỷ thoả thuận | | | unsubscribeSymbolOddLot(symbols) | Huỷ lô lẻ | | | unsubscribeBoard(boards) | Huỷ sàn | | | unsubscribeIndex(indices) | Huỷ chỉ số | | | unsubscribeOrderStatus(accountNo?), unsubscribePortfolio(accountNo?) | Huỷ lệnh / portfolio | | | unsubscribeMarket, unsubscribeMarketFlag, unsubscribeIndexTrade, unsubscribeIndexSummary | Huỷ các kênh tương ứng | | | unsubscribeAll() | Huỷ mọi đăng ký của kết nối |

Tất cả subscribe* / unsubscribe* / disconnect() trả về Promise: luôn await để bắt lỗi validate và lỗi gửi (không await thì lỗi thành unhandled rejection). Có thêm alias dễ đọc: subscribeTrades, subscribeQuotes, subscribeOrders, subscribeIndexTicks, subscribeMasterData, subscribeSessionFlag... Tên subscribeFcoOrderStatus đã deprecated (dùng subscribeOrderStatus, cùng topic order.<account>).

Kết nối tự reconnect (backoff luỹ thừa có giới hạn, token mới mỗi lần, tự resubscribe); đừng tự tạo lại kết nối khi rớt. Trạng thái: isConnected, reconnectCount, lastError. Topic interval chỉ nhận tick, 1m, 5m; buildTopic / buildTopics tạo topic đã validate. subscribeBoard/subscribeIndex gửi trade.<mã>@* (+ quote, room): server chỉ rải sàn/rổ chỉ số ra các mã thành phần khi có @*. Mỗi topic chỉ một mã (hoặc khoảng A-B); danh sách VNM,FPT trong một topic bị ValidationError vì server không tách dấu phẩy.

Callbacks:

  • onData: (msg: DataMessage) => void — Nhận market data (tự động phân loại type)
  • onTrading: (msg: TradingMessage) => void — Nhận sự kiện giao dịch (lệnh/portfolio)
  • onHeartbeat: (msg: HeartbeatMessage) => void — Nhận heartbeat
  • Callback theo loại: onMarketFlag, onIndexSummary, onOrder, onOrderMatch, onPortfolio (onData/onTrading vẫn nhận mọi thứ)
  • onConnection: (event: ConnectionEvent) => void — Trạng thái kết nối (connected, reconnecting, ...)

6.1. Thiết lập callback

stream.streaming.onData = (msg) => {
  console.log('Market data:', msg);
};

stream.streaming.onTrading = (msg) => {
  console.log('Trading data:', msg);
};

stream.streaming.onHeartbeat = (msg) => {
  console.log('Heartbeat status:', msg.status);
};

Các message type nhận được qua onData:

| Topic | Message Type | Mô tả | |-------|-------------|-------| | trade.* | TradeMessage | Dữ liệu khớp lệnh | | trade.*.<timeframe> | IntervalMessage | Dữ liệu OHLCV theo interval | | quote.* | QuoteMessage | Dữ liệu giá (bid/ask) | | room.* | ForeignRoomMessage | Room nước ngoài | | market.* | MarketStatusMessage | Trạng thái thị trường | | put.* | PutMessage | Thoả thuận | | oddlot.* | OddLotMessage | Lô lẻ |

Các message type nhận được qua onTrading:

| Topic / EventType | Message Type | Mô tả | |-------|-------------|-------| | order.* | OrderStatusMessage | Trạng thái lệnh thường | | order.* (eventType: fcoEvent) | FCOOrderUpdateMessage | Sự kiện cập nhật lệnh điều kiện FCO | | portfolio.* | PortfolioMessage | Thay đổi danh mục |

6.2. Subscribe dữ liệu thị trường

// Subscribe tất cả kênh (trade + quote + room) cho mã
await stream.streaming.subscribeSymbol(["SSI", "HPG"]);

// Subscribe từng kênh riêng
await stream.streaming.subscribeSymbolTrade(["SSI"]);
await stream.streaming.subscribeSymbolQuote(["SSI"]);

// Subscribe OHLCV theo interval
import { Timeframe } from '@ssi.developer/ssi-sdk';
await stream.streaming.subscribeSymbolOhlcv(["SSI"], Timeframe.MINUTE_1);

// Subscribe theo sàn
await stream.streaming.subscribeBoard([Board.HOSE]);

6.3. Subscribe giao dịch (order status & portfolio)

// Subscribe tất cả tài khoản
await stream.streaming.subscribeOrderStatus();

// Subscribe portfolio
await stream.streaming.subscribePortfolio();

6.4. Heartbeat

// Ping một lần
await stream.streaming.ping();

// Ping tự động theo interval (30 giây)
await stream.streaming.ping(undefined, 30000);

6.5. Ví dụ streaming hoàn chỉnh

import { Auth, Stream, Timeframe } from '@ssi.developer/ssi-sdk';

async function run() {
  const auth = new Auth({
    clientId: "YOUR_CLIENT_ID",
    apiKey: "YOUR_API_KEY",
    apiSecret: "YOUR_API_SECRET",
  });
  await auth.authenticate("222222");

  const stream = new Stream(auth);
  await stream.streaming.connect();

  stream.streaming.onData = (msg) => console.log('Data:', msg);
  stream.streaming.onTrading = (msg) => console.log('Trading:', msg);

  await stream.streaming.subscribeSymbol(["SSI"]);
  await stream.streaming.subscribeOrderStatus();
  await stream.streaming.ping();

  await stream.streaming.wait();
}

7. Xử lý lỗi

SDK sử dụng hệ thống exception phân cấp:

import { SSIError } from '@ssi.developer/ssi-sdk';

try {
  await auth.authenticate("wrong_otp");
} catch (e) {
  if (e instanceof SSIError) {
    console.log(`Lỗi: ${e.message} (code: ${e.code})`);
  }
}

Các exception:

| Exception | Mô tả | |-----------|-------| | SSIError | Base exception — có message, code, statusCode, responseBody, headers | | AuthenticationError | Xác thực thất bại (sai credentials, token hết hạn). Con trực tiếp của SSIError, cùng cấp với APIError (không phải con của APIError), nên catch (e) { if (e instanceof APIError) } không bắt lỗi xác thực | | APIError | API trả về lỗi | | WebSocketError | Lỗi kết nối hoặc giao tiếp WebSocket | | ValidationError | Lỗi validate input | | RateLimitError | Vượt quá giới hạn request — có thêm statusCode, retryAfterMs (millisecond), limit, remaining, reset | | ConfigurationError | Cấu hình sai (option không tồn tại, URL sai scheme) | | SmartOTPPendingError | Smart OTP chưa được duyệt trên thiết bị (HTTP 202 / 401114); con của AuthenticationError | | SmartOTPRejectedError | Smart OTP không thể thành công nữa (bị từ chối, hết hạn hoặc transaction không tồn tại); con của AuthenticationError | | ReauthenticationRequired | Không refresh được phiên, cần OTP mới; con của AuthenticationError | | DuplicateRequestError | HTTP 409: clientRequestId/batchRequestId đã dùng trong ngày; con của APIError. Lệnh gốc có thể vẫn đang sống, SDK không tự gửi lại với id khác | | TradingWSError | Lỗi của trading WebSocket (con của WebSocketError) |

APIError.code là mã lỗi của server khi body có mã (HTTP status nằm ở statusCode); enum ServerErrorCode liệt kê các mã này. responseBody đã được che thông tin nhạy cảm, nhưng đừng hiển thị nó cho người dùng cuối.


8. Cấu hình nâng cao

Tuỳ chỉnh retry & rate limit

const auth = new Auth({
  clientId: "YOUR_CLIENT_ID",
  apiKey: "YOUR_API_KEY",
  apiSecret: "YOUR_API_SECRET",
  maxRetries: 3,
  retryDelayMs: 1000,
  rateLimitPerSecond: 5,
});

Hành vi rate limit và retry

  • Chỉ request GET được retry khi timeout. POST/PUT/DELETE (xác thực, OTP, đặt/sửa/huỷ lệnh, FCO) chỉ gửi một lần.
  • SDK đọc header X-RateLimit-Limit / X-RateLimit-Remaining của server để giảm tốc (không bao giờ vượt rateLimitPerSecond). Gặp HTTP 429 trên GET thì chờ theo Retry-After (tối đa 3 lần, mỗi lần không quá 30 giây) rồi mới ném RateLimitError. Số liệu gần nhất: auth.restClient.rateLimit.

9. Trading WebSocket

Đặt lệnh và truy vấn qua WebSocket giao dịch (/ws/v3/trading). Trading/Stream không tự kết nối tới nó: bạn phải gọi asyncTradingWs(auth) một cách tường minh. Import từ entry chính:

import { asyncTradingWs } from '@ssi.developer/ssi-sdk';

await auth.ensureAuthenticated(process.env.SSI_OTP);
const ws = await asyncTradingWs(auth);   // kết nối tới Config.tradingWsUrl (wss://)
ws.client.onEvent = (evt) => console.log('event', evt);

await ws.subscribeOrderEvents("1234561");   // đúng 1 tài khoản, không dùng "*"
const ack = await ws.placeOrder("1234561", "SSI", OrderSide.BUY, 100, "25000", OrderType.LO, "my-id-1");
await ws.close();

| Nhóm | Method | |------|--------| | Lệnh | placeOrder, amendOrder, cancelOrder, batchNewOrders, batchCancelOrders | | FCO | placeFco({ kind, params }), cancelFco, listFco, fcoOrderBook, fcoStatusHistory | | Truy vấn | queryPosition, queryMaxBuySell, queryAccountBalance, queryPpmmrAccount, queryOrderBook | | Sự kiện | subscribeOrderEvents, subscribePortfolioEvents, unsubscribe*Events, unsubscribeAllEvents | | Khác | command(method, params), close() |

Lưu ý:

  • Lệnh trả về ack PD; kết quả khớp/từ chối đến qua sự kiện lệnh (client.onEvent).
  • Một lệnh bị timeout không được retry tự động: tra sổ lệnh theo clientRequestId trước khi gửi lại.
  • Chữ ký mặc định "auto": thử base64, nếu server từ chối (401006/401008/401013) thì thử lại một lần bằng hex.
  • placeFco nhận { kind: 'gtd' | 'stop' | 'trailingStop' | 'oco' | 'bullBear', params } (khác Python, nơi chọn theo class).
  • Config.proxy không áp dụng cho WebSocket; cần proxy thì truyền agent qua option của client.

Tài liệu liên quan

  • API_METHODS.md: danh sách đầy đủ method và tham số.
  • CHANGELOG.md: thay đổi theo phiên bản (3.3.0 có thay đổi BREAKING: subscribe*/unsubscribe*/disconnect() của streaming giờ trả Promise).
  • AGENT.md: hướng dẫn cho AI agent và người tích hợp.

API Reference

Enums

Tất cả enum có thể import từ @ssi.developer/ssi-sdk:

import { OrderSide, OrderType, OrderStatus, Board, AccountType, Timeframe } from '@ssi.developer/ssi-sdk';

OrderSide

| Giá trị | Value | Mô tả | |---------|-------|-------| | BUY | "B" | Mua | | SELL | "S" | Bán |

OrderType

| Lớp | Giá trị | Mô tả | |-----|---------|-------| | LO | "LO" | Lệnh giới hạn | | MTL | "MTL" | Market To Limit | | MP | "MP" | Market Price | | ATO | "ATO" | At The Open | | ATC | "ATC" | At The Close | | MOK | "MOK" | Match Or Kill | | MAK | "MAK" | Match And Kill | | PLO | "PLO" | Post Lunch Order |

OrderStatus

| Giá trị | Value | Mô tả | |---------|-------|-------| | PENDING | "PD" | Đang chờ | | PENDING_APPROVAL | "WA" | Chờ duyệt | | READY | "RS" | Sẵn sàng | | SENT | "SD" | Đã gửi | | QUEUED | "QU" | Đã xếp hàng | | FILLED | "FF" | Khớp toàn bộ | | PARTIAL_FILLED | "PF" | Khớp một phần | | PARTIAL_CANCELLED | "FFPC" | Khớp một phần + huỷ phần còn lại | | PENDING_MODIFY | "WM" | Chờ sửa | | PENDING_CANCEL | "WC" | Chờ huỷ | | CANCELLED | "CL" | Đã huỷ | | REJECTED | "RJ" | Bị từ chối | | EXPIRED | "EX" | Hết hạn | | PRE_SESSION | "IAV" | Phiên trước |

Board

| Giá trị | Value | Mô tả | |---------|-------|-------| | HOSE | "HOSE" | Sàn HOSE | | HNX | "HNX" | Sàn HNX | | UPCOM | "UPCOM" | Sàn UPCOM |

AccountType

| Giá trị | Value | Mô tả | |---------|-------|-------| | EQUITY | "Cash" | Tài khoản cơ sở | | EQUITY_MARGIN | "Margin" | Tài khoản ký quỹ | | DERIVATIVE | "Derivative" | Tài khoản phái sinh |

Timeframe

| Giá trị | Value | Mô tả | |---------|-------|-------| | MINUTE_1 | "1m" | 1 phút | | MINUTE_3 | "3m" | 3 phút | | MINUTE_5 | "5m" | 5 phút | | MINUTE_15 | "15m" | 15 phút | | HOUR_1 | "1h" | 1 giờ | | DAY_1 | "1d" | 1 ngày | | WEEK_1 | "1w" | 1 tuần | | MONTH_1 | "1M" | 1 tháng |


Models / Types

Các kiểu dữ liệu (Interfaces/Types) có thể import từ @ssi.developer/ssi-sdk:

Authentication

Token — Kết quả xác thực

| Trường | Kiểu | Mô tả | |--------|------|-------| | accessToken | string | Token truy cập | | tokenType | string | Loại token (thường là "Bearer") | | expiresAt | number | Thời điểm hết hạn (timestamp giây) | | refreshToken | string | Token làm mới | | refreshTokenExpiresAt | number | Thời điểm refresh token hết hạn |

Account

Account — Thông tin tài khoản

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | accountType | AccountType | Loại tài khoản |

Market Data

OHLCData — Dữ liệu nến OHLC

| Trường | Kiểu | Mô tả | |--------|------|-------| | symbol | string | Mã chứng khoán | | tradingDate | string | Ngày giao dịch | | openPrice | number | Giá mở cửa | | highPrice | number | Giá cao nhất | | lowPrice | number | Giá thấp nhất | | closePrice | number | Giá đóng cửa | | volume | number | Khối lượng | | value | number | Giá trị giao dịch |

MarketIndexes — Thông tin chỉ số

| Trường | Kiểu | Mô tả | |--------|------|-------| | index | string | Mã chỉ số | | indexName | string | Tên chỉ số | | board | Board | Sàn |

MarketIndexSummary — Tổng hợp chỉ số

| Trường | Kiểu | Mô tả | |--------|------|-------| | index | string | Mã chỉ số | | board | string | Sàn | | tradingDate | string | Ngày giao dịch | | indexValue | number | Giá trị chỉ số | | indexChange | number | Thay đổi giá | | indexChangePercent | number | Thay đổi giá (%) | | totalTrade | number | Tổng KL giao dịch | | totalTradeValue | number | Tổng giá trị giao dịch | | totalMatch | number | Tổng KL khớp lệnh | | totalMatchValue | number | Tổng giá trị khớp lệnh | | totalDeal | number | Tổng KL thoả thuận | | totalDealValue | number | Tổng giá trị thoả thuận | | totalAdvanceStock | number | Số mã tăng | | totalDeclineStock | number | Số mã giảm | | totalSteadyStock | number | Số mã đứng | | totalCeilingStock | number | Số mã trần | | totalFloorStock | number | Số mã sàn | | totalPropBuy | number | KL mua tự doanh | | totalPropBuyValue | number | Giá trị mua tự doanh | | totalPropSell | number | KL bán tự doanh | | totalPropSellValue | number | Giá trị bán tự doanh |

SecuritiesInfo — Thông tin chứng khoán

| Trường | Kiểu | Mô tả | |--------|------|-------| | symbol | string | Mã chứng khoán | | board | Board | Sàn | | index | string | Chỉ số | | symbolNameVi | string | Tên tiếng Việt | | symbolNameEn | string | Tên tiếng Anh | | lotSize | number | Lô giao dịch | | maturityDate | string | Ngày đáo hạn | | firstTradingDate | string | Ngày giao dịch đầu tiên | | lastTradingDate | string | Ngày giao dịch cuối cùng | | cwUnderlyingSymbol | string | Mã CK cơ sở (CW) | | cwExercisePrice | number | Giá thực hiện (CW) | | cwExecutionRatio | number | Tỷ lệ chuyển đổi (CW) | | listedShares | number | Số CP niêm yết | | icbCode | string | Mã ngành ICB | | icbName | string | Tên ngành ICB | | iIndex | number | Chỉ số I | | iNav | number | NAV (ETF) | | openInterest | number | Khối lượng mở (phái sinh) | | settlementPrice | number | Giá thanh toán (phái sinh) |

SecuritiesSummary — Tổng hợp chứng khoán

| Trường | Kiểu | Mô tả | |--------|------|-------| | symbol | string | Mã chứng khoán | | tradingDate | string | Ngày giao dịch | | priceChange | number | Thay đổi giá | | priceChangePercent | number | Thay đổi giá (%) | | openPrice | number | Giá mở cửa | | highPrice | number | Giá cao nhất | | lowPrice | number | Giá thấp nhất | | closePrice | number | Giá đóng cửa | | averagePrice | number | Giá trung bình | | totalMatch | number | Tổng KL khớp | | totalMatchValue | number | Tổng giá trị khớp | | totalBuy | number | Tổng KL mua | | totalTradeBuy | number | Giá trị mua | | totalSell | number | Tổng KL bán | | totalTradeSell | number | Giá trị bán | | totalForeignBuy | number | KL mua khối ngoại | | totalForeignBuyValue | number | GT mua khối ngoại | | totalForeignSell | number | KL bán khối ngoại | | totalForeignSellValue | number | GT bán khối ngoại | | remainForeignRoom | number | Room ngoại còn lại | | totalForeignRoom | number | Tổng room ngoại | | totalDeal | number | KL giao dịch thỏa thuận | | totalDealValue | number | GT giao dịch thỏa thuận | | openInterest | number | Khối lượng mở (phái sinh) | | settlementPrice | number | Giá thanh toán (phái sinh) |

Portfolio

EquityAccountBalance — Số dư tài khoản cơ sở

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | accountBalance | number | Số dư tài khoản | | totalDebt | number | Tổng nợ | | interestLoan | number | Lãi vay | | overdueFeeLoan | number | Phí vay quá hạn | | withdrawable | number | Tiền rút được | | onHoldCash | number | Tiền tạm giữ | | sellUnmatched | number | Bán chưa khớp | | sellT0 / sellT1 / sellT2 | number | Tiền bán chờ về T+0/T+1/T+2 | | buyUnmatched | number | Mua chưa khớp | | buyT0 / buyT1 / buyT2 | number | Tiền mua chờ khớp T+0/T+1/T+2 | | advanceCashT0 / advanceCashT1 | number | Ứng trước T+0/T+1 | | holdSubscription | number | Giữ đăng ký quyền mua | | dividend | number | Cổ tức chờ về/đã ghi nhận |

DerivativeAccountBalance — Số dư tài khoản phái sinh

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | accountBalance | number | Số dư tài khoản | | fee / commission / interest | number | Phí / Hoa hồng / Lãi | | extInterest | number | Lãi ngoài | | loan | number | Khoản vay | | deliveryAmount | number | Giá trị chuyển giao | | floatingPL / tradingPL / totalPL | number | Lãi lỗ trạng thái / Lãi lỗ thực tế / Tổng lãi lỗ | | withdrawable | number | Số tiền rút được | | cashSSI / cashVSDC | number | Tiền tại SSI / Tiền tại VSDC | | validNonCashSSI / validNonCashVSDC | number | Tài sản phi tiền mặt hợp lệ tại SSI / VSDC | | cashWithdrawableSSI / cashWithdrawableVSDC | number | Tiền rút được tại SSI / VSDC |

EquityPosition — Vị thế cơ sở

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | symbol | string | Mã chứng khoán | | quantity | number | Tổng số lượng | | sellableQuantity | number | Số lượng bán được | | costPrice | number | Giá vốn | | blockQuantity | number | SL phong toả | | dividendQuantity | number | SL cổ tức | | buyingQuantity / boughtQuantity | number | SL chờ mua / đã mua | | sellingQuantity / soldQuantity | number | SL chờ bán / đã bán | | t1SellQuantity / t2SellQuantity | number | SL bán T+1/T+2 | | t1BuyQuantity / t2BuyQuantity | number | SL mua về T+1/T+2 (server trả t1BuyQuantity/t2BuyQuantity) | | mortgageQuantity | number | SL cầm cố | | restrictedQuantity | number | SL hạn chế chuyển nhượng |

DerivativePosition — Vị thế phái sinh

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | symbol | string | Mã hợp đồng | | long / short / net | number | Vị thế mua / bán / ròng | | bidAvgPrice / askAvgPrice | number | Giá trung bình mua / bán | | tradePrice | number | Giá giao dịch | | floatingPL / tradingPL | number | Lãi lỗ trạng thái / Lãi lỗ thực tế |

Order — Thông tin lệnh

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | clientRequestId | string | ID yêu cầu client | | orderId | string | ID lệnh hệ thống | | symbol | string | Mã chứng khoán | | side | OrderSide | Mua/Bán | | orderType | OrderType | Loại lệnh | | price / avgPrice | number | Giá đặt / Giá trung bình khớp | | quantity | number | SL đặt | | osQuantity | number | SL chờ | | filledQuantity | number | SL đã khớp | | cancelQuantity | number | SL đã huỷ | | status | OrderStatus | Trạng thái lệnh | | inputTime / modifyTime | string | Thời gian đặt / sửa | | message | string | Thông báo / Lý do lỗi |

Trading

PlaceOrderResponse — Kết quả đặt lệnh

| Trường | Kiểu | Mô tả | |--------|------|-------| | orderId | string | ID lệnh | | clientRequestId | string | ID yêu cầu client | | status | OrderStatus | Trạng thái |

ModifyOrderResponse — Kết quả sửa lệnh

| Trường | Kiểu | Mô tả | |--------|------|-------| | clientModifyId | string | ID yêu cầu sửa | | orderId | string | ID lệnh | | clientRequestId | string | ID yêu cầu gốc | | status | OrderStatus | Trạng thái |

CancelOrderResponse — Kết quả huỷ lệnh

| Trường | Kiểu | Mô tả | |--------|------|-------| | clientCancelId | string | ID yêu cầu huỷ | | orderId | string | ID lệnh | | clientRequestId | string | ID yêu cầu gốc | | status | OrderStatus | Trạng thái |

MaxBuySellResponse — Sức mua/bán tối đa

| Trường | Kiểu | Mô tả | |--------|------|-------| | accountNo | string | Số tài khoản | | symbol | string | Mã chứng khoán | | maxBuyQuantity | number | SL mua tối đa | | maxSellQuantity | number | SL bán tối đa | | marginRatio | string | Tỷ lệ ký quỹ | | purchasePower | string | Sức mua |

Streaming Messages

TradeMessage — Dữ liệu khớp lệnh

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "trade" | Loại message | | tradingTime | string | Thời gian khớp | | symbol | string | Mã CK | | price | number | Giá khớp | | quantity | number | KL khớp | | side | string | Bên mua/bán ("B", "S", "U") | | totalVolume | number | Tổng khối lượng khớp |

IntervalMessage — Dữ liệu OHLCV theo interval

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "trade" | Loại message | | intervalTime | string | Thời gian interval | | tradingTime | string | Thời gian giao dịch | | symbol | string | Mã CK | | open / high / low / close | number | Giá OHLC | | volume | number | Khối lượng |

QuoteMessage — Dữ liệu giá bid/ask

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "quote" | Loại message | | tradingTime | string | Thời gian | | symbol | string | Mã CK | | bidPrices / bidVolumes | number[] | Giá/KL bid | | askPrices / askVolumes | number[] | Giá/KL ask |

ForeignRoomMessage — Room nước ngoài

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "room" | Loại message | | tradingTime | string | Thời gian | | symbol | string | Mã CK | | totalRoom / currentRoom | number | Tổng room / Room còn lại | | buyQuantity / buyValue | number | KL/Giá trị mua nước ngoài | | sellQuantity / sellValue | number | KL/Giá trị bán nước ngoài |

PutMessage — Thoả thuận

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "put" | Loại message | | tradingTime | string | Thời gian | | symbol | string | Mã CK | | price | number | Giá thoả thuận | | quantity | number | KL thoả thuận | | totalQuantity / totalValue | number | Tổng KL / Tổng giá trị |

OddLotMessage — Lô lẻ

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "oddlot" | Loại message | | tradingTime | string | Thời gian | | symbol | string | Mã CK | | price | number | Giá | | quantity | number | Khối lượng | | bidPrices / bidVolumes | number[] | Giá/KL bid | | askPrices / askVolumes | number[] | Giá/KL ask |

MarketStatusMessage — Trạng thái thị trường

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "market" | Loại message | | market | string | Thị trường | | status | string | Trạng thái | | tradingDate | string | Ngày giao dịch |

OrderStatusMessage — Trạng thái lệnh (streaming)

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "orderEvent" | Loại message | | accountNo | string | Số tài khoản | | clientRequestId / orderId | string | ID yêu cầu / ID lệnh | | symbol | string | Mã CK | | side | OrderSide | Mua/Bán | | orderType | OrderType | Loại lệnh | | price | number | Giá đặt | | quantity / osQuantity / filledQuantity / cancelQuantity | number | SL đặt / chờ / khớp / huỷ | | status | OrderStatus | Trạng thái | | inputTime / modifyTime | string | Thời gian đặt / sửa | | message | string | Thông báo / Lý do lỗi |

PortfolioMessage — Thay đổi danh mục (streaming)

| Trường | Kiểu | Mô tả | |--------|------|-------| | type | "clientPortfolioEvent" | Loại message | | accountNo | string | Số tài khoản | | totalAsset | number | Tổng tài sản | | cashBalance | number | Số dư tiền mặt | | stockValue | number | Giá trị chứng khoán |

HeartbeatMessage — Heartbeat

| Trường | Kiểu | Mô tả | |--------|------|-------| | method | string | Method | | channel | StreamingChannel | Channel | | status | string | Trạng thái | | message | string | Thông báo |


Giấy phép

MIT License. Bản quyền thuộc về SSI Securities Corporation.