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.
  • In any session, authenticated or not, you can subscribe to events for one or more accounts for which you can provide an API Key signature, 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.
  • All active subscriptions for a session can be found using session.subscriptions.
• 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": "5494febb-d167-46a2-996d-70533eb4d976",
    "method": "userDataStream.subscribe",
    "params": {
        "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
    }
}

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 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:

Name	Type	Mandatory	Description
apiKey	STRING	YES

Response:

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

Unsubscribe from User Data Stream

{
    "id": "5494febb-d167-46a2-996d-70533eb4d976",
    "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:

Name	Type	Mandatory	Description
subscriptionId	INT	NO	When 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": "5494febb-d167-46a2-996d-70533eb4d976",
    "method": "session.subscriptions"
}

Note:

• Users should track the corresponding subscription status of related accounts as needed.

Weight: 2

Parameters: NONE

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": "5494febb-d167-46a2-996d-70533eb4d976",
    "method": "userDataStream.subscribe.signature",
    "params": {
        "timestamp": 1770736694138,
        "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
        "signature": "15af09e41c36f3cc61378c2fbe2c33719a03dd5eba8d0f9206fbda44de717c88"
    }
}

Weight: 2

Parameters:

Name	Type	Mandatory	Description
apiKey	STRING	YES
recvWindow	DECIMAL	NO	Maximum: 60000. Supports up to three decimal places of precision (e.g., 6000.346) so that microseconds may be specified.
timestamp	LONG	YES	Unix timestamp used to sign the request, in milliseconds or microseconds. The value must reflect the current client time and is validated by the server for signed endpoints.
signature	STRING	YES

Data Source: Memory

Response:

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