API Service - sgajbi/portfolio-analytics-system GitHub Wiki
Overview
The system exposes two main API entry points:
- Ingestion Service: Write API for submitting portfolios, transactions, instruments, prices, and FX rates.
- Query Service: Read API for retrieving processed and calculated data including portfolios, positions, transactions, instruments, prices, and cashflows.
Both are implemented using FastAPI.
Ingestion Service (Write API)
Base URL: http://localhost:8000
Method | Endpoint | Description |
---|---|---|
POST | /ingest/portfolios |
Ingest a list of portfolios |
POST | /ingest/instruments |
Ingest a list of instruments |
POST | /ingest/transactions |
Ingest a list of transactions |
POST | /ingest/market-prices |
Ingest a list of market prices |
POST | /ingest/fx-rates |
Ingest a list of FX rates |
GET | /health |
Service health check |
Sample request:
POST /ingest/transactions
Content-Type: application/json
{
"transactions": [
{
"transaction_id": "TX123",
"portfolio_id": "PORT1",
"instrument_id": "AAPL",
"security_id": "SEC_AAPL",
"transaction_date": "2025-08-01",
"transaction_type": "BUY",
"quantity": 10,
"price": 190.0,
"gross_transaction_amount": 1900.0,
"trade_currency": "USD",
"currency": "USD"
}
]
}
Query Service (Read API)
Base URL: http://localhost:8001
Core Endpoints
Method | Endpoint | Description |
---|---|---|
GET | /portfolios |
List all portfolios |
GET | /portfolios/{portfolio_id} |
Get details for a specific portfolio |
GET | /portfolios/{portfolio_id}/positions |
Get latest position for each security in a portfolio |
GET | /portfolios/{portfolio_id}/transactions |
Get all transactions for a portfolio |
GET | /portfolios/{portfolio_id}/cashflows |
Get all cashflows for a portfolio |
GET | /instruments |
List all instruments |
GET | /instruments/{security_id} |
Get instrument details |
GET | /prices |
List all market prices |
GET | /prices/{security_id} |
Get price history for a specific instrument |
GET | /fx_rates |
List all FX rates |
GET | /fx_rates/{from_currency}/{to_currency} |
Get FX rate history for a currency pair |
GET | /positions |
Get all positions across portfolios |
GET | /transactions |
Get all transactions across portfolios |
GET | /cashflows |
Get all cashflows across portfolios |
GET | /health |
Service health check |
Example: Get Portfolio Positions
Request
GET /portfolios/PORT1/positions
Sample Response
{
"portfolio_id": "PORT1",
"positions": [
{
"security_id": "SEC_AAPL",
"quantity": "50.0000000000",
"cost_basis": "9000.0000000000",
"instrument_name": "Apple Inc.",
"position_date": "2025-08-01",
"valuation": {
"market_price": "200.0000000000",
"market_value": "10000.0000000000",
"unrealized_gain_loss": "1000.0000000000"
}
}
]
}
Example: Get Portfolio Transactions
Request
GET /portfolios/PORT1/transactions
Sample Response
{
"portfolio_id": "PORT1",
"total": 2,
"skip": 0,
"limit": 100,
"transactions": [
{
"transaction_id": "TX_BUY_01",
"transaction_date": "2025-07-20T00:00:00",
"transaction_type": "BUY",
"security_id": "SEC_AAPL",
"quantity": "100.0000000000",
"price": "150.0000000000",
"gross_transaction_amount": "15000.0000000000",
"net_cost": "15000.0000000000",
"realized_gain_loss": null,
"currency": "USD",
"cashflow": {
"amount": "-15000.0000000000",
"currency": "USD",
"classification": "INVESTMENT_OUTFLOW",
"timing": "EOD",
"level": "POSITION",
"calculationType": "NET"
}
}
]
}
Other Useful Queries
-
Get all instruments
GET /instruments
-
Get market price for a security
GET /prices/SEC_AAPL
-
Get all cashflows for a portfolio
GET /portfolios/PORT1/cashflows
-
Get all FX rates
GET /fx_rates