API reference / Wealth / MF

Capital gains + XIRR

FIFO matching, STCG/LTCG, grandfathering, XIRR.

POST/v1/mf/capital-gains
Authentication
Bearer token
Scope
mf:read

Before you integrate

  • Transactions may be sent in any order; they are sorted by date before matching.

Request body

FieldTypeRequiredDescription
transactionsarrayYesNon-empty list of buys and sells of one scheme.
transactions[].datestringYesTransaction date as YYYY-MM-DD or a full ISO 8601 date-time.
transactions[].typestringYesbuy or sell.
transactions[].unitsnumberYesUnits bought or sold; must be above 0.
transactions[].price_minorintegerYesNAV per unit in paise; 0 or more.
ltcg_daysintegerNoHolding days after which a gain counts as long-term; above 0. Defaults to 365.
fmv_31jan2018_minorintegerNoFair market value per unit on 31 January 2018 in paise, to apply grandfathering to older units.
current_nav_minorintegerNoToday's NAV per unit in paise, to include units still held in the XIRR. Needs valuation_date too.
valuation_datestringNoDate of current_nav_minor, as YYYY-MM-DD.

Sample code

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

curl -sS -X POST 'https://grappi.ai/v1/mf/capital-gains' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactions": [
    {
      "date": "2022-01-01",
      "type": "buy",
      "units": 100,
      "price_minor": 10000
    },
    {
      "date": "2024-01-01",
      "type": "sell",
      "units": 100,
      "price_minor": 15000
    }
  ]
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "realized": [
      {
        "buy_date": "2022-01-01",
        "sell_date": "2024-01-01",
        "units": 100,
        "term": "LTCG",
        "proceeds_minor": 1500000,
        "cost_minor": 1000000,
        "gain_minor": 500000
      }
    ],
    "total_stcg_minor": 0,
    "total_ltcg_minor": 500000,
    "total_gain_minor": 500000,
    "xirr": 0.224745,
    "warnings": []
  }
}

Response fields

FieldTypeDescription
realizedarrayEach sale matched to the units it sold, first in first out.
realized[].buy_datestringDate those units were bought.
realized[].sell_datestringDate they were sold.
realized[].unitsnumberUnits matched.
realized[].termstringSTCG or LTCG.
realized[].proceeds_minorintegerSale value in paise.
realized[].cost_minorintegerCost in paise, after grandfathering where it applies.
realized[].gain_minorintegerProceeds minus cost, in paise.
total_stcg_minorintegerTotal short-term gain in paise.
total_ltcg_minorintegerTotal long-term gain in paise.
total_gain_minorintegerTotal gain in paise.
xirrnumberAnnualised return as a fraction (0.18 means 18%); null when it cannot be worked out.
warningsarrayPlain-text issues, for example a sale of more units than were bought.

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.