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

Instrument APIs

Factsheet APIs

Rankings / Screener API

OpenAPI Specs

You can find BullAware's OpenAPI specs here.

Last updated 1 month ago

Get a list of investors.

Returns a paginated list of investors.

GEThttps://api.bullaware.com/v1/investors

Authorization

Query parameters

Response

Body

total*number

The total number of results

Example: 100

itemsarray of object

Request

const response = await fetch('https://api.bullaware.com/v1/investors', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}

Authorization

Path parameters

username*string

eToro username

Response

Body

investor*object

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/portfolio

Authorization

Path parameters

username*string

eToro username

Response

Body

balance*number

Available cash balance as a percentage of the total portfolio

Example: 1.12

positions*array of object

List of open positions in the portfolio

copies*array of object

List of copied portfolios

copiesTotal*number

Total number of copies

Example: 3

strategystring

Investment strategy name

Example: "Growth"

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/portfolio', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/trades

Authorization

Path parameters

username*string

eToro username

Query parameters

Response

Body

positions*array of object

List of positions closed

copies*array of object

List of copied portfolios who closed a position

instruments*array of object

List of instruments for closed positions

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/trades', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/history

Authorization

Path parameters

username*string

eToro username

Response

Body

instruments*array of object

The list of instruments

copies*array of object

The list of copy traders

daily*array of object

The daily history records

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/history', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/copiers/history

Authorization

Path parameters

username*string

eToro username

Response

Body

daily*array of object

The daily data points of investor copiers history

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/copiers/history', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

Get number of copiers over time for an investor.

GEThttps://api.bullaware.com/v1/investors/{username}/copiers/countries

Authorization

Path parameters

username*string

eToro username

Response

Body

countries*array of object

The list of countries with their corresponding values

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/copiers/countries', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

Get metrics for an investor.

GEThttps://api.bullaware.com/v1/investors/{username}/metrics

Authorization

Path parameters

username*string

eToro username

Query parameters

Response

Body

score*number

The BullAware score.

Example: 7.9

beta*number

A measure of the portfolio's volatility relative to the market as a whole.

Example: 1.11

sharpeRatio*number

Risk-adjusted measure of a portfolio's excess return relative to a risk-free rate.

Example: 1.23

sortinoRatio*number

Similar to Sharpe ratio but only penalizes downside volatility.

Example: 1.45

jensensAlpha*number

The difference between the actual returns and the expected returns based on beta.

Example: 2.34

omegaRatio*number

The probability-weighted ratio of gains versus losses.

Example: 1.67

treynorRatio*number

Portfolio's excess return per unit of risk (measured by beta).

Example: 0.89

informationRatio*number

Risk-adjusted excess returns compared to a benchmark.

Example: 0.56

calmarRatio*number

Ratio of average annual compound rate of return to maximum drawdown risk.

Example: 1.12

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/metrics', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/metrics/history

Authorization

Path parameters

username*string

eToro username

Query parameters

Response

Body

score*object

Historical BullAware scores by month

Example: {"2024-7":3.12,"2024-8":3.64}

beta*object

Historical beta values (portfolio's volatility relative to the market) by month

Example: {"2024-7":2.03,"2024-8":2.03}

sharpeRatio*object

Historical Sharpe ratios (risk-adjusted excess returns) by month

Example: {"2024-7":0.61,"2024-8":1.09}

sortinoRatio*object

Historical Sortino ratios (downside risk-adjusted returns) by month

Example: {"2024-7":1.62,"2024-8":2.53}

jensensAlpha*object

Historical Jensen's Alpha values (excess returns relative to CAPM) by month

Example: {"2024-7":-32.45,"2024-8":-30.99}

omegaRatio*object

Historical Omega ratios (probability-weighted ratio of gains vs losses) by month

Example: {"2024-7":0.28,"2024-8":0.23}

treynorRatio*object

Historical Treynor ratios (excess returns per unit of systematic risk) by month

Example: {"2024-7":0.29,"2024-8":0.37}

informationRatio*object

Historical Information ratios (risk-adjusted excess returns vs benchmark) by month

Example: {"2024-7":-2.61,"2024-8":-3.13}

calmarRatio*object

Historical Calmar ratios (return to maximum drawdown) by month

Example: {"2024-7":9.2,"2024-8":10}

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/metrics/history', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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.

GEThttps://api.bullaware.com/v1/investors/{username}/risk-score/monthly

Authorization

Path parameters

username*string

eToro username

Response

Body

points*array of object

List of risk score data points

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/risk-score/monthly', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

Get the daily risk score for an investor.

GEThttps://api.bullaware.com/v1/investors/{username}/risk-score/daily

Authorization

Path parameters

username*string

eToro username

Response

Body

points*array of object

List of risk score data points

Request

const response = await fetch('https://api.bullaware.com/v1/investors/{username}/risk-score/daily', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

Get a list of instruments.

Returns a paginated list of instruments.

GEThttps://api.bullaware.com/v1/instruments

Authorization

Query parameters

Response

Body

total*number

The total number of results

Example: 100

itemsarray of object

Request

const response = await fetch('https://api.bullaware.com/v1/instruments', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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

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

GEThttps://api.bullaware.com/v1/instruments/{symbol}

Authorization

Path parameters

symbol*string

The symbol of the instrument or an eToro instrument ID.

Response

Body

instrument*object

Request

const response = await fetch('https://api.bullaware.com/v1/instruments/{symbol}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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
    }
  }
}

Get the latest factsheet of an investor

GEThttps://api.bullaware.com/v1/factsheets/{username}

Authorization

Path parameters

username*string

eToro username

Response

Body

portfolio*all of

The portfolio information

history*all of

The history of the portfolio

returns*all of

Returns data for instruments and investors

generatedAt*string (date-time)

Timestamp of when the factsheet was generated

Example: "2024-12-02T10:40:23.859Z"

Request

const response = await fetch('https://api.bullaware.com/v1/factsheets/{username}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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"
}

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

GEThttps://api.bullaware.com/v1/rankings/{key}

Authorization

Path parameters

key*enum

A unique identifier for the ranking set or criteria.

scoresharpe-ratiobetacopierscopiers-changetradeswin-ratiodividend-yieldannualized-returnreturn-last-dayreturn-this-weekreturn-this-monthreturn-ytdreturn-1yreturn-2yreturn-5yreturn-all-timeprofitable-weeksprofitable-monthsprofitable-yearsweeks-since-registrationgreen-monthslongest-green-streakcurrent-green-streak

Query parameters

Response

Body

investors*array of object

An array of investor ranking items.

Request

const response = await fetch('https://api.bullaware.com/v1/rankings/{key}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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
    }
  ]
}