eToro Portfolio Search API

openapi: 3.2.0
info:
  title: eToro Portfolio Search API
  version: v1.395.0
  description: 'eToro’s public API provides access to real-time financial data, trading insights, and account management features, allowing developers to integrate eToro’s services into their applications. With access to market prices, historical data, and social trading information, the API empowers users to enhance their trading strategies. Designed for security and scalability, the eToro API ensures smooth and reliable integration for a variety of financial applications.


    For more details on integrating with eToro''s public WebSocket service, please refer to the dedicated WebSocket documentation.


    ## Authentication


    Every request must be authenticated with exactly one of two options: an OAuth 2.0 access token (`Authorization: Bearer `), or the non-interactive credential pair (`x-api-key` + `x-user-key` headers). The two options are mutually exclusive — a request carrying both is rejected. Each operation lists the OAuth scopes that grant access as alternative security requirements: a bearer token needs only ONE of them, and the same permissions govern the credential pair.'
servers:
- url: https://public-api.etoro.com
  description: eToro Public API
security:
- apiKeyAuth: []
  userKeyAuth: []
- oauth2: []
tags:
- name: PortfolioSearch
paths:
  /api/v1/portfolios/search:
    get:
      tags:
      - PortfolioSearch
      summary: Search for trader portfolios or Smart Portfolios by free-text query
      description: '**Rate limit:** 60 requests per 60 seconds. This is the **default shared quota** — it is shared with every other endpoint that has no dedicated limit, so requests across those endpoints all draw from the same budget.


        ---


        Returns a relevance-ranked list of publicly visible trader portfolios or Smart Portfolios matching the query string. The required `type` parameter determines which index is searched. Results are capped at `limit`.'
      operationId: searchPortfolios
      parameters:
      - name: x-request-id
        in: header
        required: true
        schema:
          type: string
          format: uuid
          example: f3501a01-1885-4ac0-9b9b-634ff9a1a6bd
        description: A unique request identifier.
        example: f3501a01-1885-4ac0-9b9b-634ff9a1a6bd
      - name: type
        in: query
        required: true
        description: Portfolio type to search.
        schema:
          type: string
          enum:
          - trader
          - smart-portfolio
      - name: query
        in: query
        required: true
        description: Free-text search string.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSearchResponse'
          headers:
            RateLimit-Limit:
              description: Maximum number of requests allowed per window. This is the default shared pool used by every endpoint without a dedicated limit, so it is NOT per-endpoint — requests across those endpoints all draw from this one budget.
              schema:
                type: integer
              example: 60
            RateLimit-Remaining:
              description: Requests remaining in the current window for this quota.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
            RateLimit-Policy:
              description: Quota policy in the form `<limit>;w=<window-seconds>`.
              schema:
                type: string
              example: 60;w=60
        '400':
          description: Invalid request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSearchBffApi_Error'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSearchBffApi_Error'
          headers:
            RateLimit-Limit:
              description: Maximum number of requests allowed per window. This is the default shared pool used by every endpoint without a dedicated limit, so it is NOT per-endpoint — requests across those endpoints all draw from this one budget.
              schema:
                type: integer
              example: 60
            RateLimit-Remaining:
              description: Requests remaining in the current window for this quota.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
            RateLimit-Policy:
              description: Quota policy in the form `<limit>;w=<window-seconds>`.
              schema:
                type: string
              example: 60;w=60
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 60
        '502':
          description: Upstream search provider error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSearchBffApi_Error'
        '504':
          description: Upstream search provider timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSearchBffApi_Error'
      security:
      - apiKeyAuth: []
        userKeyAuth: []
      - oauth2: []
      x-ratelimit:
        limit: 60
        window: 60
        shared: true
        defaultPool: true
components:
  schemas:
    PortfolioSearchResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          description: Relevance-ranked results. Never null - empty array when no matches.
          items:
            $ref: '#/components/schemas/PortfolioSearchResult'
    PortfolioSearchResult:
      type: object
      required:
      - username
      - type
      - profileUrl
      properties:
        username:
          type: string
        fullName:
          type:
          - string
          - 'null'
        avatarUrl:
          type:
          - string
          - 'null'
        type:
          type: string
          enum:
          - trader
          - smart-portfolio
        subType:
          type:
          - string
          - 'null'
          enum:
          - pi-certified
          - pi-cadet
          - pi-rising-star
          - pi-champion
          - pi-elite
          - pi-elite-pro
          - top-traders
          - partners
          - market
        copiers:
          type:
          - integer
          - 'null'
        country:
          type:
          - string
          - 'null'
        profileUrl:
          type: string
    PortfolioSearchBffApi_Error:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: '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`'
    userKeyAuth:
      type: apiKey
      in: header
      name: x-user-key
      description: '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_`'
    oauth2:
      type: oauth2
      description: 'eToro OAuth2 — send the access token as `Authorization: Bearer <token>`. Each operation lists the scopes that grant access as separate `security` requirements (OpenAPI OR semantics): the caller''s token only needs ONE of them — you do NOT need all of them. Mutually exclusive with the x-api-key/x-user-key credential pair: never send both.'
      flows:
        authorizationCode:
          authorizationUrl: https://www.etoro.com/sso
          tokenUrl: https://www.etoro.com/api/sso/v1/token
          scopes:
            etoro-public:agent-portfolio:read: Grants access to the 'etoro-public:agent-portfolio:read' scope.
            etoro-public:agent-portfolio:write: Grants access to the 'etoro-public:agent-portfolio:write' scope.
            etoro-public:club:read: Grants access to the 'etoro-public:club:read' scope.
            etoro-public:demo:read: Grants access to the 'etoro-public:demo:read' scope.
            etoro-public:demo:write: Grants access to the 'etoro-public:demo:write' scope.
            etoro-public:feed:read: Grants access to the 'etoro-public:feed:read' scope.
            etoro-public:feed:write: Grants access to the 'etoro-public:feed:write' scope.
            etoro-public:market-data:read: Grants access to the 'etoro-public:market-data:read' scope.
            etoro-public:money.balance:read: Grants access to the 'etoro-public:money.balance:read' scope.
            etoro-public:money.cash-transactions:read: Grants access to the 'etoro-public:money.cash-transactions:read' scope.
            etoro-public:money.transfer:read: Grants access to the 'etoro-public:money.transfer:read' scope.
            etoro-public:money.transfer:write: Grants access to the 'etoro-public:money.transfer:write' scope.
            etoro-public:money:transfer: Grants access to the 'etoro-public:money:transfer' scope.
            etoro-public:notifications:read: Grants access to the 'etoro-public:notifications:read' scope.
            etoro-public:notifications:write: Grants access to the 'etoro-public:notifications:write' scope.
            etoro-public:pi-data:read: Grants access to the 'etoro-public:pi-data:read' scope.
            etoro-public:price-alerts:read: Grants access to the 'etoro-public:price-alerts:read' scope.
            etoro-public:price-alerts:write: Grants access to the 'etoro-public:price-alerts:write' scope.
            etoro-public:real:read: Grants access to the 'etoro-public:real:read' scope.
            etoro-public:real:write: Grants access to the 'etoro-public:real:write' scope.
            etoro-public:sso-applications:read: Grants access to the 'etoro-public:sso-applications:read' scope.
            etoro-public:sso-applications:write: Grants access to the 'etoro-public:sso-applications:write' scope.
            etoro-public:sso-scopes:read: Grants access to the 'etoro-public:sso-scopes:read' scope.
            etoro-public:sso-scopes:write: Grants access to the 'etoro-public:sso-scopes:write' scope.
            etoro-public:sub-accounts:read: Grants access to the 'etoro-public:sub-accounts:read' scope.
            etoro-public:sub-accounts:write: Grants access to the 'etoro-public:sub-accounts:write' scope.
            etoro-public:trade.demo:read: Grants access to the 'etoro-public:trade.demo:read' scope.
            etoro-public:trade.demo:write: Grants access to the 'etoro-public:trade.demo:write' scope.
            etoro-public:trade.real:read: Grants access to the 'etoro-public:trade.real:read' scope.
            etoro-public:trade.real:write: Grants access to the 'etoro-public:trade.real:write' scope.
            etoro-public:user-info:read: Grants access to the 'etoro-public:user-info:read' scope.
            etoro-public:watchlist:read: Grants access to the 'etoro-public:watchlist:read' scope.
            etoro-public:watchlist:write: Grants access to the 'etoro-public:watchlist:write' scope.
x-provenance:
  method: harvested
  publisher: eToro
  source: https://builders.etoro.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)