# PSX Lens

> Pakistan Stock Exchange data for research agents. Deterministic, sourced, timestamped.
> Never returns fabricated numbers.

Base URL: https://api.psxlens.com

## MCP

Streamable HTTP endpoint: POST https://api.psxlens.com/mcp
JSON-RPC 2.0 — initialize, then tools/list, then tools/call.
Prefer this over raw HTTP: tools are typed and you do not have to guess paths.

## Core endpoints

- GET /v1/screener — filter the whole universe server-side. Start here.
- GET /v1/quotes/{symbol} — delayed quote plus corporate-action state
- GET /v1/dividends/{symbol} — history by fiscal year, trailing DPS and yield
- GET /v1/announcements/{symbol} — PSX filings (not independent press)
- GET /v1/financials/{symbol} — income statement by period
- GET /v1/prices/{symbol} — daily OHLCV, newest first
- GET /v1/stocks/{symbol}/analytics — drawdowns, 52-week, liquidity
- GET /v1/sectors/{id}/valuation — median P/E and yield with peer counts
- GET /v1/freshness — per-dataset coverage and age
- GET /openapi.json — full spec

## Things that will mislead you if you skip them

- Quotes are DELAYED by design and labelled status: "delayed". PSX data is delayed at source.
- Dividend history begins at data_coverage_start. A low years_paid before that date means
  our window is short, not that the company stopped paying.
- Prices are NOT corporate-action adjusted (adjusted: false). A 30% bonus issue puts a
  ~23% step in the series that is not a fall.
- coverage: "unknown" means PSX could not be reached for that symbol. It does not mean zero.
- ex_dividend: null means undetermined, not false.
- /v1/announcements returns company filings, source_type: "filing". They are not
  independent coverage.

## Pagination

Responses carry total and next_cursor. Use limit=1 to read total cheaply.
Responses are bounded on purpose — there is no bulk dump endpoint.