ilovepsxAPI
Build with the API / Python integration

Get Pakistan Mutual Fund NAV Data in Python

Fetch Pakistan mutual fund NAV history in Python with secure API keys, canonical fund slugs, Decimal arithmetic and source-date checks.

ILovePSXEngineering & data guides
7 min read
On this page

A useful NAV integration needs more than a request that returns a number. You need the right fund, the date that number describes, an exact value and a clear response when the requested history is unavailable.

This tutorial uses Python's standard library and the ILovePSX Funds API to discover a Pakistan mutual fund and retrieve a bounded NAV history. The same canonical fund slug can later connect your dataset to report profiles, performance and portfolio disclosures where available.

The useful part, upfront.

  • Discover the canonical fund slug before requesting NAV records.
  • Read data.navs for history and meta.next_cursor for the next page.
  • Keep decimal strings, source dates and missing values intact.

Prepare a private Python environment#

Activate fund-service access through your existing ILovePSX account and create a secret API key with the read scopes your script needs. Fund discovery requires funds:read; NAV requests require nav:read. The current release is free with unlimited monthly usage, while weighted burst protection and bounded requests still apply.

Set ILOVEPSX_API_KEY in your local shell or job's secret configuration. Do not paste its value into a notebook committed to Git, an example response or a support message. The code below sends it only in the X-API-Key header to the fixed production host. It never includes the key in a URL or prints request headers.

Save the script as nav_history.py and run it with a current Python 3 installation. No third-party HTTP package is required. The opener refuses redirects so the secret cannot be forwarded to a different destination. A network connection and an activated key are required for real requests; this article does not embed a customer key or claim a particular fund currently has a complete history.

References: Authentication, scopes and request conventions

Discover the fund, then make an explicit selection#

Set FUND_QUERY to part of the name you are looking for. GET /v1/mutual-funds/funds returns registry matches, including each official_name and slug. A name search may return several plans or funds with similar labels, so taking the first row is an unsafe way to choose an investment identity.

The first run below prints a bounded list of candidates and stops if FUND_SLUG is unset. Check the AMC and classification in the reference or authenticated explorer, then set FUND_SLUG to the exact returned slug. If the candidate is beyond the first page, use the documented registry pagination or refine your search. Do not manufacture a slug from a display name.

A registry match confirms the identity can be addressed. It does not prove that NAV or monthly report facts exist for every requested period. Keep discovery and data availability as separate checks in your application.

References: ILovePSX public API reference

Fetch a bounded history without losing pagination#

Set NAV_FROM and NAV_TO to ISO dates if you want a specific range. Otherwise this example asks for the last fourteen calendar days. The API returns observations available within that range; it does not generate an observation for every calendar date.

History is nested under data.navs, unlike the registry list under data. The loop preserves the same fund, date range, order and page size while following the opaque cursor. A repeated cursor triggers an error instead of an infinite download. The page cap is an application safety limit, independent of your account's monthly allowance.

nav_history.py · standard-library example
import json
import os
from datetime import date, timedelta
from decimal import Decimal
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import HTTPRedirectHandler, Request, build_opener

BASE = "https://funds.api.ilovepsx.com/v1/mutual-funds"
KEY = os.environ["ILOVEPSX_API_KEY"]

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, request, fp, code, message, headers, newurl):
        return None

opener = build_opener(NoRedirect)

def api(path, params=None):
    query = urlencode(params or {}, doseq=True)
    url = BASE + path + ("?" + query if query else "")
    request = Request(url, headers={"X-API-Key": KEY})
    try:
        with opener.open(request, timeout=20) as response:
            return json.load(response)
    except HTTPError as error:
        request_id = error.headers.get("X-Request-ID", "unavailable")
        raise SystemExit(f"HTTP {error.code}; request ID {request_id}") from None
    except URLError:
        raise SystemExit("Network request failed; check connectivity.") from None

query = os.environ.get("FUND_QUERY", "")
candidates = api("/funds", {"q": query, "per_page": 10})
for fund in candidates["data"]:
    print(fund["slug"], fund["official_name"])

slug = os.environ.get("FUND_SLUG")
if not slug:
    raise SystemExit("Select a returned FUND_SLUG, then run again.")
profile = api("/funds/" + quote(slug, safe=""))["data"]
print("Selected:", profile["official_name"])

today = date.today()
params = {
    "from": os.environ.get("NAV_FROM", str(today - timedelta(days=14))),
    "to": os.environ.get("NAV_TO", str(today)),
    "order": "asc",
    "limit": 100,
}
rows, seen = [], set()
for _ in range(20):
    page = api("/funds/" + quote(slug, safe="") + "/nav", params)
    rows.extend(page["data"]["navs"])
    cursor = page["meta"].get("next_cursor")
    if not cursor:
        break
    if cursor in seen:
        raise SystemExit("Repeated cursor; stop and investigate.")
    seen.add(cursor)
    params["cursor"] = cursor
else:
    raise SystemExit("Page cap reached; use a smaller date range.")

for row in rows:
    value = None if row["nav"] is None else Decimal(row["nav"])
    print(row["nav_date"], value, row["currency"])
if not rows:
    print("No NAV observations returned for this fund and range.")

References: ILovePSX public API reference · Python documentation: urllib.request and redirect handlers

Read a synthetic history response#

This synthetic response excerpt describes the fictional Example Research Fund. The dates, public ID and values are invented to demonstrate the response structure; they are not observations retrieved from production. Additional NAV price and load fields are omitted for readability.

The three observations sit inside data.navs, while data.fund identifies their shared fund. The exact string 100.125000 stays intact even if a chart rounds its label. A null next_cursor ends this example's page traversal. No missing calendar observations are implied by the three selected rows.

Synthetic NAV history excerpt · fictional data
{
  "success": true,
  "data": {
    "fund": {
      "id": "11111111-1111-4111-8111-111111111111",
      "slug": "example-research-fund",
      "name": "Example Research Fund",
      "mufap_fund_id": 999999
    },
    "currency": "PKR",
    "from": "2026-09-28",
    "to": "2026-09-30",
    "order": "asc",
    "navs": [
      { "nav_date": "2026-09-28", "nav": "100.125000", "currency": "PKR" },
      { "nav_date": "2026-09-29", "nav": "100.250000", "currency": "PKR" },
      { "nav_date": "2026-09-30", "nav": "100.500000", "currency": "PKR" }
    ]
  },
  "meta": {
    "request_id": "synthetic-history-example",
    "generated_at": "2026-10-08T09:00:00Z",
    "data_as_of": "2026-09-30",
    "data_freshness_days": 8,
    "next_cursor": null
  }
}
Synthetic example, not live fund data

Every identifier, date and financial value in this excerpt is fictional. Use returned production identities and dates when running your own integration.

References: ILovePSX public API reference

Preserve exact decimals and the observed dates#

Financial decimals arrive as strings. Construct Decimal directly from those strings when doing Python arithmetic. Converting a value to float first defeats the purpose: the conversion can introduce a binary approximation before Decimal ever sees it. Keep the original string alongside any rounded display value you produce.

Use nav_date as the observation date. meta.generated_at describes response generation, while meta.data_as_of summarizes the returned dataset's date context. A successful request made today can legitimately contain an older observation. Your UI should show the source date next to the value and record retrieval time separately.

Do not forward-fill empty calendar dates in the ingestion layer. If an analysis requires a filled series, make that transformation explicit in a separate derived dataset. The raw observations should remain available so another developer can reproduce your result.

References: ILovePSX public API reference · Python documentation: Decimal arithmetic

Treat empty results and request errors differently#

An empty history is a valid data state for the chosen fund and range. A failed request is a transport or access state. Do not display zero NAV in either case. The example stops on an HTTP error and reports only the status and request ID, which is enough to begin troubleshooting without exposing credentials.

For production jobs, handle 401 or 403 by checking activation, key status and scopes. Correct invalid parameters after a 422 response. On 429, honor Retry-After when provided and reduce concurrency; an immediate retry loop adds pressure without fixing the cause. Limit retries for transient failures, and preserve the last successful dataset when a refresh fails.

Set a timeout, cap page traversal and keep checkpoints for long-running imports. If you export the observations, record the selected slug, date bounds and retrieval timestamp with the file. That context turns a CSV from an unexplained set of prices into an auditable input.

References: Authentication, scopes and request conventions

Connect NAV data to the whole fund#

NAV is one part of a fund research workflow. The registry supplies identity and classifications; available FMR facts add the report's profile, reported performance and portfolio context. Use the same canonical slug to request /funds/{fund_slug}/fmr-reports/latest?include=all when your key has fmr:read.

That expansion can include reported returns, holdings and allocation rows where promoted facts are available. Credit-quality and asset-allocation views also have focused operations in the reference. Preserve the monthly report_date independently of nav_date, and show empty or unavailable report sections explicitly.

Before adding a return chart, decide whether you are showing NAV movement or a source-reported performance measure. They are different datasets. This tutorial fetches NAV observations; it does not calculate a distribution-adjusted investor return or recommend a fund.

References: ILovePSX Fund Manager Reports API guide · ILovePSX public API reference

MOCK DATA / REAL RESPONSE STRUCTURE

Try a complete example.

Use these fictional records to prototype a full fund view: profile, reported returns, holdings, asset and sector allocations, credit quality, fees and ratings. Every name, identifier and number is invented. This is educational mock data, with no connection to a real fund, source document or agency opinion.

The JSON mirrors the public response structure. The complete FMR example includes all supported expansions; empty arrays and nulls demonstrate valid missing-data states. Your live integration must still request the sections it needs and check the returned coverage.

Full mock FMR JSON Mock latest NAV JSON
Inspect the complete FMR model
Complete synthetic FMR response · fictional data
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000101",
    "report_ids": [
      "00000000-0000-4000-8000-000000000101"
    ],
    "fund": {
      "id": "00000000-0000-4000-8000-000000000201",
      "slug": "example-research-fund",
      "name": "Example Research Fund",
      "mufap_fund_id": null,
      "amc": {
        "id": "00000000-0000-4000-8000-000000000301",
        "slug": "example-asset-management",
        "name": "Example Asset Management"
      }
    },
    "report_date": "2026-09-30",
    "currency": "PKR",
    "data_version": 1,
    "identity": {
      "fund_name_as_reported": "Example Research Fund",
      "fund_short_name_as_reported": "ERF",
      "parent_fund_name_as_reported": null,
      "plan_name_as_reported": null,
      "fund_type_as_reported": "Open-end",
      "category_as_reported": "Illustrative mixed-asset category",
      "risk_profile_as_reported": "Illustrative higher-risk profile",
      "is_shariah_compliant": false,
      "is_plan": false,
      "is_pension_scheme": false,
      "is_etf": false
    },
    "fund_size": {
      "nav_per_unit": "100.500000",
      "nav_date": "2026-09-30",
      "offer_price": "100.500000",
      "redemption_price": "100.500000",
      "repurchase_price": "100.500000",
      "market_price": null,
      "net_assets_pkr": "1005000000.0000",
      "fund_size_pkr": "1005000000.0000",
      "fund_size_including_fof_pkr": "1005000000.0000",
      "fund_size_excluding_fof_pkr": "1005000000.0000",
      "amount_invested_by_fof_pkr": "0.0000",
      "units_outstanding": "10000000.000000"
    },
    "profile": {
      "launch_date": "2025-01-01",
      "inception_date": "2025-01-01",
      "maturity_date": null,
      "benchmark": "Example composite benchmark",
      "old_benchmark": null,
      "new_benchmark": null,
      "benchmark_effective_date": null,
      "risk_of_principal_erosion": "Principal may fluctuate; synthetic disclosure.",
      "pricing_mechanism": "Forward pricing — illustrative",
      "dealing_days": "Monday to Friday — illustrative",
      "dealing_time": "09:00 to 14:00 Pakistan time — illustrative",
      "cutoff_time": "14:00 Pakistan time — illustrative",
      "settlement_period": "T+2 — illustrative, not an actual dealing policy",
      "minimum_initial_investment_pkr": "5000.0000",
      "minimum_subsequent_investment_pkr": "1000.0000",
      "minimum_redemption_pkr": "1000.0000",
      "unit_classes": [
        "Illustrative standard units"
      ],
      "leverage": "None in this synthetic example"
    },
    "report_fragments": [
      {
        "id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "schema_version": "fmr_page_v3",
        "data_version": 1,
        "promoted_at": "2026-10-08T08:00:00Z",
        "report_date": "2026-09-30",
        "report_month": "September 2026",
        "page_type": "FUND_REPORT",
        "extraction_mode": "PROFILE_PERFORMANCE_PORTFOLIO",
        "amc_name_raw": "Example Asset Management",
        "fund_name_raw": "Example Research Fund",
        "fund_short_name_raw": "ERF",
        "parent_fund_name_raw": null,
        "plan_name_raw": null,
        "fund_type_raw": "Open-end",
        "category_raw": "Illustrative mixed-asset category",
        "risk_profile_raw": "Illustrative higher-risk profile",
        "risk_of_principal_erosion_raw": "Principal may fluctuate; synthetic disclosure.",
        "is_shariah_compliant": false,
        "is_plan": false,
        "is_pension_scheme": false,
        "is_etf": false,
        "launch_date": "2025-01-01",
        "inception_date": "2025-01-01",
        "maturity_date": null,
        "benchmark_raw": "Example composite benchmark",
        "old_benchmark_raw": null,
        "new_benchmark_raw": null,
        "benchmark_effective_date": null,
        "par_value": "100.000000",
        "listing_raw": null,
        "leverage_raw": "None in this synthetic example",
        "nav_per_unit": "100.500000",
        "nav_date": "2026-09-30",
        "offer_price": "100.500000",
        "redemption_price": "100.500000",
        "repurchase_price": "100.500000",
        "market_price": null,
        "net_assets": "1005000000.0000",
        "fund_size": "1005000000.0000",
        "fund_size_including_fof": "1005000000.0000",
        "fund_size_excluding_fof": "1005000000.0000",
        "amount_invested_by_fof": "0.0000",
        "units_outstanding": "10000000.000000",
        "currency": "PKR",
        "pricing_mechanism_raw": "Forward pricing — illustrative",
        "dealing_days_raw": "Monday to Friday — illustrative",
        "dealing_time_raw": "09:00 to 14:00 Pakistan time — illustrative",
        "cutoff_time_raw": "14:00 Pakistan time — illustrative",
        "settlement_period_raw": "T+2 — illustrative, not an actual dealing policy",
        "minimum_initial_investment": "5000.0000",
        "minimum_subsequent_investment": "1000.0000",
        "minimum_redemption": "1000.0000",
        "unit_classes": [
          "Illustrative standard units"
        ]
      }
    ],
    "sub_funds": [],
    "reported_returns": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "period_label_raw": "1 year",
        "period_key": "1Y",
        "fund_return_percent": "12.00000000",
        "benchmark_return_percent": "10.00000000",
        "peer_return_percent": null,
        "return_type": "ABSOLUTE",
        "is_annualized": false,
        "is_since_inception": false,
        "calculation_basis_raw": "Synthetic cumulative return for the stated period"
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 2,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "period_label_raw": "Month to date",
        "period_key": "MTD",
        "fund_return_percent": "0.50000000",
        "benchmark_return_percent": "0.40000000",
        "peer_return_percent": null,
        "return_type": "ABSOLUTE",
        "is_annualized": false,
        "is_since_inception": false,
        "calculation_basis_raw": "Synthetic cumulative September return"
      }
    ],
    "allocations": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "ASSET_ALLOCATION",
        "label_raw": "Equities",
        "label_normalized": null,
        "percent_of_total_assets": "60.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "603000000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 2,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "ASSET_ALLOCATION",
        "label_raw": "Cash",
        "label_normalized": null,
        "percent_of_total_assets": "20.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "201000000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 3,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "ASSET_ALLOCATION",
        "label_raw": "Government securities",
        "label_normalized": null,
        "percent_of_total_assets": "15.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "150750000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 4,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "ASSET_ALLOCATION",
        "label_raw": "Other assets",
        "label_normalized": null,
        "percent_of_total_assets": "5.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "50250000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 5,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "SECTOR_ALLOCATION",
        "label_raw": "Technology",
        "label_normalized": null,
        "percent_of_total_assets": "25.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "251250000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 6,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "SECTOR_ALLOCATION",
        "label_raw": "Fertilizer",
        "label_normalized": null,
        "percent_of_total_assets": "20.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "201000000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 7,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "SECTOR_ALLOCATION",
        "label_raw": "Banks",
        "label_normalized": null,
        "percent_of_total_assets": "15.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": "150750000.0000",
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 8,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "CREDIT_QUALITY",
        "label_raw": "Government securities — illustrative bucket",
        "label_normalized": null,
        "percent_of_total_assets": "15.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": null,
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 9,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "allocation_type": "CREDIT_QUALITY",
        "label_raw": "Unrated / no rating assigned in this example",
        "label_normalized": null,
        "percent_of_total_assets": "85.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "amount": null,
        "current_period": null,
        "previous_period": null,
        "change_percent": null,
        "bucket_start_days": null,
        "bucket_end_days": null,
        "bucket_start_years": null,
        "bucket_end_years": null
      }
    ],
    "holdings": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "holding_group": "TOP_HOLDINGS",
        "rank": 1,
        "name_raw": "Example Technology Company",
        "holding_type": "EQUITY",
        "asset_class": "Equities",
        "issuer_name_raw": "Example Technology Company",
        "security_name_raw": "Example Technology Company ordinary shares",
        "symbol_raw": "EXTECH",
        "sector_raw": "Technology",
        "percent_of_total_assets": "18.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "percent_held": null,
        "market_value": "180900000.0000",
        "value_before_provisioning": null,
        "provisioning_amount": null,
        "value_after_provisioning": null,
        "quantity": "1000000.000000",
        "units": "shares",
        "credit_rating": null,
        "rating_agency": null,
        "instrument_type_raw": "Ordinary shares",
        "coupon_rate": null,
        "yield_percent": null,
        "ytm_percent": null,
        "issue_date": null,
        "maturity_date": null,
        "listed_or_unlisted": "Listed — illustrative",
        "secured_or_unsecured": null,
        "is_shariah_compliant": null,
        "is_top_holding": true,
        "is_non_compliant": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 2,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "holding_group": "TOP_HOLDINGS",
        "rank": 2,
        "name_raw": "Example Fertilizer Company",
        "holding_type": "EQUITY",
        "asset_class": "Equities",
        "issuer_name_raw": "Example Fertilizer Company",
        "security_name_raw": "Example Fertilizer Company ordinary shares",
        "symbol_raw": "EXFERT",
        "sector_raw": "Fertilizer",
        "percent_of_total_assets": "12.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "percent_held": null,
        "market_value": "120600000.0000",
        "value_before_provisioning": null,
        "provisioning_amount": null,
        "value_after_provisioning": null,
        "quantity": "800000.000000",
        "units": "shares",
        "credit_rating": null,
        "rating_agency": null,
        "instrument_type_raw": "Ordinary shares",
        "coupon_rate": null,
        "yield_percent": null,
        "ytm_percent": null,
        "issue_date": null,
        "maturity_date": null,
        "listed_or_unlisted": "Listed — illustrative",
        "secured_or_unsecured": null,
        "is_shariah_compliant": null,
        "is_top_holding": true,
        "is_non_compliant": null
      },
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 3,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "holding_group": "TOP_HOLDINGS",
        "rank": 3,
        "name_raw": "Example Banking Company",
        "holding_type": "EQUITY",
        "asset_class": "Equities",
        "issuer_name_raw": "Example Banking Company",
        "security_name_raw": "Example Banking Company ordinary shares",
        "symbol_raw": "EXBANK",
        "sector_raw": "Banks",
        "percent_of_total_assets": "8.000000",
        "percent_of_net_assets": null,
        "percent_of_gross_assets": null,
        "percent_held": null,
        "market_value": "80400000.0000",
        "value_before_provisioning": null,
        "provisioning_amount": null,
        "value_after_provisioning": null,
        "quantity": "500000.000000",
        "units": "shares",
        "credit_rating": null,
        "rating_agency": null,
        "instrument_type_raw": "Ordinary shares",
        "coupon_rate": null,
        "yield_percent": null,
        "ytm_percent": null,
        "issue_date": null,
        "maturity_date": null,
        "listed_or_unlisted": "Listed — illustrative",
        "secured_or_unsecured": null,
        "is_shariah_compliant": null,
        "is_top_holding": true,
        "is_non_compliant": null
      }
    ],
    "metrics": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "metric_key": "NUMBER_OF_HOLDINGS",
        "label_raw": "Illustrative number of equity holdings",
        "value": "12.00000000",
        "unit": "count",
        "period": "September 2026",
        "benchmark_value": null
      }
    ],
    "fees": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "fee_type": "TOTAL_EXPENSE_RATIO",
        "label_raw": "Illustrative annualized total expense ratio",
        "value_percent": "2.000000",
        "value_amount": null,
        "currency": "PKR",
        "period": "September 2026 — annualized illustration",
        "with_government_levies": true,
        "government_levy_percent": null,
        "secp_fee_percent": null,
        "is_actual_charged": true,
        "is_maximum_allowed": false
      }
    ],
    "ratings": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "rating_type": "ILLUSTRATIVE",
        "rating_raw": "Illustrative rating — not an agency opinion",
        "rating_agency": "Example agency (fictional)",
        "rating_date": null,
        "outlook_raw": null
      }
    ],
    "parties": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "role": "FUND_MANAGER",
        "name_raw": "Example Research Team",
        "designation_raw": "Illustrative fund-management team",
        "organization_raw": "Example Asset Management"
      }
    ],
    "special_terms": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "term_type": "INVESTMENT_OBJECTIVE",
        "label_raw": "Illustrative investment objective",
        "value_raw": "A fictional mixed-asset portfolio used only to demonstrate the response model.",
        "value_numeric": null,
        "value_percent": null,
        "value_amount": null,
        "value_date": null,
        "currency": "PKR"
      }
    ],
    "compliance": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "compliance_type": "ILLUSTRATIVE_DISCLOSURE",
        "name_raw": "Synthetic compliance disclosure",
        "limit_type_raw": null,
        "regulatory_limit_percent": null,
        "actual_exposure_percent": null,
        "excess_percent": null,
        "gross_assets_percent": null,
        "net_assets_percent": null,
        "status_raw": "Illustrative only — no regulatory assessment has been performed"
      }
    ],
    "notes": [
      {
        "sub_fund_key": null,
        "sub_fund_name_raw": null,
        "row_order": 1,
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "note_kind": "NOTE",
        "section_type": "PORTFOLIO",
        "note_type": "ILLUSTRATIVE",
        "text": "All figures and entities are synthetic. The three reported top holdings are a partial list. Sector percentages use total assets. Credit-quality labels and rating text are not agency opinions."
      }
    ],
    "source": [
      {
        "report_id": "00000000-0000-4000-8000-000000000101",
        "page_number": 1,
        "document": null,
        "promoted_at": "2026-10-08T08:00:00Z",
        "data_version": 1
      }
    ],
    "sections": {
      "sub_funds": {
        "status": "NOT_REPORTED",
        "row_count": 0
      },
      "reported_returns": {
        "status": "AVAILABLE",
        "row_count": 2
      },
      "allocations": {
        "status": "AVAILABLE",
        "row_count": 9
      },
      "holdings": {
        "status": "AVAILABLE",
        "row_count": 3
      },
      "metrics": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "fees": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "ratings": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "parties": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "special_terms": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "compliance": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "notes": {
        "status": "AVAILABLE",
        "row_count": 1
      },
      "source": {
        "status": "AVAILABLE",
        "row_count": 1
      }
    },
    "available_expansions": [
      "allocations",
      "compliance",
      "fees",
      "holdings",
      "metrics",
      "notes",
      "parties",
      "ratings",
      "reported_returns",
      "source",
      "special_terms",
      "sub_funds"
    ]
  },
  "meta": {
    "request_id": "00000000000040008000000000000401",
    "generated_at": "2026-10-08T08:00:00Z",
    "data_as_of": "2026-09-30",
    "data_freshness_days": 8
  }
}
Inspect the latest NAV model
Synthetic latest NAV response · fictional data
{
  "success": true,
  "data": [
    {
      "fund_id": "00000000-0000-4000-8000-000000000201",
      "fund_slug": "example-research-fund",
      "fund_name": "Example Research Fund",
      "mufap_fund_id": null,
      "nav_date": "2026-09-30",
      "nav": "100.500000",
      "offer_price": "100.500000",
      "repurchase_price": "100.500000",
      "market_price": null,
      "front_end_load_pct": "0.000000",
      "back_end_load_pct": "0.000000",
      "contingent_load_pct": null,
      "nav_change_abs": null,
      "nav_change_pct": null,
      "currency": "PKR"
    }
  ],
  "meta": {
    "request_id": "00000000000040008000000000000402",
    "generated_at": "2026-10-08T08:00:00Z",
    "data_as_of": "2026-09-30",
    "data_freshness_days": 8
  }
}
TRACE THE EVIDENCE

Sources & further reading

Check the published contract for current fields and limits. Source documents describe reported facts; API availability still depends on promoted production coverage.

  1. ILovePSX public API reference

    Endpoint names and response handling follow the current public contract.

  2. Authentication, scopes and request conventions
  3. ILovePSX Fund Manager Reports API guide
  4. Python documentation: Decimal arithmetic
  5. Python documentation: urllib.request and redirect handlers

Put the guide to work.

Start with the documented contract, keep your key server-side, and make dates and missing data visible in your product.

Open the API quickstart
KEEP THE CONTEXT
All guides