MCP readyRESTOpenAPI

Pakistan Stock Exchange data, built for machines

Deterministic, sourced and timestamped. Every number traces to a PSX filing, and the API tells you what it does not know instead of guessing.

Use it from an AI client

Point any MCP-compatible client at the endpoint below. You get typed tools with schemas — no guessing URLs, no parsing HTML.

{
  "mcpServers": {
    "psxlens": {
      "type": "http",
      "url": "https://api.psxlens.com/mcp"
    }
  }
}

Then ask plainly: “Which PSX dividend payers are down more than 5% from their 20-day high, excluding ex-dividend drops?”

Or call it directly

curl "https://api.psxlens.com/v1/screener?dividend_yield_min=1&daily_change_max=0&drawdown_20d_min=5&min_value_traded=5000000&exclude_ex_dividend=true"

Start here

Find a company
/v1/search?q=allied
Ticker from a name. The first call to make when you have "Allied Bank" and need ABL.

Everything about one company
/v1/stocks/{sym}
Profile, quote, ratios, peers, sector medians, dividends, filings and technicals in one call, plus a derived block with market cap, the 52-week range, circuit breaker bounds, margin and growth. The same payload the website renders.

Compare
/v1/compare?symbols=ABL,MEBL
Two symbols returns a scored head-to-head: every measure banded, a winner per measure and the totals. Three or more returns the winner per metric.

Screen the whole market
/v1/screener
Yield, drawdown, P/E, market cap, liquidity, free float, security type. Server-side over every listed security.

The rest of the surface

Market board
/v1/market/board
Indices, breadth, movers and sector tone in one call. Movers already exclude rights, preference and placeholder lines and anything under Rs 1m a day.

Sector board
/v1/sectors/board
Every sector with median change, P/E and yield, breadth counts and constituents. Medians, never means.

Dividend calendar
/v1/calendar/dividends
Announced payouts still open, each with last_buy_date and whether buying today still earns it.

Dividend history
/v1/dividends/{sym}
By fiscal year, trailing DPS and yield, with an explicit coverage window.

Prices
/v1/prices/{sym}?range=1Y
Daily closes for a named window (1M to 5Y), with that window's own high, low and change.

Financials
/v1/financials/{sym}
Income statement by period. Balance sheet lines are absent; see the limits below.

Filings
/v1/announcements/{sym}
PSX company announcements, labelled as filings rather than press.

Technicals
/v1/stocks/{sym}/technicals
Moving averages, oscillators, pivots and volatility as state labels, never a buy or sell rating.

Your own portfolio

Create a key at psxlens.com/api-access, then send it as Authorization: Bearer pl_live_…. A key reads market and company data by default; reading your holdings and recording trades are separate grants you tick on.

Holdings
/v1/me/holdings
Quantity, average cost, market value and P&L per position. Needs portfolio:read.

Record a trade
POST /v1/me/transactions
Buy, sell, dividend, bonus issue or split, with a trade date. Needs portfolio:write. Nothing here places a real order; there is no broker behind it.

Free, and what that does not cost you

Every endpoint above is free and needs no key, except the ones that read your own portfolio. There is no paid tier, no rate-limited "starter" plan and no feature held back. If something is missing it is because the data is missing, and the section below says which.

What we promise not to hide

Quotes are delayed and labelled so. PSX data is delayed at source.

Dividend history starts at data_coverage_start. A short record before that date means our window is short — not that a company stopped paying.

Prices are not corporate-action adjusted. A 30% bonus issue leaves a ~23% step that is not a fall.

coverage: "unknown" means we could not reach PSX for that symbol. It never means zero.

No balance sheet. Return on equity, price to book, debt to equity and free cash flow are absent for every company, not just some. PSX publishes those lines only inside audited filing PDFs, and nothing here extracts them yet. They are omitted rather than estimated.

The 52-week range is close-based for most symbols. The end-of-day feed carries no intraday high or low, so a spike within a session is not counted. Each response says which basis it used.

No Shariah screening and no index history. Only KSE-100 membership is tracked, so KMI compliance cannot be answered. Index levels are current-only, which is why portfolio benchmarking compares against KSE-100 constituents rather than the index itself.

A blank field is unknown, never zero. Nothing here fills a gap with a guess.