# 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/search?q= — find a ticker by company name. Start here if you have a name.
- GET /v1/stocks/{symbol} — everything about one company in one call, including a
  "derived" block with market cap, the 52-week range, circuit breaker bounds,
  margins and growth. This is the payload psxlens.com itself renders.
- GET /v1/screener — filter the whole universe server-side
- GET /v1/market/board — indices, breadth, movers and sector tone in one call
- GET /v1/sectors/board — every sector with medians, breadth and constituents
- GET /v1/compare?symbols=ABL,MEBL — side by side; two symbols adds a scored
  head-to-head with a winner per measure
- GET /v1/calendar/dividends — announced payouts and whether buying today still
  earns them, with the last buying day for each
- 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}?range=1Y — daily closes for a named window, with the
  window's own change
- GET /v1/stocks/{symbol}/technicals — moving averages, oscillators, levels
- GET /v1/sectors/{id}/valuation — median P/E and yield with peer counts
- GET /v1/me/portfolio — your own ledger; needs a key with portfolio:read
- 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.