WebSocket API requests
Use WebsocketAPIClient for request/response operations over an authenticated connection. Use WebsocketClient subscriptions separately for ongoing fills and account changes.
Use await and try/catch just as you would with a REST API call. The SDK matches responses to requests and manages the WebSocket connection for you. Requests over a persistent WebSocket can offer lower overhead and latency, depending on the exchange, network and workload.
Cancel an existing Spot order
This example sends a live cancellation. Set KUCOIN_ORDER_ID in .env to an existing BTC-USDT exchange order ID that you intend to cancel. Save this as ws-api.ts beside the credential helper. Follow the compile instructions with ws-api.ts as the entry file:
import { WebsocketAPIClient } from 'kucoin-api';
import { credentials, requiredEnv } from './authenticated-client.js';
async function main() {
const orderId = requiredEnv('KUCOIN_ORDER_ID');
const wsApi = new WebsocketAPIClient({
...credentials,
attachEventListeners: false,
});
wsApi.getWSClient().on('exception', () => {
console.error('WebSocket API connection or request failed.');
});
try {
const result = await wsApi.cancelSpotOrder({ symbol: 'BTC-USDT', orderId });
console.log('Cancellation response:', result.code, result.data.orderId);
console.log(
'Check private updates or REST order status for the final outcome.',
);
} finally {
wsApi.getWSClient().closeAll();
}
}
main().catch(() => {
console.error(
'Cancellation outcome is uncertain. Check order status before retrying.',
);
process.exitCode = 1;
});node --env-file=.env dist/ws-api.jsUse the same account as the original order. This release uses fixed global WebSocket API hosts; apiRegion does not select a regional WebSocket API endpoint. Confirm account access before using this example. The example closes its connection afterward. Check order status through REST or private updates to confirm the cancellation outcome and any fills.
Responses retain the WebSocket API envelope: code, op, data and timing fields. The operation's result is in response.data. Failed requests reject; batch responses still require checking each item.
Available commands
submitNewSpotOrder(),modifySpotOrder()andcancelSpotOrder()manage Spot orders onwsApiSpotV1by default.submitMarginOrder()uses the Spot WebSocket API connection.submitFuturesOrder()and futures cancellation methods usewsApiFuturesV1by default.getWSClient()exposes lifecycle events and shutdown.
The wrapper connects and authenticates as needed. To prepare the Spot connection ahead of time, await getWSClient().connectWSAPI('wsApiSpotV1'). For lower-level requests, use sendWSAPIRequest('wsApiSpotV1', operation, params) on a WebsocketClient.
A long-running service should retain its client rather than reconnecting for every request. There is no supported testnet constructor option. Do not confuse the dedicated command keys with spotPrivateV1 or other subscription connections.
In-flight requests can reject when a connection closes, even if the exchange processed them. Resolve uncertain order outcomes before retrying a trading command.