API reference / PMS / AIF

PMS performance

TWRR + XIRR from period values + cashflows.

POST/v1/pms/performance
Authentication
Bearer token
Scope
pms:read

Before you integrate

  • periods[].start_value_minor and end_value_minor are required inside each period you send, as are date and amount_minor inside each cashflow.

Request body

FieldTypeRequiredDescription
periodsarrayNoValue of the portfolio at the start and end of each sub-period, in order. Start a new period at every deposit or withdrawal. Defaults to empty.
periods[].start_value_minorintegerNoValue at the start of the period in paise. A period starting at 0 or below is skipped.
periods[].end_value_minorintegerNoValue at the end of the period in paise.
cashflowsarrayNoDated deposits and withdrawals, for the XIRR. Defaults to empty.
cashflows[].datestringNoDate as YYYY-MM-DD.
cashflows[].amount_minorintegerNoAmount in paise: money put in is negative; money taken out, and the final value, are positive.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/pms/performance' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "periods": [
    {
      "start_value_minor": 1000000,
      "end_value_minor": 1100000
    },
    {
      "start_value_minor": 1100000,
      "end_value_minor": 1210000
    }
  ],
  "cashflows": [
    {
      "date": "2023-01-01",
      "amount_minor": -1000000
    },
    {
      "date": "2024-01-01",
      "amount_minor": 1210000
    }
  ]
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "twrr": 0.21,
    "xirr": 0.21
  }
}

Response fields

FieldTypeDescription
twrrnumberTime-weighted return over all periods as a fraction (0.21 means 21%); null when no usable period was sent.
xirrnumberAnnualised return from the cashflows as a fraction; null when it cannot be worked out, for example with fewer than two flows or no sign change.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.