Skip to content

Portfolio Analysis API ​

Returns the lending rate, utilisation and potential return for a list of securities.

Endpoint ​

http
POST /public/portfolio-analysis

Full URL: https://api.sharegain.com/public/portfolio-analysis

Headers ​

HeaderValue
X-SG-AuthorizationYour API key
Content-Typeapplication/json
X-SG-ApiVersionOptional. 1

Request Body ​

json
{
  "identifiers": [
    { "requestKey": "1", "isin": "US5949181045" },
    { "requestKey": "2", "isin": "US123" }
  ],
  "includeExtraIdentifiers": true,
  "includeRecommendedUnits": true
}
FieldTypeDescription
identifiersarrayRequired. 1–200 securities per request
includeExtraIdentifiersbooleanOptional, default false. Adds compositeBbgid and compositeTicker to each result
includeRecommendedUnitsbooleanOptional, default false. Adds recommendedUnitsToAdd to each result

Instrument Identifier Parameters ​

Each item needs a requestKey and at least one of isin, compositeBbgId or ticker.

ParameterTypeDescription
requestKeystringRequired. Your own reference for the item, unique within the request. Returned with the result
isinstring12 characters, uppercase, e.g. US5949181045
compositeBbgIdstring12 alphanumeric characters, e.g. BBG000BPH459
tickerstringTicker or composite ticker, e.g. MSFT or MSFT US. Not case-sensitive
exchangestringOptional. Two uppercase letters, e.g. UW
micstringOptional, e.g. XNAS
countrystringOptional, e.g. US

Identifying securities

  • Only a composite Bloomberg ID or a composite ticker such as MSFT US pins a single listing. An ISIN or a plain ticker such as MSFT can match any listing of a security listed in more than one market, and a plain ticker can also match a different security that uses the same ticker in another market.
  • If you send more than one of isin, compositeBbgId and ticker, they must all refer to the same security.
  • exchange, mic and country are accepted but are not currently used to identify the security.
  • Field names are not case-sensitive. Unknown fields are ignored.

Response ​

json
{
  "successResults": [
    {
      "requestKey": "1",
      "isin": "US5949181045",
      "potentialReturn": 0.0401,
      "lendingRateBps": 420,
      "utilization": 0.86,
      "date": "2026-10-16T00:00:00Z",
      "compositeBbgid": "BBG000BPH459",
      "compositeTicker": "MSFT US",
      "recommendedUnitsToAdd": 103456
    }
  ],
  "failureResults": [
    {
      "requestKey": "2",
      "isin": "US123",
      "errorMessage": "Incorrect 'ISIN' format"
    }
  ],
  "totalCount": 2
}

Status Codes ​

StatusMeaning
200 OKEvery item succeeded
206 Partial ContentAt least one item is in failureResults, including when every item failed. The body has the same shape

For request-level errors (400, 401, 403, 429…), see Errors.

Result Fields ​

FieldDescription
requestKeyThe reference you sent
isinThe ISIN of the matched security, including when you identified it by ticker or Bloomberg ID
potentialReturnEstimated lending income per unit per day, in USD: price × utilisation × lending rate (bps) ÷ 10,000 ÷ 360. Multiply by your holding for a daily estimate. null when no lending rate is available
lendingRateBpsVolume-weighted average rate (VWAR) in basis points: of your own loans in this security if you have any, otherwise across Sharegain loans. null when only a market-data estimate is available; potentialReturn still uses that estimate
utilizationShare of the Sharegain lending pool currently on loan, from 0 to 1: your own if you lend this security through Sharegain, otherwise Sharegain-wide. 0 when there is no pool data
dateAs-of date of the market data (ISO 8601, UTC)
compositeBbgid, compositeTickerOnly when includeExtraIdentifiers is true. Omitted when unavailable
recommendedUnitsToAddOnly when includeRecommendedUnits is true. Suggested number of extra units to make available for lending, based on unmet borrower demand. Omitted when there is no recommendation

Utilisation in potentialReturn

When there is no pool data, utilization is 0 but potentialReturn uses market utilisation instead. Recomputing potentialReturn from the other fields in the response won't always match.

failureResults items contain requestKey, the isin you sent (or null), and an errorMessage. See item-level errors.

Market Data Freshness ​

A security is returned in failureResults with It seems that there's missing market data for this instrument when:

  • its price is more than 2 business days old,
  • there is no exchange rate to convert its price to USD, or
  • no utilisation is available, from either pool data or market data within our freshness window (at least the last 2 business days).

A security with no market data at all within that window fails with Missing instrument data in sharegain.

An out-of-date market lending rate doesn't fail the security. It still succeeds: potentialReturn uses the rate from our rate service where there is one, and is null otherwise. Out-of-date demand data only leaves out recommendedUnitsToAdd.

Rate Limits ​

Each request may contain up to 200 identifiers, for every account. The other limits are set per account: call GET /public/portfolio-analysis/quota to see yours and your current usage.

LimitRule
Items per request200, for every account
Requests per minuteRolling 60-second window
Requests per dayResets at 00:00 UTC
Items per dayResets at 00:00 UTC. A request is rejected in full if its items would take you over the limit

Requests rejected with 400 still count toward your limits.

Sharegain API Documentation