etoro-apps

# eToro Public API Base URL: `https://public-api.etoro.com/api/v1` ## About This skill allows to interact with the user's eToro account programatically, including executing trades. ## Authentication & Required Headers The eToro API supports **two** authentication methods. Both use the same base URL and endpoints — only the auth headers differ. ### Method 1 — OAuth SSO (Bearer Token) If the user authenticated via **"Login with eToro"** (SSO/OAuth), an `access_token` is available from the token exchange. **Headers (every request):** - `x-request-id`: unique UUID per request - `Authorization`: `Bearer <access_token>` Where `access_token` comes from: 1. User clicks "Login with eToro" → redirects to `https://www.etoro.com/sso/` with PKCE challenge. 2. User authenticates on eToro's side. 3. eToro redirects back with an authorization `code`. 4. The code is exchanged for tokens via `POST https://www.etoro.com/sso/oidc/token`: - `grant_type=authorization_code` - `code=<auth_code>` - `redirect_uri=<callback_url>` - `code_verifier=<pkce_verifier>` - Plus `Authorization: Basic <base64(client_id:client_secret)>` header 5. Response contains: - `access_token` — **this is the Bearer token for API calls** (~2130 chars, JWT) - `id_token` — JWT with user identity (`sub` claim = 128-char encoded user ID) - `token_type`: `"Bearer"` - `expires_in`: (varies) Example: ```bash curl -X GET "https://public-api.etoro.com/api/v1/watchlists" \ -H "x-request-id: <UUID>" \ -H "Authorization: Bearer <access_token>" ``` ### Method 2 — Manual API Keys If the user provides API keys manually (no OAuth), use key-based auth. **Keys (request from the user on install)** - **Public API Key**: application - **User Key**: user account - **Environment**: Real Portfolio or Virtual Portfolio (real/demo) **Key generation (user-facing):** 1. Log in to eToro. 2. Settings > Trading. 3. Create New Key. 4. Choose **Environment** (Real or Virtual/Demo) and **Permissions** (Read or Write). 5. Verify identity and copy the generated User Key. **Headers (every request):** - `x-request-id`: unique UUID per request - `x-api-key`: Public API Key (`<PUBLIC_KEY>`) - `x-user-key`: User Key (`<USER_KEY>`) Example: ```bash curl -X GET "https://public-api.etoro.com/api/v1/watchlists" \ -H "x-request-id: <UUID>" \ -H "x-api-key: <PUBLIC_KEY>" \ -H "x-user-key: <USER_KEY>" ``` ### Choosing the Auth Method in Code When making requests, check which credentials are available: ```typescript if (ctx.accessToken) { // SSO auth — Bearer token from OAuth token exchange headers["Authorization"] = `Bearer ${ctx.accessToken}`; } else { // Manual API key auth headers["x-api-key"] = ctx.apiKey; headers["x-user-key"] = ctx.userKey; } ``` ## Request Conventions - **All paths below are relative to the Base URL** (which already includes `/api/v1`). Example: `GET /watchlists` means `GET https://public-api.etoro.com/api/v1/watchlists`. - Query params go in the URL, path params go in the URL path. - For query params that are documented as `array`, send them as **comma-separated values** (e.g., `instrumentIds=1001,1002`). - Pagination patterns vary by endpoint: - Search: `pageNumber`, `pageSize` - People search & trade history: `page`, `pageSize` - Feeds: `take`, `offset` - Watchlist items listing: `pageNumber`, `itemsPerPage` - **Casing matters** for request bodies: - Trading execution uses **PascalCase** fields (e.g., `InstrumentID`, `IsBuy`, `Leverage`). - Market close body uses `InstrumentId` (capital I, lowercase d). - Watchlist items use `ItemId`, `ItemType`, `ItemRank`. - Feeds post body uses lower camel (`owner`, `message`, `tags`, `mentions`, `attachments`). - Some responses may use different casing for similar concepts (e.g., `instrumentId` vs `InstrumentID`). When extracting IDs, handle both if present. ## Demo vs Real Trading - Use **demo execution endpoints** (contain `/demo/`) for testing and paper trading. - Use **non-demo execution endpoints** for real trading. - For portfolio/PnL: - Demo: `/trading/info/demo/*` - Real: `/trading/info/portfolio` and `/trading/info/real/pnl` - Ensure your key environment matches the endpoint (Virtual vs Real). Each User Key is associated with a specific environment. ## Use Defaults - Important: You don't need to specify all parameters. If the user doesn't specify leverage for example, don't send it on the API request. ## Quick Start (Demo Trade) 1. **Resolve `instrumentId`** using search. `fields` is required on search requests. ```bash curl -X GET "https://public-api.etoro.com/api/v1/market-data/search?internalSymbolFull=BTC&fields=instrumentId,internalSymbolFull,displayname" \ -H "Authorization: Bearer <access_token>" \ -H "x-request-id: <UUID>" ``` 2. **Place a demo market order by amount** (PascalCase body): ```bash curl -X POST "https://public-api.etoro.com/api/v1/trading/execution/demo/market-open-orders/by-amount" \ -H "Authorization: Bearer <access_token>" \ -H "x-request-id: <UUID>" \ -H "Content-Type: application/json" \ -d '{ "InstrumentID": 100000, "IsBuy": true, "Leverage": 1, "Amount": 100 }' ``` > **Note:** The examples above use OAuth (Bearer token). For API key auth, replace the `Authorization` header with `x-api-key` and `x-user-key` headers instead. ## Common IDs - `instrumentId`: from Search or Instruments metadata - `positionId`: from Portfolio endpoints - `orderId`: from execution responses or Portfolio endpoints - `marketId`: used by instrument feed endpoints (typically available in instrument metadata/search fields) - `userId`: numeric eToro user ID (often referred to as **CID** in responses; discover via People endpoints/search) - `watchlistId`: from watchlists list/create endpoints ## Market Data (Requests) **Search instruments** - `GET /market-data/search` - Required query: `fields` (comma-separated list of instrument fields to return) - Optional: `searchText`, `pageSize`, `pageNumber`, `sort` - The Search endpoint supports filtering by fields returned in results; for exact symbol lookup, use `internalSymbolFull` as a query param and verify the exact match. - Recommended minimal `fields` when you need IDs: include the instrument identifier (may appear as `instrumentId` or `InstrumentID`), plus `internalSymbolFull` and `displayname` (and `marketId` if you plan to use Feeds). **Metadata** - `GET /market-data/instruments` Filters: `instrumentIds`, `exchangeIds`, `stocksIndustryIds`, `instrumentTypeIds`. **Prices & history** - `GET /market-data/instruments/rates` Required: `instrumentIds` (comma-separated). - `GET /market-data/instruments/history/closing-price` Returns historical closing prices for all instruments (bulk). - `GET /market-data/instruments/{instrumentId}/history/candles/{direction}/{interval}/{candlesCount}` `direction`: `asc` or `desc`. `candlesCount` max 1000. Use only supported `interval` values (confirm via docs if unsure). **Reference data** - `GET /market-data/exchanges` (optional `exchangeIds`) - `GET /market-data/instrument-types` - `GET /market-data/stocks-industries` (optional `stocksIndustryIds`) ## Trading Execution (Requests) > Requires appropriate permissions (typically **Write**) and the correct environment (Demo vs Real). ### Market Open Orders (by amount) Endpoints: - `POST /trading/execution/demo/market-open-orders/by-amount` - `POST /trading/execution/market-open-orders/by-amount` Body (PascalCase, JSON): - **Required:** `InstrumentID`, `IsBuy`, `Leverage`, `Amount` - **Optional:** `StopLossRate`, `TakeProfitRate`, `IsTslEnabled`, `IsNoStopLoss`, `IsNoTakeProfit` ### Market Open Orders (by units) Endpoints: - `POST /trading/execution/demo/market-open-orders/by-units` - `POST /trading/execution/market-open-orders/by-units` Body (PascalCase, JSON): - **Required:** `InstrumentID`, `IsBuy`, `Leverage`, `AmountInUnits` - **Optional:** `StopLossRate`, `TakeProfitRate`, `IsTslEnabled`, `IsNoStopLoss`, `IsNoTakeProfit` ### Cancel Market Open Orders Endpoints: - `DELETE /trading/execution/demo/market-open-orders/{orderId}` - `DELETE /trading/execution/market-open-orders/{orderId}` ### Market Close Orders Endpoints: - `POST /trading/execution/demo/market-close-orders/positions/{positionId}` - `POST /trading/execution/market-close-orders/positions/{positionId}` - `DELETE /trading/execution/demo/market-close-orders/{orderId}` - `DELETE /trading/execution/market-close-orders/{orderId}` Body (JSON): - **Required:** `InstrumentId` - **Optional:** `UnitsToDeduct` (number or `null`) Partial close: set `UnitsToDeduct`. Full close: set `UnitsToDeduct` to `null`. You must close by `positionId`, not by symbol. ### Market-if-touched (Limit) Orders Endpoints: - `POST /trading/execution/demo/limit-orders` - `DELETE /trading/execution/demo/limit-orders/{orderId}` - `POST /trading/execution/limit-orders` - `DELETE /trading/execution/limit-orders/{orderId}` Body (PascalCase, JSON): - **Required:** `InstrumentID`, `IsBuy`, `Leverage`, **`Rate`**, and **one of** `Amount` **or** `AmountInUnits` - **Optional:** `StopLossRate`, `TakeProfitRate`, `IsTslEnabled`, `IsNoStopLoss`, `IsNoTakeProfit` - **Do not send:** `IsDiscounted`, `CID` ## Trading Info & Portfolio (Requests) - `GET /trading/info/demo/pnl` - `GET /trading/info/real/pnl` - `GET /trading/info/demo/portfolio` - `GET /trading/info/portfolio` Use these to discover `positionId` and `orderId` for close/cancel flows. - `GET /trading/info/trade/history` Required: `minDate` (YYYY-MM-DD). Optional: `page`, `pageSize`. ## Watchlists (Requests) **User watchlists** - `GET /watchlists` Optional: `itemsPerPageForSingle`, `ensureBuiltinWatchlists`, `addRelatedAssets`. - `GET /watchlists/{watchlistId}` Optional: `pageNumber`, `itemsPerPage`. - `POST /watchlists` Query: `name` (required), `type`, `dynamicQuery` (optional). (Uses query params, not a JSON body.) - `PUT /watchlists/{watchlistId}` Query: `newName` (required). (Uses query params, not a JSON body.) - `DELETE /watchlists/{watchlistId}` **Watchlist items (body schema)** `WatchlistItemDto` fields: - `ItemId` (required, int) - `ItemType` (required, string: `Instrument` or `Person`) - `ItemRank` (optional, int) Endpoints: - `POST /watchlists/{watchlistId}/items` - `PUT /watchlists/{watchlistId}/items` - `DELETE /watchlists/{watchlistId}/items` Example body: ```json [ { "ItemId": 12345, "ItemType": "Instrument", "ItemRank": 1 }, { "ItemId": 67890, "ItemType": "Instrument", "ItemRank": 2 } ] ``` **Default watchlists** - `POST /watchlists/default-watchlist/selected-items` - `GET /watchlists/default-watchlists/items` Optional: `itemsLimit`, `itemsPerPage`. - `POST /watchlists/newasdefault-watchlist` Query: `name` (required), `type`, `dynamicQuery` (optional). - `PUT /watchlists/setUserSelectedUserDefault/{watchlistId}` - `PUT /watchlists/rank/{watchlistId}` Query: `newRank` (required). **Public watchlists** - `GET /watchlists/public/{userId}` - `GET /watchlists/public/{userId}/{watchlistId}` ## Feeds (Requests) **Read feeds** - `GET /feeds/instrument/{marketId}` Optional: `requesterUserId`, `take`, `offset`, `badgesExperimentIsEnabled`, `reactionsPageSize`. - `GET /feeds/user/{userId}` Optional: `requesterUserId`, `take`, `offset`, `badgesExperimentIsEnabled`, `reactionsPageSize`. Notes: - `marketId` is associated with an instrument (typically available via instrument metadata/search if you include it in `fields`). - `userId` is a numeric user identifier (CID). If you only have a username, discover the numeric ID via People endpoints (see User Info & Analytics). **Create post** - `POST /feeds/post` - Body fields (lower camel, JSON): - `owner` (int) - `message` (string) - `tags`: `{ "tags": [{ "name": "...", "id": "..." }] }` - `mentions`: `{ "mentions": [{ "userName": "...", "id": "...", "isD irect": true }] }` - `attachments`: array of objects with `url`, `title`, `host`, `description`, `mediaType`, and optional `media`. Minimal example: ```json { "message": "Hello eToro feed!" } ``` ## Curated Lists & Recommendations (Requests) - `GET /curated-lists` - `GET /market-recommendations/{itemsCount}` ## Popular Investors (Copiers) - `GET /pi-data/copiers` ## User Info & Analytics (Requests) - `GET /user-info/people` Optional: `usernames`, `cidList`. Use this to map **username ↔ CID (userId)** when you need numeric `userId` for feeds/public watchlists. - `GET /user-info/people/search` Required: `period`. Optional: `page`, `pageSize`, `sort`, `popularInvestor`, `gainMax`, `maxDailyRiskScoreMin`, `maxDailyRiskScoreMax`, `maxMonthlyRiskScoreMin`, `maxMonthlyRiskScoreMax`, `weeksSinceRegistrationMin`, `countryId`, `instrumentId`, `instrumentPctMin`, `instrumentPctMax`, `isTestAccount`, and other filters. - `GET /user-info/people/{username}/gain` - `GET /user-info/people/{username}/daily-gain` Required: `minDate`, `maxDate`, `type` (`Daily` or `Period`). - `GET /user-info/people/{username}/portfolio/live` - `GET /user-info/people/{username}/tradeinfo` Required: `period` (e.g., `LastTwoYears`). ## Responses & Schemas For response schemas and full examples, refer to: - https://api-portal.etoro.com/ - MCP server: `https://api-portal.etoro.com/mcp`