Skip to main content

User Data Stream (listenKey)

Type: USER-STREAM

Weight: 1

POST /fapi/v1/listenKey · PUT /fapi/v1/listenKey · DELETE /fapi/v1/listenKey

Binance-compatible listenKey lifecycle for the private WebSocket channels. All three calls are HMAC-signed (send timestamp + signature even though there are no other parameters).

Flow​

  1. POST /fapi/v1/listenKey → 64-character key.
  2. Connect to wss://api-avax.<sparky-domain>/ws and send {"type":"auth","listenKey":"<key>"}.
  3. On {"type":"auth_result","success":true} subscribe to positions, orders, balance (User data).
  4. Keep-alive: PUT /fapi/v1/listenKey at least once per 60 min — optional while a socket authenticated with the key stays connected, because each lookup refreshes the TTL.
  5. DELETE /fapi/v1/listenKey when done.

Storage is Redis with a 3600 s TTL. Each user has one active key: repeated POSTs return the same key and refresh its TTL.

POST /fapi/v1/listenKey​

{ "listenKey": "a1b2c3d4e5f6…(64 chars)" }

Idempotent.

PUT /fapi/v1/listenKey​

No parameters — the user's current key is implicit.

{ "listenKey": "a1b2c3d4e5f6…" }
HTTPcodemsg
404-1125This listenKey does not exist (no active key — POST first).

DELETE /fapi/v1/listenKey​

{}

Idempotent (returns {} even when no key is active).

There is no wss://…/ws/<listenKey> URL form: the key is always sent in the auth message.

Authentication failures (INVALID_API_KEY, API_KEY_DISABLED, IP_NOT_ALLOWED, SIGNATURE_INVALID) apply to every signed endpoint and use Sparky's {"success":false,"error":{...}} envelope; see Error Codes.