> ## Documentation Index
> Fetch the complete documentation index at: https://api-portal.etoro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscribe (control channel)

> All client requests share one JSON envelope: `{ "id": "<guid>", "operation": "<Authenticate|Subscribe|Unsubscribe>", "data": { ... } }`. The server answers each request on the same connection with an acknowledgement that echoes the `id` and the `operation`. The `id` is a client-generated GUID used to correlate the request with its acknowledgement.



## AsyncAPI

````yaml api-reference/asyncapi.json connectionSubscribe
id: connectionSubscribe
title: Subscribe (control channel)
description: >-
  All client requests share one JSON envelope: `{ "id": "<guid>", "operation":
  "<Authenticate|Subscribe|Unsubscribe>", "data": { ... } }`. The server answers
  each request on the same connection with an acknowledgement that echoes the
  `id` and the `operation`. The `id` is a client-generated GUID used to
  correlate the request with its acknowledgement.
servers:
  - id: etoro
    protocol: wss
    host: ws.etoro.com
    bindings: []
    variables: []
address: /ws
parameters: []
bindings:
  - protocol: ws
    version: 0.1.0
    value:
      method: GET
    schemaProperties:
      - name: method
        type: string
        description: GET
        required: false
operations:
  - &ref_2
    id: subscribe
    title: Subscribe
    description: Client → server. Subscribe to one or more topics.
    type: send
    messages:
      - &ref_3
        id: subscribeRequest
        contentType: application/json
        payload:
          - name: Subscribe request
            description: Subscribe to one or more topics.
            type: object
            properties:
              - name: id
                type: string
                examples: &ref_0
                  - ed72693c-1545-4fa1-8a10-aca7cf5419a6
                required: true
              - name: operation
                type: string
                enumValues:
                  - Subscribe
                required: true
              - name: data
                type: object
                required: true
                properties:
                  - name: topics
                    type: array
                    description: >-
                      Topics to subscribe to. e.g. `instrument:<instrumentId>`
                      for market rates, or the authenticated user's
                      order/portfolio updates: `private` (or its alias
                      `private:real`) for the real account, `private:demo` for
                      the demo account.
                    required: true
                    properties:
                      - name: item
                        type: string
                        examples: &ref_1
                          - instrument:100000
                          - private
                          - private:real
                          - private:demo
                        required: false
                  - name: snapshot
                    type: boolean
                    description: >-
                      Applies to market-data topics only (e.g. `instrument:*`):
                      when true, the current rate is sent immediately on
                      subscribe. Has no effect on the private topics.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          description: Client request envelope for the Subscribe operation.
          required:
            - id
            - operation
            - data
          properties:
            id:
              type: string
              format: uuid
              examples: *ref_0
              x-parser-schema-id: <anonymous-schema-10>
            operation:
              type: string
              enum:
                - Subscribe
              x-parser-schema-id: <anonymous-schema-11>
            data:
              type: object
              required:
                - topics
              properties:
                topics:
                  type: array
                  description: >-
                    Topics to subscribe to. e.g. `instrument:<instrumentId>` for
                    market rates, or the authenticated user's order/portfolio
                    updates: `private` (or its alias `private:real`) for the
                    real account, `private:demo` for the demo account.
                  items:
                    type: string
                    examples: *ref_1
                    x-parser-schema-id: <anonymous-schema-13>
                  x-parser-schema-id: <anonymous-schema-12>
                snapshot:
                  type: boolean
                  description: >-
                    Applies to market-data topics only (e.g. `instrument:*`):
                    when true, the current rate is sent immediately on
                    subscribe. Has no effect on the private topics.
                  default: false
                  x-parser-schema-id: <anonymous-schema-14>
              x-parser-schema-id: SubscribeData
          x-parser-schema-id: SubscribeEnvelope
        title: Subscribe request
        description: Subscribe to one or more topics.
        example: |-
          {
            "id": "ed72693c-1545-4fa1-8a10-aca7cf5419a6",
            "operation": "Subscribe",
            "data": {
              "topics": [
                "instrument:100000"
              ],
              "snapshot": false
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: subscribeRequest
    bindings: []
    extensions:
      - id: x-parser-unique-object-id
        value: connectionSubscribe
sendOperations: []
receiveOperations:
  - *ref_2
sendMessages: []
receiveMessages:
  - *ref_3
extensions:
  - id: x-parser-unique-object-id
    value: connectionSubscribe
securitySchemes:
  - id: apiKeyPair
    name: apiKeyPair
    type: userPassword
    description: >-
      etoro API credentials, sent as a pair inside the `Authenticate` request's
      `data` object -- `userKey` (the user identifier) and `apiKey` (the secret)
      -- not as an HTTP header. Required before subscribing to the `private`
      topic; public market topics (`instrument:<instrumentId>`) need no
      authentication. Both values come from the API key section of etoro account
      settings, which appears once the account is verified.
    extensions: []

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.