NZXplorer API

All API requests require authentication via an API key. Pass your key in one of two ways:

Keep your API key secret. Never expose it in client-side code or public repositories.

API routes are protected against automated scraping. Requests from known scraper user agents (including AI training bots like GPTBot, CCBot, and others) are blocked with a 403 response. All legitimate access requires an API key.

Add ?format=llm to any endpoint for token-optimized output. It drops the values we do not hold and the standard metadata envelope — but it always tells you which fields were dropped, in _absent.

{
  "data": {
    "ticker": "AIR",
    "name": "Air New Zealand",
    "description": null,
    "website_url": null,
    "directors": []
  },
  "meta": {
    "schema_version": "1.0.0",
    "api_version": "v1",
    "request_id": "req_...",
    "timestamp": "2026-09...",
    "provenance": "undeclared"
  }
}

{
  "ticker": "AIR",
  "name": "Air New Zealand",
  "directors": [],
  "_absent": ["description", "website_url"]
}

Add ?format=toon to any endpoint for maximum token compression. TOON (Token-Optimized Object Notation) encodes arrays of objects as pipe-delimited tabular data — 30-60% fewer tokens than JSON with lossless roundtrip fidelity.

[
  {"ticker":"AIR","name":"Air NZ","sector":"Industrials"},
  {"ticker":"FPH","name":"Fisher & Paykel","sector":"Healthcare"},
  {"ticker":"MEL","name":"Meridian","sector":"Utilities"}
]

ticker|name|sector
AIR|Air NZ|Industrials
FPH|Fisher & Paykel|Healthcare
MEL|Meridian|Utilities

Standard JSON responses carry a meta block with schema_version, request_id and a provenance state. Where an endpoint can cite the documents behind its rows, it also returns sources[].

?format=llm and ?format=toon return bare data with no envelope, so they carry the same facts on headers instead, at no token cost: X-Schema-Version, X-Provenance and, when known, X-Data-As-Of.

Every tool on the MCP server publishes an outputSchema and annotations, and every tools/call returns structuredContent matching it, alongside the existing text content. All tools are read-only (readOnlyHint: true, destructiveHint: false, openWorldHint: false) and every input schema is closed (additionalProperties: false).

{
  "schema_version": "1.0.0",
  "tool": "get_company_detail",
  "data": { "ticker": "AIR", "...": "..." },
  "meta": {
    "retrieved_at": "2026-09-16T01:51:00Z",
    "availability_status": "ok",
    "provenance": "undeclared",
    "encoding": "json"
  }
}

initialize negotiates the protocol revision (2025-06-18, 2025-03-26 or 2024-11-05). Clients on the older revision can ignore structuredContent entirely — it is additive.

Add ?format=fdc3 to supported endpoints for FINOS FDC3 v2.0 standard context types. Enables interoperability with Bloomberg, Refinitiv, IRESS, and other FDC3-compliant desktop applications. All 131 issuers have ISINs, and LEIs are available for 65/131 issuers (50% coverage) via the GLEIF register.

{
  "data": {
    "ticker": "AIR",
    "name": "Air New Zealand",
    "isin": "NZAIRE0001S2",
    "sector": "Industrials"
  }
}

{
  "type": "fdc3.instrument",
  "name": "Air New Zealand",
  "id": {
    "ticker": "AIR",
    "ISIN": "NZAIRE0001S2",
    "LEI": "XN8VX00V0UCRJ3ZGN385"
  },
  "market": {
    "MIC": "XNZE",
    "name": "New Zealand Exchange",
    "COUNTRY_ISOALPHA2": "NZ"
  }
}

An AI research assistant that uses all NZXplorer API endpoints to answer natural language questions about NZX-listed companies. Powered by Claude with tool-calling against 36 internal data tools. Features hybrid semantic search with reranking, structured copilot cards for rich visual output, and TOON token optimization for 30-60% cost reduction.

npx nzxplorer-agent

# Default (general) persona
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the governance score for Air NZ?"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# With persona (20 available: macro, governance, risk, buffett, fund_manager, journalist, etc.)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How does the OCR cycle affect utilities?", "persona": "macro"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# Resume a prior conversation (session memory)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What changed since we last discussed?", "session_id": "SESSION_UUID"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# List your sessions
curl -H "X-API-Key: YOUR_KEY" \
  "https://nzxplorer.co.nz/api/v1/ask/sessions"

Connect NZXplorer data directly to Claude Desktop, Cursor, or any MCP-compatible client. The remote MCP server exposes 189 tools wrapping the NZX API — including anomaly detection, market signals, accounting quality, IR quality, peer mentions, board briefings, and skills matrices. 5 of them (proxy reports, research briefings, director due diligence, semantic search, and the stock screener) require a Pro plan.

{
  "mcpServers": {
    "nzxplorer": {
      "url": "https://mcp.nzxplorer.co.nz"
    }
  }
}

One-click install

Add to CursorAdd to VS CodeInstall via Smithery

Claude Code CLI:

claude mcp add nzxplorer -- npx -y nzxplorer-mcp

Smithery CLI works for Claude Desktop, Cursor, Windsurf, and Goose — auto-edits your client config:

npx -y @smithery/cli@latest install @mambaventures/nzxplorer-mcp --client claude

Replace claude with cursor, windsurf, or goose as needed. After install, set NZXPLORER_API_KEY from your Settings → API & Developer page.

Manual install

npx nzxplorer-mcp

{
  "mcpServers": {
    "nzxplorer": {
      "command": "npx",
      "args": ["-y", "nzxplorer-mcp"],
      "env": {
        "NZXPLORER_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "nzxplorer": {
      "command": "npx",
      "args": ["-y", "nzxplorer-mcp"],
      "env": {
        "NZXPLORER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Get your API key above. Full setup docs (including local-build option) in the GitHub repo.