Sharegain Lender Reporting API Specifications

📋 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).

All of these API flows also exist as optional SFTP file transfer options (CSV format) if this is preferred, and can be mixed as desired (i.e. flow X API, flow Y SFTP). All our APIs have RESTful endpoints supporting 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 are available for Lenders to consume as both 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