curl https://www.oxfordledge.com/api/data?ticker=AAPL \
  -H "X-API-Key: ol_your_api_key_here"

{
  "ticker": "AAPL",
  "price": { "current": 187.44, "changePct": 1.23 },
  "metrics": { "pe": 28.5, "marketCap": "2.89T" }
}

API Documentation

Access Oxford Ledge's financial data programmatically. Stock quotes, fundamentals, SEC filings, screener, portfolio management, and more — all via a simple REST API.

Authentication

All API requests require authentication via an API key. Generate your key from Settings → API Keys in the platform.

Send your key in the X-API-Key header on every request — the only header that carries an Oxford Ledge key today (Authorization: Bearer is reserved for OAuth access tokens; a key sent as a Bearer token is treated as anonymous). Send a descriptive User-Agent too: bare curl / python-requests agents are refused on /api/* without a credential.

# Using curl
curl -H "X-API-Key: ol_your_api_key_here" \
     -H "User-Agent: my-research-script/1.0 (you@example.com)" \
  https://www.oxfordledge.com/api/data?ticker=AAPL

# Using Python requests
import requests

headers = {"X-API-Key": "ol_your_api_key_here",
           "User-Agent": "my-research-script/1.0 (you@example.com)"}
r = requests.get("https://www.oxfordledge.com/api/data",
               params={"ticker": "AAPL"},
               headers=headers)
data = r.json()

Base URL

API versioning is supported: /api/v1/* routes to the same handlers as /api/*. Both are interchangeable.

Rate Limits

Rate limits are applied per IP address. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Developer plans

Developer and Developer Pro include everything in Power User, plus a monthly allowance of data calls across every key on the account. Keys run on the hourly ladder above, and a plan puts them on Power User's 5,000 MCP calls an hour, which makes the monthly allowance reachable:

By default, calls beyond the allowance are refused with 402 until the next month and nothing accrues. On Developer, extra calls are then $0.002 per call, capped at $50/month by default (you can change the cap); on Developer Pro, $0.001 per call, capped at $250/month by default. Each plan's extra-call rate is twice its included rate, so outgrowing a plan never costs more than 2x. AI-backed tools bill credits separately. Because a plan includes Power User, every endpoint badged Researcher, Investor or Power User answers a plan holder's keys. Cancel the plan and its Power User access ends with it.

Extra calls: the rate, the cap, and how to turn them on

Extra calls are OFF until you turn them on, and turning them on is an explicit act: POST /api/billing/agent-plan/overage with {"cap_usd": 50} (signed in, CSRF header) records the rate shown above and the monthly limit you name. Send no cap_usd for the default limit, any amount up to 4x the plan price ($396 on Developer, $1,996 on Developer Pro) to set your own, or 0 to turn extra calls off again. The rate and the limit you agree to are the ones that bill you; a later price change, or a plan change, asks you again before anything accrues.

Only a successful call counts; errors (402, 403, 404, 429, 5xx) are never billed. At the limit, calls are refused with 402 and reason: "overage_cap" naming the accrued amount and the limit, until you raise it or the month resets. GET /api/billing/agent-plan shows the rate, your limit, and what has accrued this month (overage_accrued_usd); every metered response carries the price of that call in the X-OL-Per-Call-Cost header. Extra calls are added to your next monthly invoice as one line, never charged per call.

Without a plan: included on every tier

API access is included on every plan, Learner included, and a key with no Developer plan is never billed per call. It runs within the hourly limits in the table above: 100 MCP calls an hour on Learner, 500 on Researcher, 2,000 on Investor and 5,000 on Power User. A Developer plan adds a monthly allowance on top — 100,000 calls on Developer ($99/mo) or 1,000,000 on Developer Pro ($499/mo) — and extra calls past it are metered only if you turn them on.

Your month-to-date call count is at GET /api/billing/agent-usage.

Buy or check a plan, and create keys, in YOUR API KEYS: press K or open Settings → API keys, or open /?panel=api-keys while signed in.

Response Format

All responses are JSON. Successful responses return the data directly:

{
  "ticker": "AAPL",
  "price": {
    "current": 189.84,
    "change": 2.15,
    "changePercent": 1.14
  },
  "fundamentals": { ... },
  "fetchedAt": "2026-04-03T10:30:00"
}

Errors

Error responses include an error field with a human-readable message:

{
  "error": "No ticker provided"
}
// HTTP 400, 401, 403, 404, or 429

Common error codes:

• 400 — Missing or invalid parameter
• 401 — Authentication required (missing or invalid API key)
• 402 — Feature requires a higher subscription tier (403 is CSRF and admin)
• 429 — Rate limit exceeded or monthly budget reached
• 500 — Server error

Endpoints

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/data?ticker=AAPL"

{
  "ticker": "AAPL",
  "price": {"current": 189.84, "change": 2.15, "changePercent": 1.14},
  "fundamentals": {"marketCap": 2950000000000, "pe": 31.2, "eps": 6.08, ...},
  "profile": {"name": "Apple Inc", "sector": "Technology", ...},
  "filings": [{"form": "10-K", "filed": "2025-11-01", ...}],
  "fetchedAt": "2026-04-03T10:30:00"
}

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/ticker-search?q=apple"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/random-ticker"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/fundamentals-pit?ticker=AAPL&date=2025-06-30"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/screener?pe_max=20&sector=Technology"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/portfolio-positions"

curl -X POST -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "shares": 100, "cost_basis": 150.00}' \
  "https://www.oxfordledge.com/api/portfolio-positions"

curl -X DELETE -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL"}' \
  "https://www.oxfordledge.com/api/portfolio-positions"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/etf-data?symbol=SPY"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/news/search?ticker=AAPL&days=30&limit=10"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/fund-holdings?cik=0001067983"

curl -H "X-API-Key: $KEY" \
  "https://www.oxfordledge.com/api/bond-search?q=Apple"

Python SDK

The Python SDK is on PyPI as ol-sdk and is free on every tier, Learner included:

pip install ol-sdk
pip install "ol-sdk[pandas]"   # optional DataFrame support

import oxford_ledge_sdk as ol

ol.set_api_key("ol_live_your_api_key_here")

# Company profile and quote
company = ol.get_company("AAPL")

# Fundamentals, point-in-time fundamentals
fundamentals = ol.get_fundamentals("MSFT")
pit = ol.get_fundamentals_pit("MSFT", date="2025-06-30")

# Or hold a client for custom timeouts and retries
from oxford_ledge_sdk import OxfordLedgeClient
with OxfordLedgeClient(api_key="ol_live_your_api_key_here") as client:
    bonds = client.search_bonds("Apple")

MCP Tools

Oxford Ledge exposes 62 tools via the Model Context Protocol (MCP), so Claude, Codex, Cursor and other MCP clients can look things up in the same public filings the Ledge is built on. Step-by-step setup for each client is on the MCP page. Without a key, 45 of the 62 tools answer an anonymous call; a few more answer anonymously but refuse below a paid tier, and the rest need an API key (mint one under YOUR API KEYS on the dashboard — keys look like ol_live_…). Every tool, sorted by which of the three it is, is under Who answers what on the MCP page.

Claude Desktop Configuration

Install the package (pip install oxford-ledge-mcp), then add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "oxford-ledge": {
      "command": "oxford-ledge-mcp",
      "env": {
        "OXFORD_LEDGE_URL": "https://www.oxfordledge.com",
        "OXFORD_LEDGE_API_KEY": "ol_live_YOUR_KEY_HERE"
      }
    }
  }
}

Tool Catalog

The hosted catalog carries 62 tools. The pip package (oxford-ledge-mcp) runs 29 tools on your own machine: the SEC-EDGAR tools (and the FRED tools, with your own FRED key) run standalone with no Oxford Ledge account, most of the rest answer keyless once OXFORD_LEDGE_URL is set, and the Researcher-tier ones need OXFORD_LEDGE_API_KEY; the exact split is on the MCP page. The full, always-current list is machine-readable at /api/mcp/tools.json and browsable at /mcp — plan tool calls from that live list, not from a static table. Highlights (verified against the registry 2026-09-13):

Example: Peer Comparison

Ask Claude Desktop to compare multiple tickers in a single request:

// Claude Desktop prompt:
"Compare latest-fiscal-year fundamentals for AAPL, MSFT, GOOG, and AMZN"

// Claude will call ol_peer_fundamentals with:
{
  "tickers": ["AAPL", "MSFT", "GOOG", "AMZN"]
}

Bulk Data Export

Export latest-fiscal-year fundamentals extracted from SEC filings for many tickers at once. Available to Investor tier and above.

Bulk Fundamentals

Examples

// Latest-fiscal-year statement lines for multiple tickers
GET /api/data/bulk?tickers=AAPL,MSFT,GOOG&fields=fundamentals

// Statement lines plus margin / return ratios
GET /api/data/bulk?tickers=AAPL,MSFT&fields=fundamentals,metrics

Parameters

Every served row carries fiscalYear, periodEnd, filingDate and source: "sec"; JSON only. The export is not a market-data feed: no prices, volumes or market capitalization, and no company-profile fields from vendor sources.

Additional Resources

• Machine-readable endpoint schema — JSON list of all endpoints with params
• Health check — Server status and uptime
• Data coverage — See which data sources are available for a ticker
• Pricing — Tier comparison (Learner, Researcher, Investor, Power User)