Configuration

Full Config parameter reference for Node.js SDK

Config

Config is the central configuration object of the SDK. Create an instance with your credentials:

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',
});

All Configuration Parameters

Parameter	Type	Default	Description
`clientId`	`string`	`""`	Client ID for portfolio operations
`apiKey`	`string`	`""`	API key from SSI
`apiSecret`	`string`	`""`	API secret from SSI
`privateKey`	`string`	`""`	RSA private key for signing trading orders (XML format, base64-encoded)
`apiUrl`	`string`	`"https://api.ssi.com.vn"`	REST API URL
`streamingUrl`	`string`	`"wss://stream.ssi.com.vn/ws/v3"`	WebSocket streaming URL
`tradingApiDomain`	`string`	follows `apiUrl`	REST domain for the trading API. Follows `apiUrl` by default. A bare host gets `https://`. Read the final URL through the getter `config.tradingApiUrl`
`tradingWsDomain`	`string`	`"wss://api.ssi.com.vn/ws/v3/trading"`	Trading WebSocket address (see below). A bare host gets `wss://` and the path. Read the final URL through the getter `config.tradingWsUrl`
`timeoutMs`	`number`	`60000`	Request timeout (ms)
`maxRetries`	`number`	`5`	Maximum retry attempts. Applies to timed-out GET requests only: trading commands (batches included) are never retried
`retryDelayMs`	`number`	`2000`	Base delay between retries (exponential backoff, ms)
`rateLimitPerSecond`	`number`	`10`	Request rate limit per second (0 = unlimited)
`maxBatchOrders`	`number`	`20`	Maximum orders per Batch Orders call. A value that is not an integer >= 1 falls back to the default
`proxy`	`string`	`undefined`	Proxy URL (HTTP or SOCKS5). Not applied to WebSockets
`userAgent`	`string`	`undefined`	User-Agent sent with requests
`autoReconnect`	`boolean`	`true`	Automatically reconnect and re-subscribe for Stream
`otpPollIntervalMs`	`number`	`5000`	Poll interval while waiting for Smart OTP approval (ms)
`otpPollMaxWaitMs`	`number`	`60000`	Maximum wait while polling Smart OTP (ms)
`logLevel`	`string`	`"INFO"`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

All durations are in milliseconds and carry the Ms suffix. The old names timeout and retryDelay were renamed to timeoutMs and retryDelayMs (a breaking rename, with no alias): passing an unknown option throws ConfigurationError. WebSocket URLs (streamingUrl, tradingWsDomain) must be wss://. Secrets (apiKey, apiSecret, privateKey) are masked when you print a Config, and config.toOptions() returns the options so you can build another Config.

Batch size limit (`maxBatchOrders`)

maxBatchOrders limits how many orders one placeBatchOrders / cancelBatchOrders call may carry (and batchNewOrders / batchCancelOrders of the Trading WebSocket). An empty batch, or one over the limit, is rejected locally with ValidationError and no request is sent.

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  privateKey: 'YOUR_PRIVATE_KEY', // required to sign batches
  maxBatchOrders: 20,
});

A note on the number 20: the SDK source says 20 is the server's default (MaxBatchOrderCount), while the API reference states a maximum of 50 orders per batch. The two figures have not been reconciled. The SDK only enforces the limit on the client side and does not ask the server, so the server may still reject a batch the SDK lets through. For batch usage see API Services.

TradingWSClientOptions

Options of the Trading WebSocket, passed through asyncTradingWs(auth, options?), see API Services, section 7. These are options of the WebSocket client, not part of Config. Config only supplies tradingWsDomain and the defaults for requestTimeoutMs and userAgent.

All durations are in milliseconds and carry the Ms suffix.

Option	Type	Default	Description
`requestTimeoutMs`	`number`	`Config.timeoutMs` (60000) via `asyncTradingWs`; 10000 if you build a `TradingWSClient` yourself	How long to wait for a command's response. On expiry it throws `WebSocketError` and is not retried
`signatureEncoding`	`'auto' \| 'base64' \| 'hex'`	`'auto'`	`auto` signs as base64 first and, if the signature is refused, retries exactly once as hex
`handshakeGraceMs`	`number`	`500`	How long to wait for a refusal frame the server sends after accepting the socket
`respectRateLimit`	`boolean`	`true`	Wait automatically when the rate limit is exhausted
`maxRateLimitWaitMs`	`number`	`2000`	Longest wait each time the rate limit is exhausted
`pingIntervalMs`	`number \| null`	`30000`	Keep-alive interval. `null` or `0` disables it
`userAgent`	`string`	`Config.userAgent`	User-Agent sent on connect
`connectFn`, `clock`, `sleepFn`	functions	SDK defaults	Replacements for connecting, reading time and sleeping. Meant for tests, usually not needed

Advanced Configuration

Debug logging

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  logLevel: 'DEBUG',
});

Custom retry & rate limit

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  maxRetries: 3,
  retryDelayMs: 1000,
  rateLimitPerSecond: 5,
});

Proxy

const config = new Config({
  clientId: 'YOUR_CLIENT_ID',
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  proxy: 'http://proxy.example.com:8080',
});

Recommendations

Store credentials (apiKey, apiSecret, privateKey) in environment variables or a secret manager.
Missing apiKey/apiSecret will cause authentication errors.
Missing privateKey will affect order signing operations (place/modify/cancel orders, FCO, batches, and the state-changing commands of the Trading WebSocket).
Set rateLimitPerSecond according to platform policy.
Only enable logLevel: 'DEBUG' in development environments.
Adjust timeoutMs, maxRetries, and retryDelayMs based on actual workload.
proxy is not applied to WebSocket connections (Stream and the Trading WebSocket).

On this page