Skip to main content

User Data Stream requests

User Data Stream subscription​

General information:

  • User Data Stream subscriptions allow you to receive all the events related to a given account on a WebSocket connection.
  • There are 2 ways to start a subscription:
    • If you have an authenticated session, then you can subscribe to events for that authenticated account using userDataStream.subscribe.
    • You can additionally open extra subscriptions for any account for which you have an API Key, using userdataStream.subscribe.signature.
    • You can have only one active subscription for a given account on a given connection.
  • Subscriptions are identified by a subscriptionId which is returned when starting the subscription. That subscriptionId allows you to map the events you receive to a given subscription.
  • Limits
    • A single session supports up to 1,000 active subscriptions simultaneously.
      • Attempting to start a new subscription beyond this limit will result in an error.
      • If your accounts are very active, we suggest not opening too many subscriptions at once, in order to not overload your connection.
    • A single session can handle a maximum of 65,535 total subscriptions over its lifetime.
      • If this limit is reached, you will receive an error and must re-establish a new connection to be able to start new subscriptions.
  • To verify the status of User Data Stream subscriptions, check the userDataStream field in session.status:
    • null - User Data Stream subscriptions are not available on this WebSocket API.
    • true - There is at least one subscription active in this session.
    • false - There are no active subscriptions in this session.

Subscribe to User Data Stream (USER_STREAM)​

{
  "id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
  "method": "userDataStream.subscribe"
}

Subscribe to the User Data Stream in the current WebSocket connection.

Notes:

  • This method requires an authenticated WebSocket connection using Ed25519 keys. Please refer to session.logon.
  • To check the subscription status, use session.status, see the userDataStream flag indicating you have have an active subscription.
  • User Data Stream events are available in both JSON and SBE sessions.
    • Please refer to User Data Streams for the event format details.
    • For SBE, only SBE schema 2:1 or later is supported.

Weight: 2

Parameters: NONE

Response:

{
  "id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
  "status": 200,
  "result": {}
}

Unsubscribe from User Data Stream​

{
  "id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
  "method": "userDataStream.unsubscribe"
}

Stop listening to the User Data Stream in the current WebSocket connection.

Note that session.logout will only close the subscription created with userdataStream.subscribe but not subscriptions opened with userDataStream.subscribe.signature.

Weight: 2

Parameters:

NameTypeMandatoryDescription
subscriptionIdINTNoWhen called with no parameter, this will close all subscriptions.
When called with the subscriptionId parameter, this will attempt to close the subscription with that subscription id, if it exists.

Response:

{
  "id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
  "status": 200,
  "result": {}
}

Listing all subscriptions​

{
  "id": "d3df5a22-88ea-4fe0-9f4e-0fcea5d418b7",
  "method": "session.subscriptions",
  "params": {}
}

Note:

  • Users are expected to track on their side which subscription corresponds to which account.

Weight: 2

Data Source: Memory

Response:

{
  "id": "d3df5a22-88ea-4fe0-9f4e-0fcea5d418b7",
  "status": 200,
  "result": [
    {
      "subscriptionId": 0
    },
    {
      "subscriptionId": 1
    }
  ]
}

Subscribe to User Data Stream through signature subscription (USER_STREAM)​

{
  "id": "d3df8a22-98ea-4fe0-9f4e-0fcea5d418b7",
  "method": "userDataStream.subscribe.signature",
  "params": {
    "apiKey": "mjcKCrJzTU6TChLsnPmgnQJJMR616J4yWvdZWDUeXkk6vL6dLyS7rcVOQlADlVjA",
    "timestamp": 1747385641636,
    "signature": "yN1vWpXb+qoZ3/dGiFs9vmpNdV7e3FxkA+BstzbezDKwObcijvk/CVkWxIwMCtCJbP270R0OempYwEpS6rDZCQ=="
  }
}

Weight: 2

Parameters:

NameTypeMandatoryDescription
apiKeySTRINGYes
timestampLONGYes
signatureSTRINGYes

Data Source: Memory

Response:

{
  "id": "d3df8a22-98ea-4fe0-9f4e-0fcea5d418b7",
  "status": 200,
  "result": {
    "subscriptionId": 0
  }
}

Listen Key Management (Deprecated)​

[!IMPORTANT] These requests have been deprecated, which means we will remove them in the future. Please subscribe to the User Data Stream through the WebSocket API instead.

The following requests manage User Data Stream subscriptions.

Start user data stream (USER_STREAM) (Deprecated)​

{
  "id": "d3df8a61-98ea-4fe0-8f4e-0fcea5d418b0",
  "method": "userDataStream.start",
  "params": {
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
  }
}

Start a new user data stream.

Note: the stream will close in 60 minutes unless userDataStream.ping requests are sent regularly.

Weight: 2

Parameters:

NameTypeMandatoryDescription
apiKeySTRINGYES

Data Source: Memory

Response:

Subscribe to the received listen key on WebSocket Stream afterwards.

{
  "id": "d3df8a61-98ea-4fe0-8f4e-0fcea5d418b0",
  "status": 200,
  "result": {
    "listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP"
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 2
    }
  ]
}

Ping user data stream (USER_STREAM) (Deprecated)​

{
  "id": "815d5fce-0880-4287-a567-80badf004c74",
  "method": "userDataStream.ping",
  "params": {
    "listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP",
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
  }
}

Ping a user data stream to keep it alive.

User data streams close automatically after 60 minutes, even if you're listening to them on WebSocket Streams. In order to keep the stream open, you have to regularly send pings using the userDataStream.ping request.

It is recommended to send a ping once every 30 minutes.

Weight: 2

Parameters:

NameTypeMandatoryDescription
listenKeySTRINGYES
apiKeySTRINGYES

Data Source: Memory

Response:

{
  "id": "815d5fce-0880-4287-a567-80badf004c74",
  "status": 200,
  "response": {},
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 2
    }
  ]
}

Stop user data stream (USER_STREAM) (Deprecated)​

{
  "id": "819e1b1b-8c06-485b-a13e-131326c69599",
  "method": "userDataStream.stop",
  "params": {
    "listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP",
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
  }
}

Explicitly stop and close the user data stream.

Weight: 2

Parameters:

NameTypeMandatoryDescription
listenKeySTRINGYES
apiKeySTRINGYES

Data Source: Memory

Response:

{
  "id": "819e1b1b-8c06-485b-a13e-131326c69599",
  "status": 200,
  "response": {},
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 2
    }
  ]
}