Portfolio Rail

Portfolio Rail

Portfolio management, position tracking, and NAV calculation.

Overview

The Portfolio Rail provides endpoints for managing investment portfolios, tracking positions, calculating NAV, and monitoring performance.

Base URL

/api/v1/portfolios

Endpoints

Create Portfolio

POST /api/v1/portfolios

Create a new portfolio.

Request Body:

{
  "name": "Islamic Growth Fund",
  "type": "FUND",
  "currency": "USD",
  "benchmark": "DJIM",
  "inceptionDate": "2025-01-01",
  "managerId": "user_123",
  "shariahCompliant": true
}

Response:

{
  "data": {
    "portfolioId": "pf_abc123",
    "name": "Islamic Growth Fund",
    "type": "FUND",
    "currency": "USD",
    "status": "ACTIVE",
    "nav": "0.00",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Get Portfolio

GET /api/v1/portfolios/:portfolioId

Retrieve portfolio details including current positions.

List Portfolios

GET /api/v1/portfolios

Query Parameters:

Parameter	Type	Description
type	string	Filter by type (FUND, MANAGED, CUSTODY)
status	string	Filter by status
page	number	Page number

Add Position

POST /api/v1/portfolios/:portfolioId/positions

Add a position to the portfolio.

Request Body:

{
  "instrumentId": "inst_xyz",
  "instrumentType": "SUKUK",
  "quantity": "1000",
  "costBasis": "100000.00",
  "currency": "USD",
  "acquisitionDate": "2025-01-15"
}

List Positions

GET /api/v1/portfolios/:portfolioId/positions

Get all positions in a portfolio.

Response:

{
  "data": [
    {
      "positionId": "pos_123",
      "instrumentId": "inst_xyz",
      "instrumentType": "SUKUK",
      "quantity": "1000",
      "costBasis": "100000.00",
      "marketValue": "105000.00",
      "unrealizedPnL": "5000.00",
      "weight": "0.15"
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1
  }
}

Calculate NAV

POST /api/v1/portfolios/:portfolioId/nav/calculate

Calculate current Net Asset Value.

Request Body:

{
  "valuationDate": "2025-01-15",
  "pricingSource": "MARKET"
}

Response:

{
  "data": {
    "portfolioId": "pf_abc123",
    "valuationDate": "2025-01-15",
    "totalAssets": "1000000.00",
    "totalLiabilities": "50000.00",
    "nav": "950000.00",
    "navPerUnit": "95.00",
    "unitsOutstanding": "10000",
    "currency": "USD"
  }
}

Get Performance

GET /api/v1/portfolios/:portfolioId/performance

Query Parameters:

Parameter	Type	Description
period	string	MTD, QTD, YTD, 1Y, 3Y, SI
benchmark	string	Benchmark to compare

Response:

{
  "data": {
    "portfolioId": "pf_abc123",
    "period": "YTD",
    "return": "0.0825",
    "benchmarkReturn": "0.0750",
    "alpha": "0.0075",
    "sharpeRatio": "1.25",
    "volatility": "0.12"
  }
}

Rebalance Portfolio

POST /api/v1/portfolios/:portfolioId/rebalance

Generate rebalancing recommendations.

Request Body:

{
  "targetAllocations": [
    { "assetClass": "SUKUK", "weight": 0.4 },
    { "assetClass": "EQUITY", "weight": 0.35 },
    { "assetClass": "CASH", "weight": 0.25 }
  ],
  "tolerance": 0.05
}

Portfolio Types

Type	Description
FUND	Investment fund
MANAGED	Discretionary managed account
CUSTODY	Custody account
MODEL	Model portfolio

Events

Event	Description
portfolio.created	Portfolio created
portfolio.position.added	Position added
portfolio.position.closed	Position closed
portfolio.nav.calculated	NAV calculated
portfolio.rebalanced	Portfolio rebalanced

See Also

• Risk Rail - Risk management
• Treasury Rail - Treasury operations