Portfolio Analysis API
Returns the lending rate, utilisation and potential return for a list of securities.
Endpoint
POST /public/portfolio-analysisFull URL: https://api.sharegain.com/public/portfolio-analysis
Headers
| Header | Value |
|---|---|
X-SG-Authorization | Your API key |
Content-Type | application/json |
X-SG-ApiVersion | Optional. 1 |
Request Body
{
"identifiers": [
{ "requestKey": "1", "isin": "US5949181045" },
{ "requestKey": "2", "isin": "US123" }
],
"includeExtraIdentifiers": true,
"includeRecommendedUnits": true
}| Field | Type | Description |
|---|---|---|
identifiers | array | Required. 1–200 securities per request |
includeExtraIdentifiers | boolean | Optional, default false. Adds compositeBbgid and compositeTicker to each result |
includeRecommendedUnits | boolean | Optional, default false. Adds recommendedUnitsToAdd to each result |
Instrument Identifier Parameters
Each item needs a requestKey and at least one of isin, compositeBbgId or ticker.
| Parameter | Type | Description |
|---|---|---|
requestKey | string | Required. Your own reference for the item, unique within the request. Returned with the result |
isin | string | 12 characters, uppercase, e.g. US5949181045 |
compositeBbgId | string | 12 alphanumeric characters, e.g. BBG000BPH459 |
ticker | string | Ticker or composite ticker, e.g. MSFT or MSFT US. Not case-sensitive |
exchange | string | Optional. Two uppercase letters, e.g. UW |
mic | string | Optional, e.g. XNAS |
country | string | Optional, e.g. US |
Identifying securities
- Only a composite Bloomberg ID or a composite ticker such as
MSFT USpins a single listing. An ISIN or a plain ticker such asMSFTcan 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,compositeBbgIdandticker, they must all refer to the same security. exchange,micandcountryare accepted but are not currently used to identify the security.- Field names are not case-sensitive. Unknown fields are ignored.
Response
{
"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
| Status | Meaning |
|---|---|
200 OK | Every item succeeded |
206 Partial Content | At 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
| Field | Description |
|---|---|
requestKey | The reference you sent |
isin | The ISIN of the matched security, including when you identified it by ticker or Bloomberg ID |
potentialReturn | Estimated 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 |
lendingRateBps | Volume-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 |
utilization | Share 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 |
date | As-of date of the market data (ISO 8601, UTC) |
compositeBbgid, compositeTicker | Only when includeExtraIdentifiers is true. Omitted when unavailable |
recommendedUnitsToAdd | Only 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.
| Limit | Rule |
|---|---|
| Items per request | 200, for every account |
| Requests per minute | Rolling 60-second window |
| Requests per day | Resets at 00:00 UTC |
| Items per day | Resets 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.