API · v1 · Live

Market intelligence for terminal-native agents.

Mountainhead is a market intelligence layer over public movement events, publisher feeds, social chatter, owner/ticker metadata, official disclosures, lobbying, and AI/MCP explanations. We do the joining, ranking, citing, and follow-up question generation so your terminal, Polymarket, Kalshi, equity, newsroom, or agent workflow can move from raw evidence to the questions that matter.

What changed?Why now?What should the terminal check next?
Quickstart Interactive reference

Free includes 50 API credits / month. No credit card.

Connect an agent via MCP

Setup guide

No key to paste — run this in Claude Code and approve once in your browser. Using the Claude app? Add to Claude copies the server URL and opens Customize → Connectors, where you paste it into Add custom connector.

Claude Code
claude mcp add --transport http mountainhead https://www.mountainhead.ai/api/mcp
Add to ClaudeAdd to Cursor

Base URL https://www.mountainhead.ai · Auth Bearer mh_live_… · JSON · UTF-8

01

Watch a market

TSLA, OpenAI, election odds, CEO succession, regulatory events.

02

Catch the signal

Congress trade, insider filing, lobbying spend, publisher hit, community thread, movement event.

03

Route the action

Update the terminal, alert a trader, refresh a Kalshi/Polymarket model, ask an agent.

Quickstart

From sign-up to first signal in three steps.

No SDK required. Curl works.

  1. 1

    Create an API key

    Every signed-in account starts with 50 API credits / month on the Free plan — no credit card required. Click below to sign up (or sign in) and the Account page will mint your firstmh_live_ key automatically. Keys are shown exactly once, so store yours as an environment variable.

  2. 2

    Verify it works

    GET /api/v1/me echoes your plan, scopes, and remaining quota. Any valid key can call it — perfect for health checks.

    curl https://www.mountainhead.ai/api/v1/me \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"
  3. 3

    Pull your first market feed

    Filter by owner, ticker, signal kind, severity, or time. For equities desks, ticker=TSLA gives you Elon/Tesla-linked news and movement signals in one feed. Follow next_cursor to paginate.

    curl "https://www.mountainhead.ai/api/v1/signals?ticker=TSLA&limit=5" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

Authentication

Bearer keys with scoped permissions.

One header. No signing. No rotating tokens.

Every request needs an Authorization: Bearer mh_live_… header. Keys belong to a single user and inherit that user's plan and scopes.

  • Provision: Account → API keys. Free includes 50 credits / month; Pro and Intel include more and unlock metered overage.
  • Storage: the plaintext key is shown exactly once. We only store a hash.
  • Rotation:mint a new key, deploy, then revoke the old one. There's no downtime — both work in parallel.
  • Never ship in client code. Keys bill against your account. Always call the API server-side.

Scopes

Calls without the right scope return 403 forbidden_scope.

  • read:signalsList and read research signals.
  • read:eventsSanitized flight events feed.
  • read:ownersPublic owner directory and holdings.
  • read:newsNormalized publisher feed.
  • read:marketMarket snapshots, company terminal, macro data.
  • read:filingsSEC filings, insider trades, congress trades, official profiles.
  • stream:eventsSSE live feed (Intel only).

Use cases

Market workflows, not disconnected feeds.

Use Mountainhead like a terminal-grade signal layer: owner keys, tickers, official activity, source evidence, severity, and stable cursors.

AIAsk AI / MCP layer

The API gives agents a curated knowledge list.

Your app can pull the cited signal list directly, or hand it to Ask AI / MCP to generate explanations, follow-up questions, and routing logic for a trader, reporter, or research agent.

Suggested questions

  • What changed for this owner in the last 24 hours?
  • Which items are news, social chatter, or flight movement?
  • What should a Polymarket / Kalshi desk check next?
  • Which signals are strong enough to wake up an analyst?

Possible explanations

  • A publisher hit is strong when it lines up with a tracked owner, ticker, and fresh movement context.
  • A social thread matters when the source, score, and confidence show the narrative is moving before official filings.
  • A landing becomes useful when it can be checked against court dates, board calendars, product events, or deal activity.
01

Polymarket / Kalshi / equities

news + chatter + last public location · same owner_key

A market desk gets the brief, not the homework.

A prediction-market desk can watch markets like “Musk at Tesla,” “OpenAI governance,” or TSLA volatility by joining owner/ticker signals to its own watchlist. One call returns the relevant publisher hits, social threads, landing context, scores, and follow-up prompts an analyst or agent can act on.

Request

curl "https://www.mountainhead.ai/api/v1/signals?owner_key=elon-musk&limit=5" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

Response (real shape)

JSON200 OK
{
  "signals": [
    {
      "id": "news:https://www.reuters.com/business/elon-musks-trial-against-sam-altman...",
      "kind": "general_news",
      "title": "Elon Musk's trial against Sam Altman to reveal ongoing power struggle for OpenAI",
      "thesis": "Publisher coverage tied to Elon Musk and OpenAI governance risk.",
      "owners": [{ "owner_key": "elon-musk", "owner_name": "Elon Musk", "ticker": "TSLA" }],
      "occurred_at": "2026-04-27T15:59:04+00:00",
      "score": 0.72,
      "confidence": "high",
      "severity": null,
      "evidence": [
        {
          "kind": "news",
          "label": "Reuters",
          "url": "https://www.reuters.com/business/elon-musks-trial-against-sam-altman...",
          "source_type": "news",
          "publisher": "Reuters"
        }
      ]
    },
    {
      "id": "landing:N272BG:2026-04-27T14:58:56.384+00:00",
      "kind": "landing",
      "title": "Elon Musk landed near San Jose",
      "thesis": "Recent arrival worth checking against Tesla, xAI, OpenAI, court, and board calendars.",
      "owners": [{ "owner_key": "elon-musk", "owner_name": "Elon Musk", "ticker": "TSLA" }],
      "occurred_at": "2026-04-27T14:58:56.384+00:00",
      "detected_at": "2026-04-27T14:59:01.742Z",
      "score": 0.349,
      "confidence": "medium",
      "severity": 1,
      "evidence": [
        {
          "kind": "flight_event",
          "label": "Landing · KSJC",
          "occurred_at": "2026-04-27T14:58:56.384+00:00",
          "source_type": "flight_event"
        }
      ],
      "watch_next": "Ask AI: what TSLA / OpenAI / xAI catalysts are near San Jose this week?"
    },
    {
      "id": "reddit:https://www.reddit.com/r/teslainvestorsclub/comments/...",
      "kind": "insider_chatter",
      "title": "Tesla investor thread turns to robotaxi timing",
      "thesis": "High-engagement community thread tied to the same owner/ticker watchlist.",
      "owners": [{ "owner_key": "elon-musk", "owner_name": "Elon Musk", "ticker": "TSLA" }],
      "occurred_at": "2026-04-27T14:21:00+00:00",
      "score": 0.681,
      "confidence": "high",
      "severity": null,
      "evidence": [
        {
          "kind": "reddit",
          "label": "r/teslainvestorsclub",
          "source_type": "reddit",
          "publisher": "r/teslainvestorsclub"
        }
      ],
      "watch_next": "Compare thread direction with publisher coverage before alerting the desk."
    },
    {
      "id": "news:https://www.investors.com/news/tesla-stock-elon-musk-robotaxi/",
      "kind": "general_news",
      "title": "Elon Musk Registers 304 Million Tesla Shares. Stock Sinks.",
      "owners": [{ "owner_key": "elon-musk", "ticker": "TSLA" }],
      "occurred_at": "2026-04-27T13:48:00+00:00",
      "confidence": "medium",
      "evidence": [
        {
          "kind": "news",
          "label": "Investor's Business Daily",
          "source_type": "news",
          "publisher": "Investor's Business Daily"
        }
      ]
    },
    {
      "id": "news:https://www.barrons.com/articles/tesla-stock-robotaxi-elon-musk...",
      "kind": "general_news",
      "title": "Tesla's Robotaxi Timeline Is Back in Focus",
      "owners": [{ "owner_key": "elon-musk", "ticker": "TSLA" }],
      "occurred_at": "2026-04-27T12:10:00+00:00",
      "confidence": "medium",
      "evidence": [
        {
          "kind": "news",
          "label": "Barron's",
          "source_type": "news",
          "publisher": "Barron's"
        }
      ],
      "watch_next": "Ask AI to summarize what changed across the last five TSLA-linked signals."
    }
  ],
  "next_cursor": "MjAyNi0wNC0yN1QxMzo0ODowMCswMDowMHw..."
}
  • owners[].tickerTSLA is already joined to the owner, so market-routing does not need a second database.
  • kindOne ordered feed carries news, chatter, landings, co-locations, and key dates.
  • evidence[].publisherReuters / IBD / Barron's-style source labels are ready for dashboards and audit logs.
This is the core market workflow: watch a subject, pull the signal feed, map each signal to your Polymarket, Kalshi, or equity watchlist.
02

Community chatter markets

insider_chatter · source_type=reddit · confidence=high

Turn a pile of threads into a cited narrative shift.

Prediction markets move on narratives before they move on filings. Instead of one isolated post, Mountainhead returns a ranked list of cited chatter signals with confidence, owner mapping, and an analyst-friendly `watch_next`.

Request

curl "https://www.mountainhead.ai/api/v1/signals?kind=insider_chatter&limit=3" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

Response (real shape)

JSON200 OK
{
  "signals": [
    {
      "id": "reddit:https://www.reddit.com/r/politics/comments/1swnbyg/...",
      "kind": "insider_chatter",
      "title": "Trump Erupts in '60 Minutes' Interview",
      "thesis": "Curated community thread connected to Donald Trump in r/politics.",
      "owners": [
        {
          "owner_key": "donald-trump",
          "owner_name": "Donald Trump",
          "ticker": null,
          "market_label": null
        }
      ],
      "occurred_at": "2026-04-26T23:42:55+00:00",
      "score": 0.722,
      "confidence": "high",
      "severity": null,
      "evidence": [
        {
          "kind": "reddit",
          "label": "r/politics",
          "url": "https://www.reddit.com/r/politics/comments/1swnbyg/...",
          "occurred_at": "2026-04-26T23:42:55+00:00",
          "source_type": "reddit",
          "publisher": "r/politics"
        }
      ],
      "watch_next": "Skim the top comments before assuming the rumour is widely confirmed."
    },
    {
      "id": "reddit:https://www.reddit.com/r/teslainvestorsclub/comments/...",
      "kind": "insider_chatter",
      "title": "Tesla holders debate whether robotaxi timelines slipped again",
      "thesis": "Community narrative linked to Elon Musk and TSLA volatility.",
      "owners": [
        {
          "owner_key": "elon-musk",
          "owner_name": "Elon Musk",
          "ticker": "TSLA",
          "market_label": "Tesla"
        }
      ],
      "occurred_at": "2026-04-26T22:15:12+00:00",
      "score": 0.681,
      "confidence": "high",
      "severity": null,
      "evidence": [
        {
          "kind": "reddit",
          "label": "r/teslainvestorsclub",
          "source_type": "reddit",
          "publisher": "r/teslainvestorsclub"
        }
      ],
      "watch_next": "Ask AI to compare this thread against today's TSLA publisher coverage."
    },
    {
      "id": "reddit:https://www.reddit.com/r/artificial/comments/...",
      "kind": "insider_chatter",
      "title": "OpenAI lawsuit thread resurfaces questions about governance",
      "thesis": "AI community chatter connected to an active owner/legal catalyst.",
      "owners": [
        {
          "owner_key": "elon-musk",
          "owner_name": "Elon Musk",
          "ticker": "TSLA",
          "market_label": "Tesla"
        }
      ],
      "occurred_at": "2026-04-26T20:03:44+00:00",
      "score": 0.604,
      "confidence": "medium",
      "severity": null,
      "evidence": [
        {
          "kind": "reddit",
          "label": "r/artificial",
          "source_type": "reddit",
          "publisher": "r/artificial"
        }
      ],
      "watch_next": "Route only if it lines up with fresh publisher coverage or flight context."
    }
  ]
}
  • evidence[].source_typeClosed enum: news, reddit, flight_event, co_location, key_date. Build deterministic market-routing rules.
  • score + confidenceUse score for ranking and confidence for whether to alert a human, agent, or strategy.
  • watch_nextTells an analyst or agent what to check before assuming the narrative is confirmed.
For Polymarket/Kalshi politics markets, community chatter is a first-class input. The API keeps it cited and separable from flight evidence.
03

Public movement event feed

event_type · airport_icao · payload_public · no raw lat/lon

Last public location without leaking raw track data.

If you need the aviation primitive underneath a signal, use events. Public responses expose lifecycle state, owner key, timestamp, airport/location context when known, and curated payload fields. Raw lat/lon and full position tracks stay internal.

Request

curl "https://www.mountainhead.ai/api/v1/events?owner_key=elon-musk&limit=3" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

Response (real shape)

JSON200 OK
{
  "events": [
    {
      "id": "15",
      "owner_key": "elon-musk",
      "event_type": "landing",
      "severity": null,
      "score": null,
      "occurred_at": "2026-04-27T14:58:56.384+00:00",
      "airport_icao": "KSJC",
      "payload_public": {
        "airport": "San Jose Mineta International",
        "icao": "KSJC",
        "duration_minutes": 47
      }
    },
    {
      "id": "9",
      "owner_key": "elon-musk",
      "event_type": "squawk_change",
      "severity": null,
      "score": null,
      "occurred_at": "2026-04-23T05:29:40.400+00:00",
      "airport_icao": "KPAE",
      "payload_public": {
        "airport": "Paine Field",
        "icao": "KPAE"
      }
    },
    {
      "id": "8",
      "owner_key": "elon-musk",
      "event_type": "landing",
      "severity": null,
      "score": null,
      "occurred_at": "2026-04-23T05:29:40.400+00:00",
      "airport_icao": "KPAE",
      "payload_public": {
        "airport": "Paine Field",
        "icao": "KPAE",
        "duration_minutes": 91
      }
    }
  ],
  "next_cursor": "MjAyNi0wNC0yM1QwNToyOTo0MC40KzAwOjAwfDg",
  "limit": 3
}
  • event_typeAviation lifecycle events you can alert on without parsing ADS-B payloads.
  • airport_icaoLast public location is exposed as an airport/location label, not raw coordinates.
  • events/streamIntel customers can subscribe with SSE instead of polling.
This is the public movement layer. Most market users should start with /signals and drop to /events only when they need lifecycle detail.
04

Politician + executive-branch trading

STOCK Act PTRs · OGE 278 + 278-T · activity_type=transaction|holding

One feed for Congress AND the White House.

STOCK Act covers Congress only — the President, Vice President, and cabinet file OGE Form 278 (annual holdings) and Form 278-T (periodic transaction reports, ≤30 days after a reportable trade). `market/official-activity` unions both so one call answers 'what is the White House trading?' and 'what does Trump own?' Set `chamber=executive` for exec-only; pair with `activity_type=transaction` for buy/sell events or `activity_type=holding` for the annual Schedule A snapshot.

Request

# Real exec-branch transactions (RFK Jr 278-T, Vance VFIFX sale, Hegseth Bitcoin sale)
curl "https://www.mountainhead.ai/api/v1/market/official-activity?country=US&chamber=executive&activity_type=transaction&limit=10" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

# Trump's full disclosed portfolio (Schedule A holdings, ~3,400 rows)
curl "https://www.mountainhead.ai/api/v1/market/official-activity?member=Trump&chamber=executive&activity_type=holding&limit=25" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

# Single-call official dossier with both trades and holdings
curl "https://www.mountainhead.ai/api/v1/officials?slug=donald-trump" \
  -H "Authorization: Bearer $MOUNTAINHEAD_API_KEY"

Response (real shape)

JSON200 OK
{
  "activities": [
    {
      "country": "US",
      "chamber": "executive",
      "official_name": "Robert F. Kennedy Jr.",
      "official_slug": "robert-f-kennedy-jr",
      "party": "R",
      "activity_date": "2025-04-04",
      "disclosure_date": "2025-05-09",
      "activity_type": "transaction",
      "transaction_type": "sale",
      "symbol": "CRSP",
      "asset_name": "CRISPR Therapeutics AG Common Shares (CRSP)",
      "amount_min": 1001,
      "amount_max": 15000,
      "source_url": "https://extapps2.oge.gov/201/Presiden.nsf/.../Robert-F-Kennedy-Jr-05.09.2025-278T.pdf"
    },
    {
      "country": "US",
      "chamber": "executive",
      "official_name": "JD Vance",
      "activity_date": "2024-08-29",
      "activity_type": "transaction",
      "transaction_type": "sale",
      "symbol": null,
      "asset_name": "Vanguard Target Retirement 2050 Fund (VFIFX)",
      "amount_min": 100001,
      "amount_max": 250000
    },
    {
      "country": "US",
      "chamber": "executive",
      "official_name": "Donald Trump",
      "activity_date": "2025-12-31",
      "activity_type": "holding",
      "transaction_type": null,
      "symbol": "JPM",
      "asset_name": "JPMORGAN CHASE & CO COM",
      "amount_min": 500001,
      "amount_max": 1000000
    }
  ],
  "count": 25,
  "next_cursor": "MjAyNS0xMi0zMXxKUE0"
}
  • activity_type`transaction` = real buy/sell/exchange (STOCK Act PTRs + OGE 278-T). `holding` = Schedule A standing positions disclosed once a year on the annual 278.
  • chamber=executiveUnlocks Trump / Vance / Bessent / Rubio / Hegseth / Lutnick / RFK Jr. (and any cabinet member added to officials). STOCK Act doesn't cover them.
  • search_signals (kind=congress_trade)Cabinet 278-T trades on a tracked ticker surface here too — same shape as STOCK Act signals, slightly higher base score.
The President and VP don't file periodic transaction reports — for 'what does Trump own?' use activity_type=holding. For 'what did Cabinet member X just trade?' use activity_type=transaction.

Endpoints

The full surface.

Every endpoint returns JSON. List endpoints share the same cursor pagination shape.

  • GET
    /api/v1/me

    Verify a key. Returns plan, scopes, current rate-limit window, and month-to-date usage.

    any key
  • GET
    /api/v1/signals

    Primary product. Ranked, cited research signals filtered by owner, ticker, kind, severity, and time.

    read:signals
  • GET
    /api/v1/signals/{id}

    Fetch a single signal by stable id.

    read:signals
  • GET
    /api/v1/events

    Reverse-chronological feed of sanitized flight events. Coordinates are not exposed.

    read:events
  • GET
    /api/v1/events/stream

    Server-Sent Events feed of sanitized flight events. Intel plan only.

    stream:events
  • GET
    /api/v1/owners

    Public owner directory. Suppressed owners return as `{ owner_key, hidden: true }`.

    read:owners
  • GET
    /api/v1/news

    Normalized publisher feed. Closed `source_type` enum and free-text publisher label.

    read:news
  • GET
    /api/v1/market/snapshot

    Batched quote/price/delta/volume snapshot for up to 10 ticker symbols.

    read:market
  • GET
    /api/v1/market/company

    Company overview: fundamentals, recent earnings, SEC filings, news, and tracked owners.

    read:market
  • GET
    /api/v1/market/macro

    Curated FRED + OECD macro bundle: rates, inflation, labor, growth, money, housing, credit.

    read:market
  • GET
    /api/v1/market/filings

    List recent SEC EDGAR submissions for a ticker or CIK.

    read:filings
  • GET
    /api/v1/market/filing-content

    Fetch and return the plain-text content of an SEC filing document.

    read:filings
  • GET
    /api/v1/insider-chatter

    Pre-indexed insider sources for a tracked owner.

    read:news
  • GET
    /api/v1/market/insider-trades

    SEC Form 4 insider trading transactions by officers, directors, and 10%+ owners.

    read:filings
  • GET
    /api/v1/market/institutional

    13F-HR quarterly institutional holdings from major fund managers.

    read:filings
  • GET
    /api/v1/market/congress

    Congressional stock trading disclosures from House/Senate STOCK Act filings. For US executive branch (President / VP / cabinet — OGE Form 278/278-T) use `/api/v1/market/official-activity?country=US&chamber=executive`.

    read:filings
  • GET
    /api/v1/market/congress/summary

    Congressional trading leaderboard: most active traders, most-traded tickers, bipartisan convergence, disclosure lag.

    read:filings
  • GET
    /api/v1/officials

    Government official profiles with bio, committees, recent trades + holdings, and 90-day trading stats. Covers US Congress (STOCK Act), US executive branch (`chamber=executive` — Trump, Vance, Bessent, Rubio, Hegseth, Lutnick, RFK Jr. via OGE 278/278-T), UK Parliament, Canadian Commons, EU Parliament.

    read:filings
  • GET
    /api/v1/market/official-activity

    Unified disclosures across US (STOCK Act House/Senate + OGE Form 278 annual + OGE 278-T periodic transaction reports for executive branch), UK (registered interests), Canada (declarations), EU (MEP declarations). Use `chamber=executive` for White-House-only; `activity_type=holding` to see standing positions; `activity_type=transaction` to limit to real buy/sell events.

    read:filings
  • GET
    /api/v1/market/lobbying

    Lobbying disclosure filings. Registrant, client, amount, issue codes, lobbyists, government entities.

    read:filings
  • GET
    /api/v1/preferences

    User region preferences (GET to read, PUT to update). Controls default country filtering. Regions: US, GB, CA, EU.

    any key

Need request/response shapes and a live “Try it” UI? Open the interactive reference →

Pagination

Stable cursors. No skipped rows.

List endpoints return an opaque next_cursor in the body and a standard Link header. Cursors encode (timestamp, id) so duplicate timestamps never drop a row.

Loop until next_cursor is null. Default page size is 50, max 200.

let cursor: string | undefined;
do {
  const page = await client.public.listSignals({
    limit: 100,
    cursor,
  });
  for (const s of page.data) handle(s);
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Rate limits & errors

Per-key token buckets. Fail-closed on outages.

Free

30 req / min

0 included

Pro

120 req / min

1,000 included

Intel

600 req / min

10,000 included

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exhaust the bucket you get 429 with Retry-After.

Important: if our rate-limit infrastructure is unavailable we fail closed with 503 and Retry-After: 1. Well-behaved clients honor it; broken clients get throttled.

StatusCodeWhen
400invalid_requestBad query
401unauthorizedMissing or bad key
403forbidden_scopeKey lacks scope
404not_foundResource missing or hidden
429rate_limitedBucket empty
503rate_limit_unavailableLimiter offline

Compliance

Two enforcement points. Audit them yourself.

Delayed tails

Aircraft listed in the public delayed_tails registry are returned with the configured delay. Real-time access requires a separate licensing agreement.

Hidden owners

Owners flagged is_public=false are redacted to { owner_key, hidden: true }. Their signals and events are filtered out of every list endpoint.

Read the full compliance overview for takedown procedure and source attribution.

SDKs & MCP

Pick your tool.

TypeScript SDK

Generated from the live OpenAPI document. Same package name as the project so types track the v1 surface as it evolves.

npm install mountainhead

MCP for AI agents

Hosted Streamable HTTP MCP server at /api/mcp. Point Claude Code, Claude Desktop, Cursor, Gemini CLI, Antigravity, or any MCP client at one endpoint and get 22 tools. Most clients need no API key — OAuth 2.1 PKCE means they discover everything from the URL and you approve once in a browser.

Full MCP setup guide — every client, verified configs

Ready to build?

Mint a key in your account and start hitting /api/v1/me in a minute.

Get an API keyOpen reference

Need higher limits, custom contracts, or enterprise support? Talk to us.