Authentication

Smart Balance OpenAPI is served through Themis broker with HMAC apiKey authentication. The same credentials and algorithm apply to REST endpoints and WebSocket handshake.

The Signalplus service platform requires partners to sign requests. The platform verifies the signature upon receiving the request. If the signature verification fails, the platform rejects the request and returns a 401 response.

Base URL

REST API:

WebSocket:

Signature Algorithm

content   = `${timestamp}\n${nonce}`
signature = Base64( HmacSHA256( Base64Decode(apiSecret), content.getBytes("UTF-8") ) )

timestamp — current UTC milliseconds as string.

nonce — unique random string per request (UUID recommended).

apiSecret — issued by Signalplus, already Base64-encoded.

Timestamp tolerance: the server rejects requests when |now − timestamp| > 15_000 ms.

REST Headers

WebSocket Query String

WebSocket handshake carries the same four credentials in the connection URL:

wss://<base>/<stage>?apiKey=<apiKey>&signature=<URL-encoded>&nonce=<URL-encoded>&timestamp=<timestamp>

All four parameters are mandatory. signature and nonce must be URL-encoded because they may contain /, +, =.

Signature Example (Kotlin)

val timestamp = System.currentTimeMillis().toString()
val nonce = UUID.randomUUID().toString()
val mac = Mac.getInstance("HmacSHA256")
mac.init(SecretKeySpec(Base64.getDecoder().decode(apiSecret), "HmacSHA256"))
val signature = Base64.getEncoder()
    .encodeToString(mac.doFinal("$timestamp\n$nonce".toByteArray()))

Common Response Envelope

All REST responses wrap the payload in a uniform envelope:

{
  "succ": true,
  "code": 0,
  "message": "",
  "value": { /* endpoint-specific payload */ }
}

Error example:

{
  "succ": false,
  "code": 1000,
  "message": "Invalid signature",
  "value": null
}

Enum Reference

Most numeric fields in Smart Balance payloads are enum codes, not arbitrary integers. Always use the values below.

side

type — order type

orderStatus / legStatus

portfolioStatus (WebSocket push)

kind — instrument kind

tradeMode

positionSide

timeInForce

placePriceLabel / priceLabel — dynamic price reference

totalEndAction

cancelType (order-level, push side)

mode — PortfolioMode (appears in some WS payloads)

String Enums (no numeric encoding)

Rate Limit

Exceeding a rate limit returns HTTP 429.

Error Codes

The numeric code in the response body mirrors the business meaning; HTTP status aligns by convention.

Constraints