Skip to main content
Version: 1.1.1

General WebSocket API Information

Base Endpoint​

  • The base endpoint for public streams is:
    wss://dev.yimmit.com/api/v3/ranger/public
  • The base endpoint for private (authenticated) streams is:
    wss://dev.yimmit.com/api/v3/ranger/private
  • Streams are selected via the stream query parameter, for example:
    wss://dev.yimmit.com/api/v3/ranger/private/?stream=trade&stream=order

Connection Authentication​

Public Streams​

Public streams can be connected directly without any authentication. Simply connect to the public endpoint:

wss://dev.yimmit.com/api/v3/ranger/public/?stream=ethusdt.trades&stream=ethusdt.ticker

Private Streams​

Private streams require authentication using HTTP headers during the WebSocket handshake. You must include the following headers when establishing the connection:

  • X-Auth-Apikey - Your API key
  • X-Auth-Nonce - A unique nonce (timestamp in milliseconds)
  • X-Auth-Signature - HMAC SHA256 signature

Signature Generation​

The signature is generated using HMAC SHA256 with your secret key:

signature = HMAC-SHA256(secret_key, nonce + api_key)

Where:

  • nonce is the timestamp in milliseconds (same value as X-Auth-Nonce)
  • api_key is your API key (same value as X-Auth-Apikey)

Example Connection Headers​

X-Auth-Apikey: your-api-key-here
X-Auth-Nonce: 1234567890000
X-Auth-Signature: generated-hmac-sha256-signature

Connection Example​

const WebSocket = require('ws');
const crypto = require('crypto');

const apiKey = 'your-api-key';
const secretKey = 'your-secret-key';
const nonce = Date.now();

// Generate signature
const message = `${nonce}${apiKey}`;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(message)
  .digest('hex');

// Connect with authentication headers
const ws = new WebSocket('wss://dev.yimmit.com/api/v3/ranger/private/?stream=trade&stream=order', {
  headers: {
    'X-Auth-Apikey': apiKey,
    'X-Auth-Nonce': nonce.toString(),
    'X-Auth-Signature': signature
  }
});

Connection Management​

  • A single connection to the API is only valid for 24 hours; expect to be disconnected after the 24-hour mark.
  • Before a disconnection either due to maintenance or after 24 hours, a serverShutdown event will be sent. Please reconnect as soon as possible to prevent stream interruption.
  • We support HMAC, RSA, and Ed25519 keys. For more information, please see API Key types.
  • Responses are in JSON by default.

Data and Timestamps​

  • Data is returned in chronological order, unless noted otherwise.
    • Without startTime or endTime, returns the most recent items up to the limit.
    • With startTime, returns oldest items from startTime up to the limit.
    • With endTime, returns most recent items up to endTime and the limit.
    • With both, behaves like startTime but does not exceed endTime.
  • All timestamps in the JSON responses are in milliseconds in UTC by default. To receive the information in microseconds, please add the parameter timeUnit=MICROSECOND or timeUnit=microsecond in the URL.
  • Timestamp parameters (e.g. startTime, endTime, timestamp) can be passed in milliseconds or microseconds.

Character Encoding​

  • If your request contains a symbol name containing non-ASCII characters, then the response may contain non-ASCII characters encoded in UTF-8.
  • Some methods may return asset and/or symbol names containing non-ASCII characters encoded in UTF-8 even if the request did not contain non-ASCII characters.

Field Names and Values​

  • All field names and values are case-sensitive, unless noted otherwise.

API Timeout​

  • APIs have a timeout of 10 seconds when processing a request. If a response from the Matching Engine takes longer than this, the API responds with "Timeout waiting for response from backend server. Send status unknown; execution status unknown." (-1007 TIMEOUT)
  • This does not always mean that the request failed in the Matching Engine.
  • If the status of the request has not appeared in User Data Stream, please perform an API query for its status.

Security​

  • Please avoid SQL keywords in requests as they may trigger a security block by a WAF (Web Application Firewall) rule.