BullAware API

BullAware API docs gives you access to the APIs that power BullAware.com

Authentication

Before starting, you need to get an API Key from here.

You can use your API Key either on the query strings or headers:

Query String

Add ?apikey={YOUR_API_KEY} to any API endpoint.

Headers

Add the header Authorization with the value Bearer {YOUR_API_KEY}

---

Investor API

Get a list of investors.

get

Returns a paginated list of investors.

Authorizations

ApiKeyQueryApiKeyHeader

Query parameters

usernamestringoptional

Filter by username. Accepts multiple username separated by commas.

fullnamestringoptional

yearlyReturnsstringoptional

Filter for yearly returns. Years are in 4 digits format. Format: year:comparator:value. Comparators: gt, lt, gte, lte. Supports aggregate functions avg and sum for multiple years, e.g., avg(year1,year2):comparator:value.

Example: 2023:gt:5,2022:lt:10,2021:gte:2,avg(2020,2021,2022):gt:5,sum(2021,2022):gt:10

piLevelstring · enumoptionalAvailable options:

investsInstringoptional

A string representing investment sectors or types, with conditions and exclusions. Use "+" for AND, "|" for OR, and "-" for NOT. For example, "Tech+Software-Crypto" means Tech AND Software, but NO Crypto. Valid sectors/types: Tech, Manufacturing, Med Tech, Retail, Financial Services, Energy, Consumable Goods, Healthcare, Media Services, Construction, Utilities, Minerals, Software, Entertainment, Durable Goods, Telecom, Processing, Distribution, Other, Stocks, Transportation, Currencies, Commodities, Indices, ETF, Crypto.

countrystringoptional

Filter by country (ISO 3166-1 alpha-2 country code). Accepts multiple countries separated by commas.

Example: US,GB

orderBystringoptional

Sorts results by a field or aggregate expressions. Format for field sort: 'fieldName:order' (e.g., 'return1Year:asc', default is 'desc'). For aggregates like sum or avg, use 'operation(field1,field2):order' (e.g., 'sum(yearlyReturns.2023,yearlyReturns.2022)' or 'avg(yearlyReturns.2023,yearlyReturns.2022,yearlyReturns.2021):asc').

pagenumberoptional

Page number for pagination (default: 1).

Example: 1

weeksSinceRegistrationstringoptional

Filter for weeks since registration. Comparators: gt, lt, gte, lte.

Example: lte:50

weeklyDDstringoptional

Filter for the maximum weekly drawdown during the last 12 months. It's a negative number between 0 and -100. Closest to -100 mean higher losses. Comparators: gt, lt, gte, lte.

Example: gt:-5

dailyDDstringoptional

Filter for the maximum daily drawdown during the last 12 months. It's a negative number between 0 and -100. Closest to -100 mean higher losses. Comparators: gt, lt, gte, lte.

Example: gt:-3

winRatiostringoptional

Filter for the percentage of trades that were profitable during the last 12 months. Comparators: gt, lt, gte, lte.

Example: gte:50

tradesstringoptional

Filter for number of trades during the last 12 months. Comparators: gt, lt, gte, lte.

Example: gte:50

copiersstringoptional

Filter for copiers. Comparators: gt, lt, gte, lte.

Example: gt:100

return2Yearsstringoptional

Filter for return over 2 years. Comparators: gt, lt, gte, lte.

Example: gt:20

return1Yearstringoptional

Filter for return this year. Comparators: gt, lt, gte, lte.

Example: gte:10

returnThisWeekstringoptional

Filter for return this week. Comparators: gt, lt, gte, lte.

Example: gt:2

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors'

200

200

{
  "total": 100,
  "items": [
    {
      "username": "BigTech",
      "fullname": "John Doe",
      "returnThisWeek": 1.26,
      "returnYearToDate": 17.74,
      "return1Year": 39.98,
      "return2Years": 71.916,
      "return5Years": 133.29,
      "yearlyReturns": {
        "2013": -11.07,
        "2014": -13.42,
        "2015": 45.5,
        "2016": 26.14,
        "2017": 29.29,
        "2018": 6.31,
        "2019": 34.82,
        "2020": 79.6,
        "2021": 11.3,
        "2022": -38.81,
        "2023": 54.73
      },
      "copiers": 3537,
      "aum": "$5M+",
      "piLevel": "Elite Pro",
      "trades": 294,
      "winRatio": 69.73,
      "dailyDD": -3.28,
      "weeklyDD": -4.74,
      "weeksSinceRegistration": 580,
      "country": "IT",
      "investsIn": [
        "Software",
        "Retail"
      ],
      "topTradedInstrument": {
        "instrumentId": 1002,
        "name": "Alphabet",
        "symbol": "GOOG"
      },
      "link": "https://www.etoro.com/people/BigTech"
    }
  ]
}

Get an eToro portfolio by username. Only public portfolios with at least 1 copier are supported.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}'

200

200

{
  "investor": {
    "username": "BigTech",
    "fullname": "John Doe",
    "returnThisWeek": 1.26,
    "returnYearToDate": 17.74,
    "return1Year": 39.98,
    "return2Years": 71.916,
    "return5Years": 133.29,
    "yearlyReturns": {
      "2013": -11.07,
      "2014": -13.42,
      "2015": 45.5,
      "2016": 26.14,
      "2017": 29.29,
      "2018": 6.31,
      "2019": 34.82,
      "2020": 79.6,
      "2021": 11.3,
      "2022": -38.81,
      "2023": 54.73
    },
    "copiers": 3537,
    "aum": "$5M+",
    "piLevel": "Elite Pro",
    "trades": 294,
    "winRatio": 69.73,
    "dailyDD": -3.28,
    "weeklyDD": -4.74,
    "weeksSinceRegistration": 580,
    "country": "IT",
    "investsIn": [
      "Software",
      "Retail"
    ],
    "topTradedInstrument": {
      "instrumentId": 1002,
      "name": "Alphabet",
      "symbol": "GOOG"
    },
    "link": "https://www.etoro.com/people/BigTech",
    "strategyID": 2,
    "monthlyReturns": {
      "2021-01": 5.5,
      "2021-02": 9.2,
      "2021-03": -4.3
    },
    "score": 7.9,
    "riskScore": 5,
    "beta": 1.11,
    "maxDailyRiskScore": 5,
    "maxMonthlyRiskScore": 5,
    "profitableWeeksPct": 64.91,
    "profitableMonthsPct": 84.62,
    "avgPosSize": 2.73,
    "highLeveragePct": 20,
    "mediumLeveragePct": 15,
    "lowLeveragePct": 65,
    "longPosPct": 82,
    "topTradedInstrumentPct": 9.54,
    "about": "I invest in tech using growth strategy.",
    "aboutShort": "I invest in tech.",
    "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/5572968/2.jpg",
    "copiersChange": 12,
    "dividendYield": 0.78
  }
}

Get the instruments in an eToro portfolio.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/portfolio'

200

200

{
  "balance": 1.12,
  "positions": [
    {
      "direction": 1,
      "symbol": "GOOG",
      "value": 13.7,
      "netProfit": 24.7
    }
  ],
  "copies": [
    {
      "cid": 30000000,
      "username": "BigTech",
      "invested": 4.76,
      "netProfit": 8.9,
      "value": 4.65,
      "portfolio": {
        "positions": [
          {
            "direction": 1,
            "symbol": "GOOG",
            "value": 13.7,
            "netProfit": 24.7
          }
        ],
        "balance": 0.283
      },
      "avatar": "https://etoro-cdn.etorostatic.com/images/avatoros/150x150/ar.png",
      "piLevel": 0
    }
  ],
  "copiesTotal": 3,
  "strategy": "Growth"
}

Get a list of closed positions for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Query parameters

startstringoptional

Start date for trades in ISO format

endstringoptional

End date for trades in ISO format

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/trades'

200

200

{
  "positions": [
    {
      "positionId": 2747926753,
      "openDateTime": "2024-01-04T16:45:50.917Z",
      "openRate": 151.3742,
      "instrumentId": 1706,
      "isBuy": true,
      "parentCID": 15321738,
      "closeDateTime": "2024-06-26T14:19:45.467Z",
      "closeRate": 234.8,
      "closeReason": 17,
      "netProfit": 55.1,
      "leverage": 1
    }
  ],
  "copies": [
    {
      "cid": 1234567,
      "username": "BigTech"
    }
  ],
  "instruments": [
    {
      "instrumentId": 1001,
      "name": "Apple",
      "symbol": "AAPL"
    }
  ]
}

Get the porfolio of an investor for any day in the past.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/history'

200

200

{
  "instruments": [
    {
      "instrumentId": 1001,
      "name": "Apple",
      "symbol": "AAPL",
      "sector": "Electronic Technology",
      "country": "US",
      "exchange": "Nasdaq",
      "type": 5
    }
  ],
  "copies": [
    {
      "username": "BigTech",
      "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/5572968/2.jpg",
      "piLevel": "Cadet"
    }
  ],
  "daily": [
    {
      "date": "2024-01-01T00:00:00Z",
      "cash": 3.5,
      "assets": [
        {
          "invested": 5,
          "value": 6.6,
          "instrumentId": 1001,
          "userName": "BigTech"
        }
      ]
    }
  ]
}

Get number of copiers over time for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/copiers/history'

200

200

{
  "daily": [
    {
      "date": "2024-11-06T00:00:00Z",
      "value": 123
    }
  ]
}

Get number of copiers over time for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/copiers/countries'

200

200

{
  "countries": [
    {
      "code": "AR",
      "value": 123
    }
  ]
}

Get metrics for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Query parameters

startstringoptional

Start date for trades in ISO format. If not provided, it will use the first trade date.

endstringoptional

End date for trades in ISO format. If not provided, it will use the latest trade date.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/metrics'

200

200

{
  "score": 7.9,
  "beta": 1.11,
  "sharpeRatio": 1.23,
  "sortinoRatio": 1.45,
  "jensensAlpha": 2.34,
  "omegaRatio": 1.67,
  "treynorRatio": 0.89,
  "informationRatio": 0.56,
  "calmarRatio": 1.12
}

Get historical metrics for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Query parameters

startstringoptional

Start date for trades in ISO format. If not provided, it will use the first trade date.

endstringoptional

End date for trades in ISO format. If not provided, it will use the latest trade date.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/metrics/history'

200

200

{
  "score": {
    "2024-7": 3.12,
    "2024-8": 3.64
  },
  "beta": {
    "2024-7": 2.03,
    "2024-8": 2.03
  },
  "sharpeRatio": {
    "2024-7": 0.61,
    "2024-8": 1.09
  },
  "sortinoRatio": {
    "2024-7": 1.62,
    "2024-8": 2.53
  },
  "jensensAlpha": {
    "2024-7": -32.45,
    "2024-8": -30.99
  },
  "omegaRatio": {
    "2024-7": 0.28,
    "2024-8": 0.23
  },
  "treynorRatio": {
    "2024-7": 0.29,
    "2024-8": 0.37
  },
  "informationRatio": {
    "2024-7": -2.61,
    "2024-8": -3.13
  },
  "calmarRatio": {
    "2024-7": 9.2,
    "2024-8": 10
  }
}

Get the monthly risk score for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/risk-score/monthly'

200

200

{
  "points": [
    {
      "date": "2020-06-01T00:00:00.000Z",
      "riskScore": 6,
      "minRiskScore": 5,
      "maxRiskScore": 7
    }
  ]
}

Get the daily risk score for an investor.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/investors/{username}/risk-score/daily'

200

200

{
  "points": [
    {
      "date": "2020-06-01T00:00:00.000Z",
      "riskScore": 6,
      "minRiskScore": 5,
      "maxRiskScore": 7
    }
  ]
}

---

Instrument APIs

Get a list of instruments.

get

Returns a paginated list of instruments.

Authorizations

ApiKeyQueryApiKeyHeader

Query parameters

namestringoptional

symbolstringoptional

Filter by symbol. Accepts multiple symbols separated by commas.

typestring · enumoptionalAvailable options:

sectorstring · enumoptional

Filter by sector. Accepts multiple sectors separated by commas.

Available options:

industrystring · enumoptional

Filter by industry. Accepts multiple industries separated by commas.

Available options:

indexstring · enumoptional

Filter by index. Accepts multiple indices separated by commas.

Available options:

countrystringoptional

Filter by country (ISO 3166-1 alpha-2 country code). Accepts multiple countries separated by commas.

Example: US,GB

yearlyReturnsstringoptional

Filter for yearly returns. Years are in 4 digits format. Format: year:comparator:value. Comparators: gt, lt, gte, lte. Supports aggregate functions avg and sum for multiple years, e.g., avg(year1,year2):comparator:value.

Example: 2023:gt:5,2022:lt:10,2021:gte:2,avg(2020,2021,2022):gt:5,sum(2021,2022):gt:10

orderBystringoptional

Sorts results by a field or aggregate expressions. Format for field sort: 'fieldName:order' (e.g., 'returnYearToDate:asc', default is 'desc'). For aggregates like sum or avg, use 'operation(field1,field2):order' (e.g., 'sum(yearlyReturns.2023,yearlyReturns.2022)' or 'avg(operatingMargin,grossIncomeMargin):asc')').

fieldsstringoptional

Comma-separated list of fields to include in the response.

pagenumberoptional

Page number for pagination (default: 1).

Example: 1

5YearAverageNetProfitMarginstringoptional

Filter by average net profit margin. Comparators: gt, lt, gte, lte.

Example: gt:20

5YearAverageReturnOnInvestedCapitalstringoptional

Filter by the average return on investment. Comparators: gt, lt, gte, lte.

Example: gt:15

grossIncomeMarginstringoptional

Filter by gross income margin. Comparators: gt, lt, gte, lte.

Example: gte:40

operatingMarginstringoptional

Filter by operating margin. Comparators: gt, lt, gte, lte.

Example: gte:15

quickRatiostringoptional

Filter by quick ratio. Comparators: gt, lt, gte, lte.

Example: gte:1.5

totalDebtToEquityRatiostringoptional

Filter by total debt to equity ratio. Comparators: gt, lt, gte, lte.

Example: lt:0.5

betastringoptional

Filter by beta. Comparators: gt, lt, gte, lte.

Example: gt:1

currentRatiostringoptional

Filter by current ratio. Comparators: gt, lt, gte, lte.

Example: gte:1

peRatiostringoptional

Filter by P/E ratio. Comparators: gt, lt, gte, lte.

Example: lte:25

dividendPayoutRatiostringoptional

Filter by dividend payout ratio. Comparators: gt, lt, gte, lte.

Example: gt:5

dividendYieldstringoptional

Filter by dividend yield percentage. Comparators: gt, lt, gte, lte.

Example: gt:5

dividendLastYearstringoptional

Filter by dividend per share during the last 12 months. Comparators: gt, lt, gte, lte.

Example: gt:1

salesOrRevenuestringoptional

Filter by sales or revenue in dollars. Comparators: gt, lt, gte, lte.

Example: gt:1000000

epsstringoptional

Filter by earnings per share. Comparators: gt, lt, gte, lte.

Example: gt:1

marketCapitalizationstringoptional

Filter by market cap in dollars. Comparators: gt, lt, gte, lte.

Example: gte:100000000

numberOfEmployeesstringoptional

Filter by number of employees. Comparators: gt, lt, gte, lte.

Example: gte:1000

returnYearToDatestringoptional

Filter by the return year to date. Comparators: gt, lt, gte, lte.

Example: gt:15

returnLastYearstringoptional

Filter by the return during the last year. Comparators: gt, lt, gte, lte.

Example: gt:30

returnLastMonthstringoptional

Filter by the return during the last month. Comparators: gt, lt, gte, lte.

Example: gt:6

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/instruments'

200

200

{
  "total": 100,
  "items": [
    {
      "instrumentId": 1001,
      "name": "Apple",
      "symbol": "AAPL",
      "cik": "0000320193",
      "link": "https://www.etoro.com/markets/AAPL",
      "closingPrice": 237.33,
      "returnLastDay": 1.92,
      "returnThisWeek": 3.24,
      "returnThisMonth": 5.06,
      "returnLastMonth": 6.46,
      "returnYearToDate": 23.26,
      "returnLastYear": 24.91,
      "return2Years": 54.771,
      "return5Years": 281.63,
      "yearlyReturns": {
        "2022": -26.83,
        "2023": 48.18
      },
      "type": "Stock",
      "sector": "Electronic Technology",
      "industry": "Telecommunications Equipment",
      "ceo": "Tim Cook, MBA",
      "country": "US",
      "exchange": "Nasdaq",
      "numberOfEmployees": 164000,
      "marketCapitalization": 3587432814000,
      "eps": 6.0699,
      "salesOrRevenue": 391035000000,
      "dividendLastYear": 0.97,
      "dividendYield": 0.4171,
      "dividendPayoutRatio": 16.31,
      "peRatio": 39.1,
      "currentRatio": 0.87,
      "beta": 1.22,
      "longTermDebtToEquityRatio": 169.53,
      "totalDebtToEquityRatio": 209.06,
      "quickRatio": 0.83,
      "revenuePerShare": 25.65,
      "cashFlowPerShare": 7.58,
      "netOperatingCashFlow": 118254000000,
      "operatingMargin": 31.51,
      "grossIncomeMargin": 46.21,
      "averageDailyVolumeLast3Months": 48560301.66,
      "dividendExDate": "2024-11-08T00:00:00.000Z",
      "dividendPayDate": "2024-11-14T00:00:00.000Z",
      "dividendFrequency": "QUARTERLY",
      "dividendUsd": 0.25
    }
  ]
}

Get Instrument by Symbol

get

Retrieve a single instrument by its symbol or eToro instrument ID.

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

symbolstringrequired

The symbol of the instrument or an eToro instrument ID.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/instruments/{symbol}'

200

200

{
  "instrument": {
    "instrumentId": 1001,
    "name": "Apple",
    "symbol": "AAPL",
    "cik": "0000320193",
    "link": "https://www.etoro.com/markets/AAPL",
    "closingPrice": 237.33,
    "returnLastDay": 1.92,
    "returnThisWeek": 3.24,
    "returnThisMonth": 5.06,
    "returnLastMonth": 6.46,
    "returnYearToDate": 23.26,
    "returnLastYear": 24.91,
    "return2Years": 54.771,
    "return5Years": 281.63,
    "yearlyReturns": {
      "2022": -26.83,
      "2023": 48.18
    },
    "type": "Stock",
    "sector": "Electronic Technology",
    "industry": "Telecommunications Equipment",
    "ceo": "Tim Cook, MBA",
    "country": "US",
    "exchange": "Nasdaq",
    "numberOfEmployees": 164000,
    "marketCapitalization": 3587432814000,
    "eps": 6.0699,
    "salesOrRevenue": 391035000000,
    "dividendLastYear": 0.97,
    "dividendYield": 0.4171,
    "dividendPayoutRatio": 16.31,
    "peRatio": 39.1,
    "currentRatio": 0.87,
    "beta": 1.22,
    "longTermDebtToEquityRatio": 169.53,
    "totalDebtToEquityRatio": 209.06,
    "quickRatio": 0.83,
    "revenuePerShare": 25.65,
    "cashFlowPerShare": 7.58,
    "netOperatingCashFlow": 118254000000,
    "operatingMargin": 31.51,
    "grossIncomeMargin": 46.21,
    "averageDailyVolumeLast3Months": 48560301.66,
    "dividendExDate": "2024-11-08T00:00:00.000Z",
    "dividendPayDate": "2024-11-14T00:00:00.000Z",
    "dividendFrequency": "QUARTERLY",
    "dividendUsd": 0.25,
    "monthlyReturns": {
      "2023-11": 11.23,
      "2023-12": 1.36
    }
  }
}

---

Factsheet APIs

Get the latest factsheet of an investor

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

usernamestringrequired

eToro username

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/factsheets/{username}'

200

200

{
  "portfolio": {
    "username": "BigTech",
    "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/5572968/2.jpg",
    "country": "IT",
    "strategy": 2,
    "monthlyReturns": {},
    "piLevel": 6,
    "riskScore": 4,
    "fundType": 0,
    "aum": "$5M+",
    "about": "text",
    "positions": [
      {
        "direction": 1,
        "symbol": "GOOG",
        "value": 13.7,
        "netProfit": 24.7
      }
    ],
    "copiesTotal": 3,
    "balance": 0.83,
    "copiers": 3532,
    "updatedAt": "2024-12-02T10:27:38.681Z"
  },
  "history": {
    "cid": 3180395,
    "username": "MarianoPardo",
    "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/3180395/2.jpg",
    "piLevel": 6,
    "instruments": [
      {
        "instrumentId": 1001,
        "name": "Apple",
        "symbol": "AAPL",
        "price": 237.33
      }
    ],
    "copies": [
      {
        "cid": 18809478,
        "username": "YoniAssia",
        "invested": 4.82,
        "netProfit": 5.51,
        "value": 4.73,
        "portfolio": {
          "username": "BigTech",
          "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/5572968/2.jpg",
          "country": "IT",
          "strategy": 2,
          "monthlyReturns": {},
          "piLevel": 6,
          "riskScore": 4,
          "fundType": 0,
          "aum": "$5M+",
          "about": "text",
          "positions": [
            {
              "direction": 1,
              "symbol": "GOOG",
              "value": 13.7,
              "netProfit": 24.7
            }
          ],
          "copiesTotal": 3,
          "balance": 0.83,
          "copiers": 3532,
          "updatedAt": "2024-12-02T10:27:38.681Z"
        }
      }
    ],
    "positions": [
      {
        "direction": 1,
        "symbol": "GOOG",
        "value": 13.7,
        "netProfit": 24.7
      }
    ]
  },
  "returns": {
    "instruments": [
      {
        "symbol": "AAPL",
        "returns": {}
      }
    ],
    "investors": [
      {
        "cid": 19812375,
        "returns": {}
      }
    ]
  },
  "generatedAt": "2024-12-02T10:40:23.859Z"
}

---

Rankings / Screener API

Get the top investors by a specific ranking key and a set of filters.

get

Authorizations

ApiKeyQueryApiKeyHeader

Path parameters

keystring · enumrequired

A unique identifier for the ranking set or criteria.

Available options:

Query parameters

pagenumberoptional

Page number for pagination.

limitnumberoptional

Number of results per page.

usernamestringoptional

Filter results by eToro username.

countrystringoptional

Filter results by country code.

strategynumber · enumoptional

Filter by strategy type. Enter the number for the desired strategy: Value = 1, Growth = 2, Income = 3, LongShort = 4, MultiStrategy = 5, Momentum = 6, Macro = 7, MarketNeutral = 8, EventDriven = 9, DiversifiedETF = 10, Quant = 11.

Available options:

minScorenumberoptional

Minimum BullAware score.

maxScorenumberoptional

Maximum BullAware score.

minSharpeRationumberoptional

Minimum Sharpe ratio.

maxSharpeRationumberoptional

Maximum Sharpe ratio.

minBetanumberoptional

Minimum beta.

maxBetanumberoptional

Maximum beta.

minAnnualizedReturnnumberoptional

Minimum annualized return percentage.

maxAnnualizedReturnnumberoptional

Maximum annualized return percentage.

minRiskScorenumberoptional

Minimum eToro risk score.

maxRiskScorenumberoptional

Maximum eToro risk score.

minTrackRecordnumberoptional

Minimum track record length (in years).

maxTrackRecordnumberoptional

Maximum track record length (in years).

minCopiersnumberoptional

Minimum number of copiers.

maxCopiersnumberoptional

Maximum number of copiers.

minPiLevelnumberoptional

Minimum PI level.

maxPiLevelnumberoptional

Maximum Pi level.

minTradesnumberoptional

Minimum number of trades.

maxTradesnumberoptional

Maximum number of trades.

minGreenMonthsPctnumberoptional

Minimum percentage of green (profitable) months.

maxGreenMonthsPctnumberoptional

Maximum percentage of green (profitable) months.

minGreenYearsPctnumberoptional

Minimum percentage of green (profitable) years.

maxGreenYearsPctnumberoptional

Maximum percentage of green (profitable) years.

minWinRationumberoptional

Minimum win ratio (percentage of winning trades).

maxWinRationumberoptional

Maximum win ratio (percentage of winning trades).

maxDrawdownDepthnumberoptional

Maximum drawdown depth.

maxDrawdownDurationnumberoptional

Maximum drawdown duration filter (in months).

minDividendYieldnumberoptional

Minimum dividend yield.

maxDividendYieldnumberoptional

Maximum dividend yield.

minOpenInstrumentsnumberoptional

Minimum number of currently open instruments.

maxOpenInstrumentsnumberoptional

Maximum number of currently open instruments.

minLongPctnumberoptional

Minimum percentage of long positions.

maxLongPctnumberoptional

Maximum percentage of long positions.

minNoLeveragePctnumberoptional

Minimum percentage of positions with no leverage.

maxNoLeveragePctnumberoptional

Maximum percentage of positions with no leverage.

investsInstringoptional

Comma-separated list of sectors the investor must be investing in.

notInvestsInstringoptional

Comma-separated list of sectors the investor must NOT be investing in.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bullaware.com/v1/rankings/{key}'

200

200

{
  "investors": [
    {
      "username": "BigTech",
      "avatar": "https://etoro-cdn.etorostatic.com/avatars/150X150/3180395.jpg",
      "amount": 3537,
      "position": 1,
      "copiers": 3537,
      "strategy": 2,
      "country": "IT",
      "score": 6.353,
      "returnThisWeek": 1.26,
      "returnYearToDate": 17.74,
      "return1Year": 39.98,
      "return2Years": 71.92,
      "return5Years": 133.29
    }
  ]
}

---

OpenAPI Specs

You can find BullAware's OpenAPI specs here.