Sharegain Lender Reporting API Specifications
Proposed specification
These endpoints are planned and not yet available. Some of these data flows are available today through SFTP file transfer. Contact your Sharegain account manager to find out which.
📋 Overview
This document describes the API integration options for Lenders connecting to Sharegain's Securities Lending as a Service (SlaaS) platform. The integration consists of inbound APIs (Lender → Sharegain) and outbound APIs (Sharegain → Lender).
Once available, each API flow will also be offered as an SFTP file transfer (CSV format), and the two can be mixed (for example flow X by API, flow Y by SFTP). The APIs will be RESTful, with JSON payloads.
🔵 Inbound APIs (Lender → Sharegain)
These endpoints allow lenders to push data to Sharegain. Authentication via OAuth 2.0 client credentials or API key.
1️⃣ Positions API
| Purpose | Provide Sharegain with your current total settled position holdings to determine lendable inventory. |
| Frequency | Daily (end-of-day) |
| HTTP Method | POST /api/v1/positions |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Security Identification | ISIN (primary), ticker, exchange, external instrument ID |
| Holdings | Quantity, currency |
| Client/Account | Client ID (anonymised underlying client unique identifier), custody account ID, depositary (BIC) |
| Lending Eligibility | Tax rate (withholding %, conditional requirement depending on custody structure), position status (e.g., Recall) |
📝 Integration Notes
- Full snapshot of inventory
- Securities must be identified by ISIN and one country or composite exchange level identifier at minimum
- External instrument ID is an optional unique internal identifier from your system that we will return to you on all reporting, enabling 1:1 mapping.
- Position status drives immediate loan availability adjustments, optional feature.
- Depositary BIC used for settlement routing, conditional requirement if assets of the same market and security type are comingled across domestic & ICSD depositories.
Example Use Case
Lender sends nightly position file showing 10,000 units of VGOV LN (IE00B42WWV65) available for lending at 70% withholding tax rate.
2️⃣ Transactions API
| Purpose | Notify Sharegain of buy/sell activity affecting lendable positions intraday. |
| Frequency | Intraday (real-time or batched) |
| HTTP Method | POST /api/v1/transactions |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Transaction Reference | Unique transaction ID |
| Client/Account | Client ID, account ID |
| Security | ISIN, ticker, exchange, external instrument ID |
| Trade Details | Buy/Sell indicator, units, trade date, settlement date |
| Settlement | Depositary BIC |
📝 Integration Notes
- Enables Sharegain to anticipate settlement impact on loans, by netting transactions and adjusting inventory in near-real-time
- Sell transactions trigger potential recall processing
- Transaction ID must be unique and idempotent
Example Use Case
Client sells 800 units of VGOV settling T+2 — Sharegain adjusts loan availability accordingly.
3️⃣ Settlement Status API (optional)
| Purpose | Provide real-time settlement status updates for pending trades (typically sourced from SWIFT/DTC/CREST). This is only required if we are not receiving settlement status updates directly from your custody system(s), where we typically consume SWIFT-formatted or custodian-specific templates inbound to Sharegain. |
| Frequency | Intraday |
| HTTP Method | POST /api/v1/settlement-status and via webhook |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Trade Reference | Account number, trade ID, trade type (Loan, Return, Recall) |
| Trade Details | Original units, settled units, trade date, intended settlement date, actual settlement date |
| Security | ISIN |
| Settlement Info | PSET/Depository (BIC), settlement status, settlement substatus, substatus narrative |
| Counterparty | Borrower code |
🔄 Settlement Status Values
| Status | Description |
|---|---|
Pending | Trade awaiting settlement |
Matched | Counterparty matched, awaiting execution |
Settled | Trade successfully settled |
Failed | Settlement failure (with narrative) |
📝 Integration Notes
- Critical for loan lifecycle management
- Substatus narrative provides reason codes for fails
- Actual settlement date populated only upon completion
- Supports both push (webhook) and pull (polling) patterns
Example Use Case
Loan L1001 shows status "Pending / Matched" — trade is matched with BAML awaiting MGTCBEBE Euroclear settlement.
4️⃣ Client Reference API
| Purpose | Manage client-level preferences including lending opt-in/opt-out status and fee splits. |
| Frequency | Daily or on-change |
| HTTP Method | POST /api/v1/client-reference or PATCH /api/v1/clients/{clientId} |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Effective Date | Date the preference applies from |
| Client ID | Unique client identifier in lender's system |
| Opt-In Status | In (participate in lending) or Out (excluded) |
| Fee Split | Client's share of lending revenue (percentage) |
📝 Integration Notes
- Opt-out clients are immediately excluded from new loan matching
- Fee split determines revenue allocation in billing
- Changes are effective from the specified date forward
- Historical changes should not be backdated
Example Use Case
Client 1 opts out of lending program with 80% fee split — no new loans will be allocated to their holdings.
🟢 Outbound APIs (Sharegain → Lender)
These will be available to consume as webhook subscriptions or polling endpoints.
5️⃣ Loans API — Custody Level
| Purpose | Comprehensive view of all loans at the aggregator custody account level. |
| Frequency | Daily & intraday snapshot |
| HTTP Method | GET /api/v1/loans/custody or webhook subscription |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Loan Identity | Loan ID, loan status, loan type, collateral type |
| Quantities | Original units, settled units |
| Economics | Lending rate, investment rate, rebate rate, fee split, margin %, haircut % |
| Lifecycle Dates | Trade date, collateral date, settlement date, end date |
| Parties | Lender code/name, account number, borrower code/name (including external borrower code) |
| Security | Instrument name, ISIN, composite ticker, country ticker, BBGID, external instrument ID, instrument type, country of incorporation/listing |
| Valuation | Market price, market currency, market value, FX rate, loan price, loan value, loan currency |
| Tax & Accruals | Withholding tax rate, loan-to-date accruals (gross, agent, net) |
🏷️ Loan Status Values
| Status |
|---|
Pending - Uncovered |
Pending - Covered |
Open |
Closed |
Cancelled |
📝 Integration Notes
- Custody-level aggregates underlying client loans for operational simplicity
- Market/loan value includes FX conversion for multi-currency portfolios
- Accruals are cumulative loan-to-date figures
- Supports filtering by status, date range, borrower, security
Example Use Case
Lender retrieves all open loans to reconcile against their books — sees L2001 for 10,000 ACB CA shares with Barclays at 72bps.
6️⃣ Loans API — Client Level
| Purpose | Granular view of loans at the underlying client level, including sub-allocation details. |
| Frequency | Daily & intraday snapshot |
| HTTP Method | GET /api/v1/loans/clients or webhook subscription |
📦 Key Data Elements
All custody-level fields, plus:
| Category | Fields |
|---|---|
| Sub-Loan Reference | Loan ID (client-level), Actual Loan ID (physical transfer reference) |
| Tiered Economics | Lending rate (gross bank), lending rate (net bank/gross client), lending rate (net client) |
| Tiered Fee Splits | Fee split (bank), fee split (client) |
| Tiered Accruals | Loan-to-date accrual (net bank), loan-to-date accrual (net client) |
| Client Identifiers | Client instrument ID |
📝 Integration Notes
- Enables for client-level revenue attribution and reporting
- Actual Loan ID links sub-allocations to physical settlement
- Three-tier rate structure supports agent/bank/client fee waterfalls
- The Client instrument ID maps to the Lender's external instrument ID provided in the positions API
Example Use Case
Lender needs to report lending revenue per underlying retail client — sees client CL1 earned 216.43 on their portion of L2001.
7️⃣ Trades API
| Purpose | All pending and recently settled trades including lifecycle status for reconciliation and audit. |
| Frequency | Daily & intraday snapshot |
| HTTP Method | GET /api/v1/trades |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Trade Details | Trade ID, trade type, trade status, original units, settled units, outstanding settlement units |
| Trade Dates | Trade date, intended settlement date, actual settlement date |
| Trade Values | Trade value (market currency), trade value (loan currency) |
| Linked Loan | Full loan details (ID, status, type, original/settled units, all rates, all dates, and other details including parties, security, valuations and terms) |
🏷️ Trade Types & Status Values
| Trade Types | Trade Status Values |
|---|---|
| Loan | Pending |
| Return | Settled |
| Recall | Cancelled |
📝 Integration Notes
- Trade ID format indicates relationship (e.g., L2005/1 is first return on L2005)
- Outstanding settlement units shows partial settlement progress
- Actual settlement date null until fully settled
- Valuable for fail management and settlement efficiency reporting
Example Use Case
Lender queries pending trades to identify settlement delays — sees L2005/1 return for 4,000 units still outstanding.
8️⃣ Position Reconciliation API
| Purpose | Simplified reconciliation view showing net traded vs. net settled positions per client/security/borrower. |
| Frequency | Daily |
| HTTP Method | GET /api/v1/position-reconciliation |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Parties | Lender code/name, account number, client borrower code, borrower code/name |
| Security | Instrument name, ISIN, composite ticker, country ticker, BBGID, client instrument ID |
| Position Summary | Net traded units, net settled units |
📝 Integration Notes
- Aggregated view for operational dashboards and custody reconciliation
- Client borrower code enables lender-side reconciliation
Example Use Case
Client CL2 shows 50,000 traded but 0 settled with BAML on FST US — indicates pending settlement.
9️⃣ Accruals API
| Purpose | Daily indicative accruals for active loans, supporting revenue forecasting and billing reconciliation. |
| Frequency | Daily |
| HTTP Method | GET /api/v1/accruals |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Accrual Date | Date the accrual applies to |
| Position & Valuation | Settled units, market price/currency, FX rate, loan price/value/currency |
| Rate Components | Investment rate/amount, rebate rate/amount, lending rates (gross bank, net bank, net client) |
| Calculation Basis | Day count basis (e.g., 360, 365) |
| Fee Splits | Fee split (bank), fee split (client) |
| Accrual Amounts | Accrual (gross), accrual (agent), accrual (net), accrual (net bank), accrual (net client) |
| Loan & Party Details | Full loan reference, lender/borrower identifiers |
| Security Details | Full instrument identification |
📝 Integration Notes
- Day count basis affects accrual calculations (actual/360 vs actual/365)
- Indicative figures — final billing may adjust for rate changes
- Net client accrual represents end-investor earnings
Example Use Case
Daily accrual file shows CL1 earning $6.11 net on their 350,000 BHP position at 1.5% gross rate.
🔟 Collateral API
| Purpose | Detailed breakdown of triparty collateral allocated against loans, at underlying client level. |
| Frequency | Daily |
| HTTP Method | GET /api/v1/collateral |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Collateral Context | Date, triparty agent, RQV account |
| Parties | Lender code/name, account number, borrower code/name (including external code) |
| Collateral Type | Cash or Non-Cash |
| Instrument Details | Name, ISIN, ticker, BBGID, instrument type, issuer, maturity date |
| Credit Quality | Moody's rating, S&P rating |
| Valuation | Quantity, market price/currency/value, FX rate, collateral price/currency/value |
| Haircut | Haircut %, collateral value with haircut applied |
📝 Integration Notes
- Triparty agent identifies collateral manager (e.g., JP Morgan, BNY Mellon)
- RQV account is the required collateral value account reference
- Haircuts reduce collateral credit based on instrument risk
- Credit ratings enabling collateral eligibility monitoring
- Supports regulatory reporting (SFTR, etc.)
Example Use Case
JP Morgan triparty holding shows US Treasury notes (AA1/AAA) allocated to CL1 with 5% haircut, net value $1.2M.
1️⃣1️⃣ Income Distribution API
| Purpose | Corporate action income (dividends, etc.) requiring payment processing. |
| Frequency | Ad hoc |
| HTTP Method | POST /api/v1/income-distribution and via webhook |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Event Timing | Date, intended value date, record date |
| Event Type | Type (e.g., "Corporate Event Income") |
| Counterparty | Borrower code, external borrower code |
| Payment Details | Currency, gross dividend per share, quantity on loan, payment value |
| Corporate Action Reference | Corporate action ID, corporate action type (e.g., Cash Dividend) |
| Security | ISIN, external instrument ID |
📝 Integration Notes
- Manufactured dividend payments from borrower to lender
- Corporate action ID enables event reconciliation
Example Use Case
Cash dividend of $1.15/share on CA7142661031 — 1,000 shares on loan requires $1,150 payment from MS by 28/07/2025.
1️⃣2️⃣ Client Revenue API
| Purpose | Monthly summary of lending revenues attributed to underlying retail clients and the aggregator. |
| Frequency | Monthly |
| HTTP Method | GET /api/v1/client-revenue |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Period | Billing month |
| Client | Client code |
| Revenue | Billing currency, net client revenue, net aggregator revenue |
📝 Integration Notes
- Currency indicates billing denomination
- Net revenue after all fee splits applied reflected
- Aggregator revenue represents the Lender's retained share
Example Use Case
February billing shows sub_account A earned €1,000 net, with matching €1,000 to the Aggregator.
1️⃣3️⃣ Billing Summary API
| Purpose | Monthly summary of total revenue payments due from borrowers. |
| Frequency | Monthly |
| HTTP Method | GET /api/v1/billing-summary |
📦 Key Data Elements
| Category | Fields |
|---|---|
| Period | Billing month |
| Borrower | Borrower code, external borrower code |
| Amounts | Billing currency, gross accrual, Sharegain accrual, other agent accrual, net accrual, net client revenue |
📝 Integration Notes
- Reconciles to borrower invoices
- Net accrual = gross − Sharegain − other agents
- Net client revenue represents underlying client share
Example Use Case
February billing shows €15,000 gross from Borrower1, €3,000 to Sharegain, €12,000 net to lender/clients.
⚙️ Technical Integration Requirements
🔐 Authentication
- OAuth 2.0 Client Credentials flow for server-to-server integration
- API keys supported for simpler implementations
- All endpoints require TLS 1.2+
📄 Data Formats
| Type | Format |
|---|---|
| Request/Response | JSON (Content-Type: application/json) |
| Date/Time | ISO 8601 format (e.g., 2025-01-21T14:30:00Z) |
| Currency | ISO 4217 codes (e.g., USD, EUR, GBP) |
| Country | ISO 3166-1 alpha-2 codes (e.g., US, GB, DE) |
| Identifiers | BIC codes for settlement agents/depositaries |
📑 Pagination
- Large result sets return paginated responses
- Standard cursor-based pagination with next cursor and limit parameters
⚠️ Error Handling
Standard HTTP status codes with error responses including error_code, message, and details fields.
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |