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


Related Pages