Add items to watchlist

curl --request POST \
  --url https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-request-id: <x-request-id>' \
  --header 'x-user-key: <api-key>' \
  --data '
[
  {
    "itemId": 12345,
    "itemType": "Instrument",
    "itemRank": 1,
    "itemAddedReason": "Manual",
    "itemAddedDate": "2023-11-07T05:31:56Z",
    "market": {
      "id": "<string>",
      "symbolName": "<string>",
      "displayName": "<string>",
      "assetTypeId": 123,
      "assetTypeSubCategoryId": 123,
      "exchangeId": 123,
      "hasExpirationDate": true,
      "avatar": {
        "small": "<string>",
        "medium": "<string>",
        "large": "<string>",
        "svg": {
          "url": "<string>",
          "backgroundColor": "<string>",
          "textColor": "<string>"
        }
      }
    }
  }
]
'

import requests

url = "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items"

payload = [
    {
        "itemId": 12345,
        "itemType": "Instrument",
        "itemRank": 1,
        "itemAddedReason": "Manual",
        "itemAddedDate": "2023-11-07T05:31:56Z",
        "market": {
            "id": "<string>",
            "symbolName": "<string>",
            "displayName": "<string>",
            "assetTypeId": 123,
            "assetTypeSubCategoryId": 123,
            "exchangeId": 123,
            "hasExpirationDate": True,
            "avatar": {
                "small": "<string>",
                "medium": "<string>",
                "large": "<string>",
                "svg": {
                    "url": "<string>",
                    "backgroundColor": "<string>",
                    "textColor": "<string>"
                }
            }
        }
    }
]
headers = {
    "x-request-id": "<x-request-id>",
    "x-api-key": "<api-key>",
    "x-user-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-request-id': '<x-request-id>',
    'x-api-key': '<api-key>',
    'x-user-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      itemId: 12345,
      itemType: 'Instrument',
      itemRank: 1,
      itemAddedReason: 'Manual',
      itemAddedDate: '2023-11-07T05:31:56Z',
      market: {
        id: '<string>',
        symbolName: '<string>',
        displayName: '<string>',
        assetTypeId: 123,
        assetTypeSubCategoryId: 123,
        exchangeId: 123,
        hasExpirationDate: true,
        avatar: {
          small: '<string>',
          medium: '<string>',
          large: '<string>',
          svg: {url: '<string>', backgroundColor: '<string>', textColor: '<string>'}
        }
      }
    }
  ])
};

fetch('https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'itemId' => 12345,
        'itemType' => 'Instrument',
        'itemRank' => 1,
        'itemAddedReason' => 'Manual',
        'itemAddedDate' => '2023-11-07T05:31:56Z',
        'market' => [
                'id' => '<string>',
                'symbolName' => '<string>',
                'displayName' => '<string>',
                'assetTypeId' => 123,
                'assetTypeSubCategoryId' => 123,
                'exchangeId' => 123,
                'hasExpirationDate' => true,
                'avatar' => [
                                'small' => '<string>',
                                'medium' => '<string>',
                                'large' => '<string>',
                                'svg' => [
                                                                'url' => '<string>',
                                                                'backgroundColor' => '<string>',
                                                                'textColor' => '<string>'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-request-id: <x-request-id>",
    "x-user-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items"

	payload := strings.NewReader("[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-request-id", "<x-request-id>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("x-user-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items")
  .header("x-request-id", "<x-request-id>")
  .header("x-api-key", "<api-key>")
  .header("x-user-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-request-id"] = '<x-request-id>'
request["x-api-key"] = '<api-key>'
request["x-user-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

Watchlists

Add items to watchlist

Rate limit: 20 requests per 60 seconds. This is a shared quota — the same budget is consumed by a group of related endpoints, so calling any of them reduces what is left for the others (you cannot call each at the full rate independently). Endpoints sharing this quota:

DELETE /api/v1/watchlists/{watchlistId}
DELETE /api/v1/watchlists/{watchlistId}/items
POST /api/v1/watchlists
POST /api/v1/watchlists/default-watchlist/selected-items
POST /api/v1/watchlists/newasdefault-watchlist
PUT /api/v1/watchlists/rank/{watchlistId}
PUT /api/v1/watchlists/setUserSelectedUserDefault/{watchlistId}
PUT /api/v1/watchlists/{watchlistId}
PUT /api/v1/watchlists/{watchlistId}/items

Adds new items to an existing watchlist.

POST

api

watchlists

{watchlistId}

items

Add items to watchlist

curl --request POST \
  --url https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-request-id: <x-request-id>' \
  --header 'x-user-key: <api-key>' \
  --data '
[
  {
    "itemId": 12345,
    "itemType": "Instrument",
    "itemRank": 1,
    "itemAddedReason": "Manual",
    "itemAddedDate": "2023-11-07T05:31:56Z",
    "market": {
      "id": "<string>",
      "symbolName": "<string>",
      "displayName": "<string>",
      "assetTypeId": 123,
      "assetTypeSubCategoryId": 123,
      "exchangeId": 123,
      "hasExpirationDate": true,
      "avatar": {
        "small": "<string>",
        "medium": "<string>",
        "large": "<string>",
        "svg": {
          "url": "<string>",
          "backgroundColor": "<string>",
          "textColor": "<string>"
        }
      }
    }
  }
]
'

import requests

url = "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items"

payload = [
    {
        "itemId": 12345,
        "itemType": "Instrument",
        "itemRank": 1,
        "itemAddedReason": "Manual",
        "itemAddedDate": "2023-11-07T05:31:56Z",
        "market": {
            "id": "<string>",
            "symbolName": "<string>",
            "displayName": "<string>",
            "assetTypeId": 123,
            "assetTypeSubCategoryId": 123,
            "exchangeId": 123,
            "hasExpirationDate": True,
            "avatar": {
                "small": "<string>",
                "medium": "<string>",
                "large": "<string>",
                "svg": {
                    "url": "<string>",
                    "backgroundColor": "<string>",
                    "textColor": "<string>"
                }
            }
        }
    }
]
headers = {
    "x-request-id": "<x-request-id>",
    "x-api-key": "<api-key>",
    "x-user-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-request-id': '<x-request-id>',
    'x-api-key': '<api-key>',
    'x-user-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      itemId: 12345,
      itemType: 'Instrument',
      itemRank: 1,
      itemAddedReason: 'Manual',
      itemAddedDate: '2023-11-07T05:31:56Z',
      market: {
        id: '<string>',
        symbolName: '<string>',
        displayName: '<string>',
        assetTypeId: 123,
        assetTypeSubCategoryId: 123,
        exchangeId: 123,
        hasExpirationDate: true,
        avatar: {
          small: '<string>',
          medium: '<string>',
          large: '<string>',
          svg: {url: '<string>', backgroundColor: '<string>', textColor: '<string>'}
        }
      }
    }
  ])
};

fetch('https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'itemId' => 12345,
        'itemType' => 'Instrument',
        'itemRank' => 1,
        'itemAddedReason' => 'Manual',
        'itemAddedDate' => '2023-11-07T05:31:56Z',
        'market' => [
                'id' => '<string>',
                'symbolName' => '<string>',
                'displayName' => '<string>',
                'assetTypeId' => 123,
                'assetTypeSubCategoryId' => 123,
                'exchangeId' => 123,
                'hasExpirationDate' => true,
                'avatar' => [
                                'small' => '<string>',
                                'medium' => '<string>',
                                'large' => '<string>',
                                'svg' => [
                                                                'url' => '<string>',
                                                                'backgroundColor' => '<string>',
                                                                'textColor' => '<string>'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>",
    "x-request-id: <x-request-id>",
    "x-user-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items"

	payload := strings.NewReader("[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-request-id", "<x-request-id>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("x-user-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items")
  .header("x-request-id", "<x-request-id>")
  .header("x-api-key", "<api-key>")
  .header("x-user-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public-api.etoro.com/api/v1/watchlists/{watchlistId}/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-request-id"] = '<x-request-id>'
request["x-api-key"] = '<api-key>'
request["x-user-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"itemId\": 12345,\n    \"itemType\": \"Instrument\",\n    \"itemRank\": 1,\n    \"itemAddedReason\": \"Manual\",\n    \"itemAddedDate\": \"2023-11-07T05:31:56Z\",\n    \"market\": {\n      \"id\": \"<string>\",\n      \"symbolName\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"assetTypeId\": 123,\n      \"assetTypeSubCategoryId\": 123,\n      \"exchangeId\": 123,\n      \"hasExpirationDate\": true,\n      \"avatar\": {\n        \"small\": \"<string>\",\n        \"medium\": \"<string>\",\n        \"large\": \"<string>\",\n        \"svg\": {\n          \"url\": \"<string>\",\n          \"backgroundColor\": \"<string>\",\n          \"textColor\": \"<string>\"\n        }\n      }\n    }\n  }\n]"

response = http.request(request)
puts response.read_body

Authorizations

x-api-key

string

header

default:lhgfaslk21490FAScVPkdsb53F9dNkfHG4faZSG5vfjndfcfgdssdgsdHF4663

required

API key of the application. Only valid together with the x-user-key header — the pair is an alternative to OAuth bearer authentication, never sent alongside it. The pair is granted the same permissions the operation's OAuth scopes describe.

Demo credential for trying the API from these docs: lhgfaslk21490FAScVPkdsb53F9dNkfHG4faZSG5vfjndfcfgdssdgsdHF4663

x-user-key

string

header

default:eyJlYW4iOiJVbnJlZ2lzdGVyZWRBcHBsaWNhdGlvbiIsImVrIjoiOE5sZ2cwcW5EUVdROUFNWGpXT2lmOWktZnpidG5KcUlqWGJ3WHJZZkpZcldrbG90ZEhvLVBjSWhQaU8xU1ZtMW84aU1WZGZqN2xWNzFjLXFxLmcybXE1dnh4Q1hUT25xaWRUaTFlcEhmVk1fIn0_

required

User-specific authentication key. Only valid together with the x-api-key header — the pair is an alternative to OAuth bearer authentication, never sent alongside it.

Demo credential for trying the API from these docs: eyJlYW4iOiJVbnJlZ2lzdGVyZWRBcHBsaWNhdGlvbiIsImVrIjoiOE5sZ2cwcW5EUVdROUFNWGpXT2lmOWktZnpidG5KcUlqWGJ3WHJZZkpZcldrbG90ZEhvLVBjSWhQaU8xU1ZtMW84aU1WZGZqN2xWNzFjLXFxLmcybXE1dnh4Q1hUT25xaWRUaTFlcEhmVk1fIn0_

Headers

x-request-id

string<uuid>

required

A unique request identifier.

Example:

"89a6f859-e236-4612-9ded-a1786548f701"

Path Parameters

watchlistId

string

required

Unique identifier of the watchlist

Body

application/json

Items to add to the watchlist

itemId

integer<int32>

required

Unique identifier of the financial instrument

Example:

12345

itemType

string

required

Type of the financial instrument (e.g., 'Instrument', 'Person')

Example:

"Instrument"

itemRank

integer<int32>

default:0

Ranking position of the item in the watchlist

Example:

1

itemAddedReason

string

Reason the item was added to the watchlist

Example:

"Manual"

itemAddedDate

string<date-time>

Date and time the item was added

market

object

Market metadata for the instrument when included

Show child attributes

Response

Items added successfully

⌘I

Getting started

Guides

Core API

Deprecated

WebSocket API

Vibe Code

AI Agents

Changelog

Add items to watchlist

Authorizations

Headers

Path Parameters

Body

Response