# Equibles Documentation

---

# Overview

Equibles gives your tools structured financial data for US-listed companies — SEC filings, institutional holdings, insider & congressional trades, short data, fundamentals, and earnings-call intelligence. You can reach it two ways: a native **MCP server** for AI agents, or a plain **REST API**. Both are free to start.

## Two ways to connect

**[MCP server](/docs/mcp)** — connect Claude, Cursor, ChatGPT, or any MCP client and let your agent query live data in the conversation, with no glue code.

**[REST API](/docs/api)** — standard JSON over HTTPS at `api.equibles.com/v1`. Authenticate with an API key and page through the endpoints.

## Quickstart

1. **Create an API key.** Keys start with `eq_` and are shown once. See [Authentication](/docs/authentication).
2. **Call the REST API:**

   ```bash
   curl "https://api.equibles.com/v1/stocks/AAPL/prices" \
     -H "Authorization: Bearer eq_your_api_key"
   ```

3. **Or connect an AI agent over MCP:**

   ```json
   {
     "mcpServers": {
       "equibles": {
         "url": "https://mcp.equibles.com/mcp",
         "headers": { "Authorization": "Bearer eq_your_api_key" }
       }
     }
   }
   ```

   Per-client setup for Claude, Cursor, ChatGPT and more is under [Connect the MCP server](/docs/mcp).

## Explore

- [Authentication](/docs/authentication) — create keys, delivery methods, and OAuth.
- [Connect the MCP server](/docs/mcp) — get any MCP client running in minutes.
- [MCP tool reference](/docs/mcp/tools) — every tool your agent can call.
- [Tools in detail](/docs/mcp/tool-examples) — parameters, example prompts, and sample output for the flagship tools.
- [Recipes](/docs/recipes) — multi-tool workflows for common jobs.
- [REST API](/docs/api) — base URL, pagination, and the response envelope.
- [Endpoint reference](/docs/api/endpoints) — all REST endpoints, grouped.
- [Rate limits & errors](/docs/rate-limits) — daily limits, headers, and error codes.
- [Data coverage](/docs/data) — every dataset and where it comes from.
- [Changelog](/docs/changelog) — what's new, newest first.

## Built for AI agents

Every page here is available as clean Markdown for LLMs and coding assistants — open any page's **Open as Markdown** menu to copy it, or pull the whole set from [llms.txt](/docs/llms.txt) (a linked index) and [llms-full.txt](/docs/llms-full.txt) (the entire docs in one file).

> New here? The fastest path to a working call is [Quickstart](/docs/quickstart).

---

# Quickstart

Go from zero to a working request in a few minutes.

## 1. Create an API key

Sign in and open your [API keys](/dashboard/apikeys) in the dashboard. A key starts with `eq_` and is shown **once** — copy it somewhere safe. Claude web and ChatGPT can connect over OAuth with no key at all; see [Authentication](/docs/authentication).

## 2. Make your first REST call

Fetch Apple's recent daily prices:

```bash
curl "https://api.equibles.com/v1/stocks/AAPL/prices?limit=5" \
  -H "Authorization: Bearer eq_your_api_key"
```

You'll get a paginated JSON list:

```json
{
  "data": [
    { "date": "2026-07-07", "open": 228.14, "high": 230.02, "low": 227.31, "close": 229.87, "volume": 41028300 }
  ],
  "meta": { "limit": 5, "offset": 0, "count": 5, "hasMore": true }
}
```

## 3. Connect an AI agent over MCP

Point any MCP client at `https://mcp.equibles.com/mcp` and your assistant can query the same data in chat. For example, in Cursor add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "equibles": {
      "url": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" }
    }
  }
}
```

Then ask: *"Show me Apple's last five daily closes."* Step-by-step for every client is under [Connect the MCP server](/docs/mcp).

## Next steps

- [Authentication](/docs/authentication) — keys, headers, and OAuth.
- [Rate limits & errors](/docs/rate-limits) — how the shared daily limit works.
- [Endpoint reference](/docs/api/endpoints) — everything the REST API exposes.

---

# Authentication

Every request to the REST API and the MCP server is authenticated with an **API key**. Supported AI connectors can also sign in over **OAuth**, so there's no key to copy or store.

## API keys

Create keys in your [dashboard](/dashboard/apikeys). A key starts with the prefix `eq_` and is shown **once** at creation — copy it then and store it somewhere safe. We only keep a hash, so a lost key can't be recovered; create a new one and delete the old.

## Sending your key

Provide the key one of two ways. The `Authorization` header is preferred.

**Authorization header**

```bash
curl "https://api.equibles.com/v1/stocks/AAPL/prices" \
  -H "Authorization: Bearer eq_your_api_key"
```

**Query parameter** — useful where you can't set headers (for example an MCP client that only takes a URL):

```
https://api.equibles.com/v1/stocks/AAPL/prices?api_key=eq_your_api_key
```

> A key in the URL can end up in logs and browser history. Prefer the header, and treat any URL that contains a key as a secret.

## OAuth (MCP connectors)

Claude web, Claude Cowork, and ChatGPT can connect to the MCP server without an API key. Paste `https://mcp.equibles.com/mcp` into the client's connector settings and sign in to Equibles to approve access — the client holds a short-lived OAuth token instead of a key. Step-by-step for each client is under [Connect the MCP server](/docs/mcp).

## Keeping keys safe

- Use a separate key per integration so you can revoke one without affecting the others.
- Keep keys server-side. Never commit them to source control or ship them in client-side code.
- Rotate on a schedule, and immediately if a key may have leaked — delete it in the dashboard and create a new one.
- All requests must be over HTTPS.

---

# MCP vs REST — which to use

Equibles serves the same data two ways. Which you want depends on who's calling.

## Pick one

| | **MCP server** | **REST API** |
|---|---|---|
| Best for | AI agents & assistants (Claude, Cursor, ChatGPT) | Your own scripts, backends, dashboards |
| You write | nothing — the model calls tools in chat | HTTP requests + JSON parsing |
| Shape | tools the model picks by name | endpoints you call by URL |
| Auth | OAuth sign-in or API key | API key |
| Endpoint | `https://mcp.equibles.com/mcp` | `https://api.equibles.com/v1` |

**Reach for the MCP server** when a person or an agent is asking questions in natural language and you want the answers in the conversation — no glue code. It's the fastest path and how most people start. See [Connect the MCP server](/docs/mcp).

**Reach for the REST API** when you're writing code that needs the data on a schedule or inside your own product — a nightly job, a screener, a chart. Standard JSON over HTTPS. See [the REST API guide](/docs/api).

## They share one daily limit

Both surfaces draw on the **same daily request quota** for your account — an MCP tool call and a REST call each count once. Mixing them is fine; just budget against the single limit. See [Rate limits & errors](/docs/rate-limits).

## Using both

Nothing stops you from doing both — connect an agent over MCP for exploration, and call REST from a backend for the parts you've automated. Same data, same account, same key.

---

# Connect the MCP server

The Equibles MCP server lets an AI agent pull live financial data straight into the conversation. Point any MCP-capable client at the server URL and your assistant can search filings, read holdings, and analyse earnings calls with no glue code. Every tool is available on every plan.

```
https://mcp.equibles.com/mcp
```

## Choose your client

Each client connects a little differently. Pick yours for setup, verification, and troubleshooting tailored to it.

- [Claude Code](/docs/mcp/claude-code) — one-command install.
- [Claude Desktop](/docs/mcp/claude-desktop) — connectors, no API key.
- [Claude web](/docs/mcp/claude-web) — custom connector over OAuth.
- [Cursor](/docs/mcp/cursor) — `mcp.json` config.
- [VS Code](/docs/mcp/vscode) — Copilot MCP config.
- [ChatGPT](/docs/mcp/chatgpt) — developer-mode connector.
- [Windsurf](/docs/mcp/windsurf) — Cascade MCP config.
- [Gemini CLI](/docs/mcp/gemini-cli) — settings config.
- [Any MCP client](/docs/mcp/other) — the generic recipe.

## Authentication

Most modern clients can **sign in over OAuth** — no key to copy or store. Any client can also use an **API key**, sent as a `Bearer` header or an `?api_key=` query parameter on the URL. See [Authentication](/docs/authentication) for details.

## What your agent can do

Once connected, just ask in plain English — the model picks the right tool. A few to try, spanning what the server covers:

**Fundamentals & filings**

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> What did NVIDIA guide for next quarter's revenue? <span class="tag">Guidance</span></div>
  <div class="doc-prompt"><span class="q">›</span> Show Apple's gross margin trend over the last 8 quarters. <span class="tag">Financials</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize the risk factors in Tesla's latest 10-K. <span class="tag">Filings</span></div>
  <div class="doc-prompt"><span class="q">›</span> What KPIs did Netflix report last quarter? <span class="tag">KPIs</span></div>
</div>

**Ownership & flows**

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Which hedge funds bought the most NVIDIA last quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Has any member of Congress traded Palantir this year? <span class="tag">Congress</span></div>
  <div class="doc-prompt"><span class="q">›</span> Show recent insider selling at Microsoft. <span class="tag">Insider</span></div>
  <div class="doc-prompt"><span class="q">›</span> What's in Berkshire Hathaway's latest 13F? <span class="tag">13F</span></div>
</div>

**Markets & screening**

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Screen for profitable software stocks under a 20 P/E. <span class="tag">Screener</span></div>
  <div class="doc-prompt"><span class="q">›</span> Which stocks have the highest short-squeeze scores today? <span class="tag">Short interest</span></div>
  <div class="doc-prompt"><span class="q">›</span> Compare EV/EBITDA for AMD, NVIDIA, and Intel. <span class="tag">Valuation</span></div>
  <div class="doc-prompt"><span class="q">›</span> What's the latest CPI and unemployment rate? <span class="tag">Macro</span></div>
</div>

Browse every tool in the [tool reference](/docs/mcp/tools), or see [popular tools in detail](/docs/mcp/tool-examples) with their parameters and sample output. To string several together, follow a [recipe](/docs/recipes); to bake in our research conventions, add the [Claude Skill](/docs/mcp/claude-skill). Every call counts against your [daily limit](/docs/rate-limits).

## Troubleshooting

<details class="doc-ts"><summary>Your agent answered without calling Equibles?</summary>
<div class="doc-ts-body">

If the numbers look plausible but the assistant never shows a tool call, it's answering from its own training data instead of live data — the single most common issue. Tell it explicitly to **use the Equibles MCP server** (or name the data, e.g. "using Equibles, show…"). If it still won't, confirm the connector is enabled for the conversation on your [client's page](/docs/mcp).

</div>
</details>

<details class="doc-ts"><summary>Access denied or over your limit?</summary>
<div class="doc-ts-body">

Re-check your API key or OAuth sign-in on your [client's setup page](/docs/mcp). If you've used up today's calls, the server replies with a message explaining the limit — see [Rate limits](/docs/rate-limits) to raise it.

</div>
</details>

---

# Claude Code

Claude Code connects to the Equibles MCP server with one command — no config file to edit.

## 1. Install Claude Code

Install the CLI from [claude.com/claude-code](https://claude.com/claude-code), then run `claude` in any terminal.

## 2. Add the Equibles server

One command adds the server; you sign in over OAuth on first use — no key to manage:

```bash
claude mcp add --transport http equibles https://mcp.equibles.com/mcp
```

Run `/mcp` inside Claude Code and choose **Authenticate** to sign in, then confirm it registered with `claude mcp list`.

**Prefer an API key?** Create one at [/dashboard/apikeys](/dashboard/apikeys) (it starts with `eq_` and is shown once), then run:

```bash
claude mcp add-json equibles '{"type":"http","url":"https://mcp.equibles.com/mcp","headers":{"Authorization":"Bearer eq_your_api_key"}}' --scope user
```

> `--scope user` makes Equibles available in every project. Drop it to add the server to the current project only.

## 3. Test it

Start `claude` and ask any of these — the assistant should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

Run `claude mcp list` to confirm it registered, then start a fresh `claude` session — a running session won't pick up a newly added server.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Tell it explicitly to "use the Equibles MCP server" in your prompt.

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong. Re-copy it from [/dashboard/apikeys](/dashboard/apikeys) and re-run the `add-json` command. If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Claude Desktop

Claude Desktop connects to the Equibles MCP server as a custom connector — sign in over OAuth and there's no key to manage.

## 1. Install Claude Desktop

Download the desktop app from [claude.com/download](https://claude.com/download) and sign in.

## 2. Add the Equibles server

Add Equibles as a custom connector over OAuth:

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Paste the server URL:
   ```
   https://mcp.equibles.com/mcp
   ```
4. Click through to sign in to Equibles and **approve** access. Claude Desktop holds a short-lived OAuth token — no key to copy.

> **Prefer an API key?** Instead of signing in, paste a URL with your key from [/dashboard/apikeys](/dashboard/apikeys):
> ```
> https://mcp.equibles.com/mcp?api_key=eq_your_api_key
> ```

## 3. Test it

Open a new chat and ask any of these — Claude should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Connector not appearing?</summary>
<div class="doc-ts-body">

Fully quit and reopen Claude Desktop after adding it — a reload isn't enough.

</div>
</details>

<details class="doc-ts"><summary>Claude answers without Equibles data?</summary>
<div class="doc-ts-body">

Tell it explicitly to "use the Equibles MCP server" in your prompt.

</div>
</details>

<details class="doc-ts"><summary>Access denied?</summary>
<div class="doc-ts-body">

Re-approve the connector in **Settings → Connectors**, or if you're using a key, re-copy it from [/dashboard/apikeys](/dashboard/apikeys). If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Claude web

On claude.ai you add Equibles as a custom connector — sign in over OAuth and there's no key to manage.

## 1. Open Claude web

Sign in at [claude.ai](https://claude.ai). Custom connectors are available on paid plans.

## 2. Add the Equibles server

Add Equibles as a custom connector over OAuth:

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Paste the server URL:
   ```
   https://mcp.equibles.com/mcp
   ```
4. Click through to sign in to Equibles and **approve** access. Claude holds a short-lived OAuth token — no key to copy.

> **Prefer an API key?** Instead of signing in, paste a URL with your key from [/dashboard/apikeys](/dashboard/apikeys):
> ```
> https://mcp.equibles.com/mcp?api_key=eq_your_api_key
> ```

## 3. Test it

Enable the Equibles connector in a chat, then ask any of these:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Connector not appearing?</summary>
<div class="doc-ts-body">

Reload the page and confirm Equibles is toggled on for the conversation; re-add it under **Settings → Connectors** if it's missing.

</div>
</details>

<details class="doc-ts"><summary>Claude answers without Equibles data?</summary>
<div class="doc-ts-body">

Make sure the connector is enabled for the chat and tell it explicitly to "use the Equibles MCP server".

</div>
</details>

<details class="doc-ts"><summary>Access denied?</summary>
<div class="doc-ts-body">

Re-approve the connector in **Settings → Connectors**, or if you're using a key, re-copy it from [/dashboard/apikeys](/dashboard/apikeys). If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Cursor

Cursor connects to the Equibles MCP server through its `mcp.json` config, authenticated with an API key.

## 1. Install Cursor

Download the editor from [cursor.com](https://cursor.com) and sign in.

## 2. Add the Equibles server

One click installs the server and signs you in over OAuth — no key to manage:

<div class="doc-ctas">
  <a class="doc-cta primary" href="cursor://anysphere.cursor-deeplink/mcp/install?name=Equibles&amp;config=eyJ1cmwiOiJodHRwczovL21jcC5lcXVpYmxlcy5jb20vbWNwIn0=">Add to Cursor</a>
</div>

**Prefer an API key?** Create one at [/dashboard/apikeys](/dashboard/apikeys) (it starts with `eq_` and is shown once), then add Equibles to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "equibles": {
      "url": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" }
    }
  }
}
```

> For a single project instead of every project, put the same JSON in `.cursor/mcp.json` at the project root. You can also add the server from **Settings → MCP → Add new MCP server**.

## 3. Test it

Open Cursor's chat (Agent mode) and ask any of these — it should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

Fully restart Cursor after editing `mcp.json`, then check **Settings → MCP** shows Equibles enabled with a green dot.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Use Agent mode and tell it explicitly to "use the Equibles MCP server".

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong — re-copy it from [/dashboard/apikeys](/dashboard/apikeys) into the `Authorization` header. If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# VS Code

VS Code connects to the Equibles MCP server from Copilot agent mode, configured in an `mcp.json` file.

## 1. Install VS Code

Install [VS Code](https://code.visualstudio.com) with GitHub Copilot, and switch Copilot Chat to **Agent** mode.

## 2. Add the Equibles server

One command adds the server; Copilot signs you in over OAuth on first use — no key to manage:

```bash
code --add-mcp '{"name":"equibles","type":"http","url":"https://mcp.equibles.com/mcp"}'
```

**Prefer an API key?** Create one at [/dashboard/apikeys](/dashboard/apikeys) (it starts with `eq_` and is shown once), then add Equibles to `.vscode/mcp.json` in your workspace (or your user `mcp.json`):

```json
{
  "servers": {
    "equibles": {
      "type": "http",
      "url": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" }
    }
  }
}
```

> Prefer not to store the key in the file? Run **MCP: Add Server** from the Command Palette and use an `${input:...}` variable — VS Code prompts for the key and stores it securely.

## 3. Test it

Open Copilot Chat in **Agent** mode and ask any of these — it should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

After editing `mcp.json`, click **Start** on the server (or reload the window) — check the MCP servers list in the Command Palette shows Equibles running.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Make sure Copilot is in Agent mode and tell it explicitly to "use the Equibles MCP server".

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong — re-copy it from [/dashboard/apikeys](/dashboard/apikeys) into the `Authorization` header. If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# ChatGPT

ChatGPT connects to the Equibles MCP server as a custom connector — sign in over OAuth and there's no key to manage.

## 1. Open ChatGPT

Sign in at [chatgpt.com](https://chatgpt.com). Custom connectors require a paid plan with developer mode / connectors enabled in **Settings**.

## 2. Add the Equibles server

Add Equibles as a custom connector over OAuth:

1. Open **Settings → Connectors** (enable developer mode if prompted).
2. Click **Create** / **Add custom connector**.
3. Paste the server URL:
   ```
   https://mcp.equibles.com/mcp
   ```
4. Click through to sign in to Equibles and **approve** access. ChatGPT holds a short-lived OAuth token — no key to copy.

> **Prefer an API key?** Instead of signing in, paste a URL with your key from [/dashboard/apikeys](/dashboard/apikeys):
> ```
> https://mcp.equibles.com/mcp?api_key=eq_your_api_key
> ```

## 3. Test it

Enable the Equibles connector for a chat, then ask any of these:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Connector not appearing?</summary>
<div class="doc-ts-body">

Reload ChatGPT and confirm the connector is toggled on for the conversation; re-add it under **Settings → Connectors** if it's missing.

</div>
</details>

<details class="doc-ts"><summary>ChatGPT answers without Equibles data?</summary>
<div class="doc-ts-body">

Make sure the connector is enabled for the chat and tell it explicitly to "use the Equibles MCP server".

</div>
</details>

<details class="doc-ts"><summary>Access denied?</summary>
<div class="doc-ts-body">

Re-approve the connector in **Settings → Connectors**, or if you're using a key, re-copy it from [/dashboard/apikeys](/dashboard/apikeys). If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Windsurf

Windsurf connects to the Equibles MCP server from Cascade, configured in `mcp_config.json`.

## 1. Install Windsurf

Download [Windsurf](https://windsurf.com) and open the Cascade panel.

## 2. Add the Equibles server

Create an API key at [/dashboard/apikeys](/dashboard/apikeys) (it starts with `eq_` and is shown once), then add Equibles to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "equibles": {
      "serverUrl": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" }
    }
  }
}
```

> Windsurf is the odd one out — remote servers use the `serverUrl` key, not `url`. Open the file via Cascade's **Plugins → View raw config** if you'd rather not edit it by hand.

## 3. Test it

In the Cascade panel, ask any of these — it should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

After editing `mcp_config.json`, click **Refresh** in Cascade's MCP list (or fully restart Windsurf), and confirm Equibles is enabled.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Tell it explicitly to "use the Equibles MCP server" in your prompt.

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong — re-copy it from [/dashboard/apikeys](/dashboard/apikeys) into the `Authorization` header. If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Gemini CLI

The Gemini CLI connects to the Equibles MCP server through its `settings.json`, authenticated with an API key.

## 1. Install the Gemini CLI

Install it from [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli), then run `gemini` once to sign in.

## 2. Add the Equibles server

Create an API key at [/dashboard/apikeys](/dashboard/apikeys) (it starts with `eq_` and is shown once), then add Equibles to `~/.gemini/settings.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "equibles": {
      "httpUrl": "https://mcp.equibles.com/mcp",
      "headers": { "Authorization": "Bearer eq_your_api_key" }
    }
  }
}
```

> A streamable-HTTP server uses the `httpUrl` key (not `url`, which is for SSE endpoints). For a single project, put the same block in `.gemini/settings.json` at the project root.

## 3. Test it

Start `gemini` and ask any of these — it should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

Restart the CLI after editing `settings.json`, then run `/mcp` inside `gemini` to confirm Equibles is listed and connected.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Tell it explicitly to "use the Equibles MCP server" in your prompt.

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong — re-copy it from [/dashboard/apikeys](/dashboard/apikeys) into the `Authorization` header. If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Any MCP client

Any MCP-capable client can reach the Equibles server over Streamable HTTP with an API key — here's the generic recipe.

## 1. Install your MCP client

Use any client that supports remote (Streamable HTTP) MCP servers. Check its own MCP setup docs for where server config lives.

## 2. Add the Equibles server

Point the client at the Equibles server with these three values:

```
Transport:  Streamable HTTP
URL:        https://mcp.equibles.com/mcp
Header:     Authorization: Bearer eq_your_api_key
```

Create the key at [/dashboard/apikeys](/dashboard/apikeys) — it starts with `eq_` and is shown once.

> **Can't set a header?** Put the key in the URL instead: `https://mcp.equibles.com/mcp?api_key=eq_your_api_key`. Treat any URL containing a key as a secret.

## 3. Test it

Once connected, ask your assistant any of these — it should call an Equibles tool:

<div class="doc-prompts">
  <div class="doc-prompt"><span class="q">›</span> Show me Apple's last five daily closes. <span class="tag">Prices</span></div>
  <div class="doc-prompt"><span class="q">›</span> Who are NVIDIA's top institutional holders this quarter? <span class="tag">13F</span></div>
  <div class="doc-prompt"><span class="q">›</span> Summarize Microsoft's most recent earnings call. <span class="tag">Earnings</span></div>
</div>

## Troubleshooting

<details class="doc-ts"><summary>Server not appearing?</summary>
<div class="doc-ts-body">

Fully restart the client after editing its config, and confirm it lists Equibles as connected.

</div>
</details>

<details class="doc-ts"><summary>Model answers without Equibles data?</summary>
<div class="doc-ts-body">

Tell it explicitly to "use the Equibles MCP server" in your prompt.

</div>
</details>

<details class="doc-ts"><summary>401 / access denied?</summary>
<div class="doc-ts-body">

Your key is missing or wrong — re-copy it from [/dashboard/apikeys](/dashboard/apikeys) into the `Authorization` header (or the `api_key` query parameter). If you're over your daily limit, see [Rate limits](/docs/rate-limits).

</div>
</details>

---

# Tool reference

Once you've [connected a client](/docs/mcp), your agent can call any of these tools by name — you don't invoke them yourself, the model picks the right tool for the question. Each returns structured, sourced data, and every call counts against your [daily limit](/docs/rate-limits). The same data is available over the [REST API](/docs/api/endpoints).

The tools are grouped into eleven families — **filings & documents**, **fundamentals & valuation**, **earnings calls & IR**, **institutional (13F) holdings**, **funds & advisers**, **insider trading**, **congressional trading**, **short selling**, **capital, executives & screening**, **prices & technicals**, and **economic, futures & sentiment**. Use the *On this page* menu to jump to one.

Want to see what a tool takes and returns? [Popular tools in detail](/docs/mcp/tool-examples) shows the parameters, an example prompt, and a real sample of the output for the ten most-used ones. To chain several into a workflow, see the [recipes](/docs/recipes).

## Filings & documents

| Tool | Description |
|---|---|
| `SearchDocuments` | Semantic search across the full SEC filing and transcript corpus. |
| `SearchCompanyDocuments` | Semantic search scoped to one company's filings and transcripts. |
| `SearchDocument` | Semantic search within a single document. |
| `SearchDocumentKeyword` | Exact keyword search within a single document. |
| `ListCompanyDocuments` | List a company's filings and transcripts, newest first. |
| `ReadDocumentLines` | Read numbered text lines from a filing or transcript. |
| `GetFailsToDeliver` | SEC fails-to-deliver records for a stock. |
| `GetExemptOfferings` | Reg D private placements (Form D) for a company. |

## Fundamentals & valuation

| Tool | Description |
|---|---|
| `GetFinancialFact` | A single XBRL financial concept over time. |
| `CompareFinancialFact` | Compare one financial concept across multiple companies. |
| `GetFinancialStatement` | A full income, balance sheet, or cash-flow statement. |
| `GetRevenueBreakdown` | Revenue disaggregated by segment, product, or geography. |
| `GetCompanyKpis` | Company-reported KPIs extracted from filings. |
| `GetNonGaapBridge` | The GAAP-to-non-GAAP reconciliation bridge. |
| `GetGuidance` | Forward guidance ranges issued by management. |
| `GetValuationMultiples` | Current valuation multiples (P/E, EV/EBITDA, and more). |
| `GetValuationMultiplesHistory` | Historical valuation multiples over time. |
| `GetCustomerConcentration` | Major-customer concentration disclosed in filings. |
| `GetGoingConcernStatus` | Going-concern warnings flagged by auditors. |

## Earnings calls & investor relations

| Tool | Description |
|---|---|
| `GetEarningsBrief` | A concise, sourced brief of an earnings call. |
| `GetCallInsights` | Key insights and themes extracted from a call. |
| `GetEarningsCallEvent` | Details of a specific earnings-call event. |
| `GetEarningsCallSpeakers` | Speakers and their attributed remarks on a call. |
| `ListInvestorEvents` | Upcoming and past investor events for a company. |
| `GetInvestorEventSpeakers` | Speakers scheduled for an investor event. |
| `GetInvestorRelationsNews` | Company press releases and IR news. |
| `GetInvestorRelationsEvents` | Company-published investor-relations events. |

## Institutional holdings (13F)

| Tool | Description |
|---|---|
| `GetTopHolders` | Top institutional holders of a stock, by shares. |
| `GetOwnershipHistory` | Institutional ownership of a stock across quarters. |
| `GetTopBuyersSellers` | Largest 13F buyers and sellers vs the prior quarter. |
| `GetInstitutionPortfolio` | An institution's reported 13F portfolio. |
| `GetInstitutionSummary` | Portfolio summary — AUM, concentration, turnover. |
| `GetInstitutionSectorAllocation` | An institution's allocation by sector. |
| `GetInstitutionQuarterlyActivity` | An institution's quarter-over-quarter position changes. |
| `SearchInstitutions` | Find a 13F filer by name. |
| `GetMarketWide13FActivity` | Market-wide 13F leaderboards (top buys, new positions, exits). |
| `GetMostHeldStocks` | Stocks ranked by 13F ownership breadth. |
| `GetSuperInvestors` | Portfolios of tracked super-investors. |

## Funds & advisers

| Tool | Description |
|---|---|
| `SearchFunds` | Search the registered fund / ETF directory. |
| `GetFundProfile` | A fund's profile and identifiers. |
| `GetFundHoldings` | A fund's holdings from its latest NPORT-P. |
| `GetFundOperations` | Fund N-CEN operational data and service providers. |
| `GetFundsHoldingStock` | Funds and ETFs that hold a given stock. |
| `GetFundOverlap` | Holdings overlap between two funds. |
| `GetConsensusHoldings` | Consensus positions across a set of funds. |
| `GetFundCloneBacktest` | Backtest a strategy that clones a fund's disclosed holdings. |
| `SearchInvestmentAdvisers` | Search SEC-registered investment advisers (Form ADV). |
| `GetInvestmentAdviser` | A full Form ADV adviser profile. |

## Insider trading

| Tool | Description |
|---|---|
| `GetInsiderTransactions` | Insider transactions (Form 3/4) for a stock. |
| `GetInsiderOwnership` | Current insider ownership of a stock. |
| `GetProposedSales` | Proposed insider sales (Form 144). |
| `GetInsiderSentimentScores` | Composite insider-sentiment scores. |
| `SearchInsiders` | Find a corporate insider by name. |

## Congressional trading

| Tool | Description |
|---|---|
| `GetCongressionalTrades` | Congressional stock trades for a ticker. |
| `GetMemberTrades` | A member of Congress's disclosed trades. |
| `GetMemberNetWorth` | A member's net-worth history (bands). |
| `GetMarketWideCongressionalActivity` | Market-wide congressional trading aggregates. |
| `SearchCongressMembers` | Find a member of Congress by name. |

## Short selling

| Tool | Description |
|---|---|
| `GetShortVolume` | Daily FINRA short volume for a stock. |
| `GetShortInterest` | Bi-monthly FINRA short interest for a stock. |
| `GetOffExchangeVolume` | Weekly off-exchange (dark-pool / OTC) volume. |
| `GetShortInterestSnapshot` | Market-wide short-interest snapshot. |
| `GetLargestShortVolume` | Stocks with the largest daily short volume. |
| `GetShortSqueezeScores` | Highest composite short-squeeze scores (0–100). |

## Capital, executives & screening

| Tool | Description |
|---|---|
| `GetBuybackPrograms` | Announced share-repurchase programs and progress. |
| `GetAtmPrograms` | At-the-market (ATM) equity programs. |
| `GetExecutiveChanges` | Executive and director appointments and departures. |
| `GetExecutiveCompensation` | Executive compensation disclosed in filings. |
| `ScreenStocks` | Screen US stocks with natural-language or structured filters. |
| `GetGovernmentContracts` | Federal contract awards won by a company. |
| `GetTopGovernmentContractors` | Companies ranked by total federal contract dollars. |
| `GetFdaCatalysts` | Scheduled FDA advisory-committee meetings, soonest first. |

## Prices & technicals

| Tool | Description |
|---|---|
| `GetStockPrices` | Daily OHLCV price history. |
| `GetLatestPrices` | Latest close and volume for up to 25 stocks. |
| `GetBollingerBands` | Bollinger Bands computed from OHLCV. |
| `GetStochasticOscillator` | Stochastic oscillator computed from OHLCV. |
| `GetAverageTrueRange` | Average True Range (ATR) computed from OHLCV. |
| `GetOnBalanceVolume` | On-Balance Volume (OBV) computed from OHLCV. |

## Economic, futures & sentiment

| Tool | Description |
|---|---|
| `GetEconomicIndicator` | Historical observations for a FRED series. |
| `GetLatestEconomicData` | Latest value for every tracked FRED series. |
| `SearchEconomicIndicators` | Search FRED economic series. |
| `GetEconomicCalendar` | Economic release calendar with importance tiers. |
| `GetCftcPositioning` | Weekly Commitments of Traders (COT) positioning for a contract. |
| `GetLatestCftcData` | Latest COT snapshot across tracked contracts. |
| `SearchCftcMarkets` | Search CFTC futures markets. |
| `GetPutCallRatios` | CBOE put/call ratio history. |
| `GetVixHistory` | CBOE VIX daily OHLC (from 1990). |

---

# Tools in detail

The [tool reference](/docs/mcp/tools) lists every tool. This page shows ten of the most-used ones in detail — the parameters they take, a question that triggers them, and a **real, trimmed sample** of what they return, so you can see the shape of the data before you wire anything up. You never call these by hand; the model picks the tool from your question.

## ScreenStocks

Screen the whole US universe by combining range filters across datasets — market cap, price, 13F filer count and its quarter-over-quarter change, short interest %, days to cover, the composite squeeze and insider-sentiment scores, net insider buying, and the going-concern flag. Every bound is optional.

**Key parameters:** `minMarketCap` / `maxMarketCap`, `minSqueezeScore`, `minShortInterestPercent`, `minInsiderSentiment`, `minNetInsiderBuy`, `hasGoingConcernDoubt`, `sortBy`, `maxResults` (and more — every axis has a min/max).

**Ask:** *"Screen for $1B+ stocks with a squeeze score above 75."*

**Returns:**

```
# Stock screener — 310 match(es), showing 3

| Ticker | Company            | Market Cap | SI %   | Days to Cover | Squeeze | Net Insider Buy (90d) |
|--------|--------------------|-----------:|-------:|--------------:|--------:|----------------------:|
| SNOW   | Snowflake Inc.     |     $90.6B |  6.65% |          2.94 |      76 |            -$470.3M   |
| NBIS   | Nebius Group N.V.  |     $55.8B | 27.68% |          3.46 |      85 |            -$142.2M   |
| FITB   | Fifth Third Bancorp|     $51.7B |  5.75% |          6.52 |      86 |              -$1.3M   |
```

## GetValuationMultiples

Trailing-twelve-month EV/Revenue, EV/EBIT and P/E, each shown against the industry median and quartiles so the multiple reads in context. Inputs are tagged at the same balance-sheet date; a company missing an input is excluded from that ratio, never estimated. REITs also get P/FFO and P/AFFO from their own SEC reconciliation.

**Parameters:** `ticker` (required).

**Ask:** *"How expensive is Apple versus its industry?"*

**Returns:**

```
# Valuation multiples — AAPL (Apple Inc.)
- Industry: Consumer Electronics · Market cap: $4.63T · Enterprise value: $4.67T
- TTM revenue: $451.4B · TTM EBIT: $147.4B · TTM diluted EPS: $8.26

| Ratio       | Company | Industry median | Industry quartiles |
|-------------|--------:|----------------:|--------------------|
| EV/Revenue  |  10.34× |           0.70× | 0.39× – 3.33×      |
| EV/EBIT     |  31.68× |               — | —                  |
| P/E (TTM)   |  38.17× |          65.46× | 47.32× – 220.92×   |
```

## GetFinancialStatement

An income statement, balance sheet, or cash-flow statement for one fiscal year and period, from SEC Company Facts (structured XBRL), with the latest-restated value for each line.

**Parameters:** `ticker` (required), `statement` (`income` / `balance` / `cashflow`), `year`, `period` (`FY` / `Q1`–`Q4`).

**Ask:** *"Show Apple's latest annual income statement."*

**Returns** (trimmed):

```
Income Statement — AAPL (Apple Inc.) — FY2025

| Line Item        |            Value | Period End | Form | Filed      |
|------------------|-----------------:|------------|------|------------|
| Revenue          | $416,161,000,000 | 2025-09-27 | 10-K | 2025-10-31 |
| Gross Profit     | $195,201,000,000 | 2025-09-27 | 10-K | 2025-10-31 |
| Operating Income | $133,050,000,000 | 2025-09-27 | 10-K | 2025-10-31 |
| Net Income       | $112,010,000,000 | 2025-09-27 | 10-K | 2025-10-31 |
| EPS (Diluted)    |            $7.46 | 2025-09-27 | 10-K | 2025-10-31 |
```

## GetGuidance

Management's forward outlook, extracted from Item-2.02 8-K earnings releases and call transcripts — each guided metric with its range, basis (GAAP/non-GAAP), period, and provenance, newest release first. Revenue and EPS guidance also carry the reported actual and an above/within/below verdict once the facts land.

**Parameters:** `ticker` (required).

**Ask:** *"What is Delta guiding for this year?"*

**Returns:**

```
# Earnings guidance — DAL (Delta Air Lines, Inc.)

| Filed      | Metric             | Period    | Guided        | Change    | Basis    |
|------------|--------------------|-----------|---------------|-----------|----------|
| 2026-07-10 | Earnings Per Share | FY 2026   | $6.50 – $7.50 | Initiated | —        |
| 2026-07-10 | Free Cash Flow     | FY 2026   | $3B – $4B     | Initiated | Non-GAAP |
| 2026-03-31 | operating margin   | June qtr  | 6% – 8%       | Initiated | —        |
```

## GetEarningsBrief

A verifier-approved read of a company's recent earnings calls — a TL;DR, the bullish and bearish points, and verbatim pull-quotes with speaker and role, newest quarter first. The same brief the Equibles stock page shows.

**Parameters:** `ticker` (required), `limit` (quarters, default 2).

**Ask:** *"Summarize NVIDIA's latest earnings call."*

**Returns** (trimmed):

```
# NVDA — earnings brief · FY2027 Q1 (call 2026-05-20)

NVIDIA reported record Q1 revenue of $81.6B, up 85% YoY, with Data Center
revenue of $75.2B up 92% YoY, and announced an $80B buyback authorization.

Bullish
- Revenue $81.6B, up 85% YoY and 20% sequentially (14th straight up quarter)
- Data Center $75.2B, up 92% YoY; networking $14.8B up 199% YoY
Bearish
- GAAP gross margin slipped 0.1 pt sequentially to 74.9%

From the call
> ...full confidence in the $1 trillion in Blackwell and Reuben revenue we
> foresee from 2025 through calendar 2027. — Colette Kress, CFO
```

## GetTopHolders

The largest institutional holders of a stock from SEC 13F-HR filings, ranked by shares, with value and share of total institutional ownership. While a quarter's filing window is open, funds that haven't filed yet carry their prior-quarter positions.

**Parameters:** `ticker` (required), `reportDate`, `maxResults` (default 20).

**Ask:** *"Who are NVIDIA's biggest institutional holders?"*

**Returns** (trimmed):

```
Top institutional holders of Nvidia Corp (NVDA) as of 2026-06-30:
Showing 3 of 5856 institutions.

| # | Institution                      |        Shares | Value ($M) | % of Total |
|---|----------------------------------|--------------:|-----------:|-----------:|
| 1 | BlackRock, Inc.                  | 1,925,533,174 |  335,813.0 |     11.62% |
| 2 | VANGUARD CAPITAL MANAGEMENT LLC   | 1,538,550,382 |  268,323.2 |      9.29% |
| 3 | STATE STREET CORP                | 993,885,601   |  173,333.6 |      6.00% |
```

## GetInsiderTransactions

Recent insider purchases, sales, and awards from SEC Form 3/4 filings — insider name, role, transaction type, shares, price, and post-transaction holdings.

**Parameters:** `ticker` (required), `maxResults` (default 50).

**Ask:** *"Any insider selling at Microsoft lately?"*

**Returns:**

```
Recent insider transactions for Microsoft Corp (MSFT):

| Date       | Insider        | Role                     | Type  | Shares | Price   | Owned After |
|------------|----------------|--------------------------|-------|-------:|--------:|------------:|
| 2026-06-15 | Coleman Amy    | EVP, Chief HR Officer    | Sell  |     35 | $390.74 |      45,444 |
| 2026-06-15 | Jolla Alice L. | Chief Accounting Officer | Award |  5,004 |   $0.00 |      76,152 |
| 2026-06-11 | Hoffman Reid   | Director                 | Award |     39 |   $0.00 |      16,963 |
```

## GetCongressionalTrades

Stock trades by members of Congress for a ticker — who traded, position, buy/sell, the disclosed amount range, and owner.

**Parameters:** `ticker` (required), `transactionType` (`Purchase` / `Sale`), `startDate`, `endDate`, `maxResults` (default 50).

**Ask:** *"Has anyone in Congress traded NVIDIA this year?"*

**Returns:**

```
Congressional trades for NVDA (Nvidia Corp):

| Date       | Member             | Position       | Type | Amount Range        | Owner |
|------------|--------------------|----------------|------|---------------------|-------|
| 2026-06-30 | Sheldon Whitehouse | Senator        | Sale | $15,001–$50,000     | Self  |
| 2026-06-16 | Matthew Van Epps   | Representative | Sale | $1,001–$15,000      | —     |
| 2026-05-08 | Sheldon Whitehouse | Senator        | Sale | $100,001–$250,000   | Self  |
```

## GetShortSqueezeScores

The stocks with the highest composite short-squeeze score — a peer-relative 0–100 rank from short interest % of shares, days to cover, and the recent change in short share of volume, plus catalyst boosts. Pass `minMarketCap` / `minDollarVolume` to clear out untradeable micro-caps.

**Parameters:** `minMarketCap`, `minDollarVolume`, `maxResults` (default 25).

**Ask:** *"Highest short-squeeze scores among $1B+ stocks?"*

**Returns** (trimmed):

```
# Highest short-squeeze scores — settlement 2026-06-30

| # | Ticker | Score | Short % | Days to Cover | Δ Short Int | Catalysts             | Market Cap |
|---|--------|------:|--------:|--------------:|------------:|-----------------------|-----------:|
| 1 | TRAX   |    97 |  11.2 % |           4.8 |      +33.2% | PriceSpike+VolumeSurge|     $1.26B |
| 2 | CRNX   |    96 |  13.1 % |           9.2 |       +7.7% | PriceSpike+VolumeSurge|     $8.81B |
| 3 | XENE   |    95 |   6.5 % |           3.0 |      +42.0% | PriceSpike+VolumeSurge|     $6.66B |
```

## GetBuybackPrograms

A company's share-repurchase picture — tracked programs (authorized total, remaining, expiry), the latest authorization, and repurchase history (cash spent, shares, average price) by fiscal year and recent quarter. From XBRL facts plus verified extractions; nothing estimated.

**Parameters:** `ticker` (required).

**Ask:** *"How much stock has Apple been buying back?"*

**Returns** (trimmed):

```
# Share repurchases — AAPL (Apple Inc.)

Latest authorization: $315,000,000,000 (as of 2021-12-25)

| Fiscal year ended | Cash spent      | Shares      | Source              |
|-------------------|----------------:|------------:|---------------------|
| 2025-09-27        | $90,711,000,000 | 402,000,000 | 10-K, filed 2025-10-31 |
| 2024-09-28        | $94,949,000,000 | 499,000,000 | 10-K, filed 2025-10-31 |
| 2023-09-30        | $77,550,000,000 | 471,000,000 | 10-K, filed 2025-10-31 |
```

---

Want the same shape over plain HTTP for your own code? Every tool has a REST twin — see the [endpoint reference](/docs/api/endpoints). Ready to string several together? See the [recipes](/docs/recipes).

---

# Write a Claude Skill

A [Claude Skill](https://claude.com/claude-code) is a short `SKILL.md` that Claude loads to learn how *you* want a job done. Pair one with the Equibles MCP server and your agent stops answering market questions from memory and starts pulling — and citing — the real numbers, with the right conventions baked in.

## The Equibles Skill

Save this as `.claude/skills/equibles-research/SKILL.md` in your project (Claude Code), or add it as a Skill in Claude Desktop / claude.ai:

```markdown
---
name: equibles-research
description: Use for any question about US-listed companies — prices, SEC filings,
  fundamentals, holdings, insider & congressional trades, short data, earnings calls.
  Always pull the numbers from the Equibles tools, never from memory.
---

# Equibles research

## When to use
- Any question that needs a real number, filing, holding, or transcript for a US-listed company.
- Never answer market data from memory — call an Equibles tool. If a tool returns
  nothing, say so; don't fill the gap with a guess.

## Conventions
- **Cite the source.** Equibles returns the form, filing date, and period for each
  figure — pass those through so every number is traceable.
- **Fiscal periods.** State the fiscal year and period (FY or Q1–Q4). Trailing-
  twelve-month (TTM) figures sum the four most recent discrete quarters.
- **Valuation.** Read a multiple against the industry median/quartiles the tool
  returns, not in isolation. For REITs, use P/FFO and P/AFFO — not P/E.
- **Guidance.** Note the basis (GAAP vs non-GAAP), and never compare non-GAAP
  guidance against a GAAP actual.
- **Prices** are split-adjusted daily closes.
- **13F holdings.** A quarter's filing window stays open 45 days after quarter-end;
  funds that haven't filed yet carry their prior-quarter positions.

## Getting the tools
Connect the Equibles MCP server — see https://equibles.com/docs/mcp .
```

## Why it helps

The Skill fixes the two things that go wrong most often when an AI touches financial data:

- **It answers from training data instead of the tools.** The "never from memory" rule, plus the connected server, keeps answers grounded in live filings.
- **It gets a convention subtly wrong** — comparing non-GAAP guidance to a GAAP actual, valuing a REIT on P/E, or mixing fiscal periods. The conventions above encode the right call once, so you don't restate them every prompt.

Adapt it freely — add your own coverage rules, preferred peer sets, or output format. The Skill is yours; the tools and their sourcing come from Equibles.

---

# REST API

The REST API serves the same data as the MCP server as plain JSON over HTTPS — ideal for scripts, backends, and dashboards. Every endpoint lives under `https://api.equibles.com/v1`.

## Base URL & authentication

All requests go to `https://api.equibles.com/v1` and must include your API key as a `Bearer` token (or an `?api_key=` query parameter — see [Authentication](/docs/authentication)).

```bash
curl "https://api.equibles.com/v1/stocks/AAPL/prices?startDate=2024-01-01" \
  -H "Authorization: Bearer eq_your_api_key"
```

## Pagination

List endpoints accept `limit` and `offset` query parameters and wrap the rows in a `data` array alongside a `meta` object. Use `meta.hasMore` to decide whether to fetch the next page (increase `offset` by `limit`). The maximum `limit` is 500.

```json
{
  "data": [ /* rows */ ],
  "meta": { "limit": 50, "offset": 0, "count": 50, "hasMore": true }
}
```

## Response format

- All responses are JSON with **camelCase** field names.
- Dates are ISO `yyyy-MM-dd` strings.
- Successful reads return `200`; see [Rate limits & errors](/docs/rate-limits) for non-2xx.
- `v1` is stable — breaking changes ship under a future version, never inside `v1`.

## Errors & rate limits

Non-2xx responses return a consistent error envelope, and requests count against a shared daily limit across REST and MCP. Full details are on [Rate limits & errors](/docs/rate-limits).

```json
{ "error": { "code": "not_found", "message": "Stock not found.", "status": 404 } }
```

## Reference

- [Endpoint reference](/docs/api/endpoints) — all endpoints, grouped by domain.
- [Interactive docs](https://api.equibles.com/docs) — try endpoints live in Swagger UI.
- [OpenAPI spec](https://api.equibles.com/openapi/v1.json) — generate a client from `v1.json`.

---

# Endpoint reference

All endpoints are `GET` requests under `https://api.equibles.com`. Prefer to try them live? The [interactive Swagger docs](https://api.equibles.com/docs) document every parameter and response. See the [API guide](/docs/api) for auth and pagination.

## Prices

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/prices` | Daily OHLCV price history. |
| `/v1/prices/latest` | Latest close and volume for up to 25 tickers. |

## Filings & documents

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/filings` | SEC filings and earnings transcripts for a stock. |
| `/v1/filings/{documentId}/lines` | Numbered text lines from one filing or transcript. |
| `/v1/filings/{documentId}/keyword-search` | Exact keyword search within one filing. |
| `/v1/stocks/{ticker}/fails-to-deliver` | SEC fails-to-deliver records. |
| `/v1/stocks/{ticker}/exempt-offerings` | Reg D private placements (Form D). |

## Institutional holdings (13F)

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/institutional-holders` | Top 13F holders ranked by shares. |
| `/v1/stocks/{ticker}/institutional-ownership` | Institutional ownership across quarters. |
| `/v1/stocks/{ticker}/institutional-activity` | Top 13F buyers/sellers vs the prior quarter. |
| `/v1/13f/market-activity` | Market-wide 13F leaderboards by bucket. |
| `/v1/13f/most-held` | Stocks ranked by 13F ownership breadth. |
| `/v1/institutions` | Search 13F filers by name. |
| `/v1/institutions/{cik}/portfolio` | An institution's reported portfolio. |
| `/v1/institutions/{cik}/summary` | Portfolio summary — AUM, concentration, turnover. |
| `/v1/institutions/{cik}/sector-allocation` | Portfolio allocation by industry. |
| `/v1/institutions/{cik}/activity` | Quarterly position-change buckets. |

## Funds & advisers

| Endpoint | Description |
|---|---|
| `/v1/funds` | Search the registered fund / ETF directory. |
| `/v1/funds/{ticker}/holdings` | Fund holdings from the latest NPORT-P. |
| `/v1/funds/{ticker}/operations` | Fund N-CEN operations and service providers. |
| `/v1/stocks/{ticker}/fund-owners` | Funds and ETFs holding a stock. |
| `/v1/investment-advisers` | Search SEC-registered advisers (Form ADV). |
| `/v1/investment-advisers/{crd}` | Full Form ADV profile by Org CRD. |

## Insider trading

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/insider-transactions` | Insider transactions (Form 3/4). |
| `/v1/stocks/{ticker}/insider-ownership` | Current insider ownership. |
| `/v1/stocks/{ticker}/proposed-sales` | Proposed insider sales (Form 144). |
| `/v1/insiders` | Search corporate insiders by name. |

## Congressional trading

| Endpoint | Description |
|---|---|
| `/v1/congress/members` | Search members of Congress by name. |
| `/v1/congress/trades` | Congressional trades by ticker and/or member. |
| `/v1/congress/members/{id}/net-worth` | Member net-worth history (bands). |
| `/v1/congress/market-activity` | Market-wide congressional trading aggregates. |

## Short data

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/short-volume` | Daily FINRA short volume. |
| `/v1/stocks/{ticker}/short-interest` | Bi-monthly FINRA short interest. |
| `/v1/stocks/{ticker}/off-exchange-volume` | Weekly dark-pool / OTC volume. |
| `/v1/short-interest/snapshot` | Market-wide short-interest snapshot. |
| `/v1/short-volume/largest` | Stocks with the largest daily short volume. |
| `/v1/short-squeeze-scores` | Highest composite short-squeeze scores (0–100). |

## Government contracts

| Endpoint | Description |
|---|---|
| `/v1/stocks/{ticker}/government-contracts` | Federal contract awards won by a company. |
| `/v1/government-contracts/top` | Companies ranked by total federal contract dollars. |

## FDA catalysts

| Endpoint | Description |
|---|---|
| `/v1/fda/catalysts` | Scheduled FDA advisory-committee meetings, soonest first. |

## Economic data (FRED)

| Endpoint | Description |
|---|---|
| `/v1/fred/series` | Search FRED economic series. |
| `/v1/fred/series/{seriesId}/observations` | Historical observations for a series. |
| `/v1/fred/latest` | Latest observation for every tracked series. |
| `/v1/fred/calendar` | Economic release calendar with importance tier. |

## Futures positioning (CFTC)

| Endpoint | Description |
|---|---|
| `/v1/cftc/contracts` | Search CFTC futures contracts. |
| `/v1/cftc/contracts/{marketCode}/positions` | Weekly COT positioning for a contract. |
| `/v1/cftc/positions/latest` | Latest COT snapshot across contracts. |

## Market sentiment (CBOE)

| Endpoint | Description |
|---|---|
| `/v1/market/put-call-ratios` | CBOE put/call ratio history. |
| `/v1/market/vix` | CBOE VIX daily OHLC (from 1990). |

---

# Rate limits & errors

REST and MCP share a single daily request limit per account. Every response carries headers so you can track usage, and errors follow a consistent JSON shape.

## Daily limits

One counter covers both the REST API and MCP tool calls. It resets at **00:00 UTC**.

| Plan | Requests / day | Scope |
|---|---|---|
| Free | 100 | REST + MCP combined |
| Pro | 10,000 | REST + MCP combined |

Need more? [Compare plans](/pricing).

## Rate-limit headers

Every counted response includes these headers:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Your plan's daily request limit. |
| `X-RateLimit-Remaining` | Requests left today. |
| `X-RateLimit-Reset` | Unix time (seconds) when the counter resets — next UTC midnight. |
| `Retry-After` | Seconds to wait — sent only on a `429`. |

## When you hit the limit

Over the limit, the REST API returns `429 Too Many Requests` with the error envelope below. The MCP server instead returns a normal tool result whose text explains the limit and links to upgrade — so your agent can relay it in the conversation rather than surfacing an opaque transport error.

```json
{ "error": { "code": "rate_limited", "message": "Daily call limit exceeded.", "status": 429 } }
```

## Error format

Every non-2xx REST response uses the same envelope:

```json
{
  "error": {
    "code": "not_found",
    "message": "Stock not found.",
    "status": 404
  }
}
```

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_parameter` | A query parameter is missing or malformed. |
| 401 | `unauthorized` | Missing or invalid API key. |
| 403 | `forbidden` | Your plan doesn't allow this request. |
| 404 | `not_found` | No matching resource. |
| 429 | `rate_limited` | Daily limit exceeded — retry after reset. |
| 500 | `internal_error` | Something went wrong on our side. |

---

# Data coverage

Equibles covers US-listed companies with data sourced directly from primary regulators and exchanges. The web interface shows a curated slice of each dataset; the [MCP server](/docs/mcp) and [REST API](/docs/api) expose the full set.

## Filings & fundamentals

| Dataset | What it covers | Source |
|---|---|---|
| SEC filings | 10-K, 10-Q, 8-K, 20-F, 6-K, 40-F and amendments, with full text. | SEC EDGAR |
| Financial facts | Income statement, balance sheet, and cash flow from tagged XBRL. | SEC EDGAR (XBRL) |
| Earnings calls | Full transcripts with speaker attribution, briefs, and insights. | Company webcasts |
| KPIs & guidance | Company-reported KPIs, non-GAAP bridges, and forward guidance. | SEC filings |

## Ownership & trading

| Dataset | What it covers | Source |
|---|---|---|
| Institutional holdings | 13F portfolios, top holders, and quarter-over-quarter activity. | SEC EDGAR (13F) |
| Insider trading | Form 3/4 transactions, ownership, and Form 144 proposed sales. | SEC EDGAR |
| Congressional trading | Stock trades and net worth for members of Congress. | Congressional disclosures |
| Funds & ETFs | NPORT-P holdings, N-CEN operations, and Form ADV advisers. | SEC EDGAR |

## Market & short data

| Dataset | What it covers | Source |
|---|---|---|
| Short volume & interest | Daily short volume, bi-monthly short interest, and squeeze scores. | FINRA |
| Off-exchange volume | Weekly dark-pool / OTC (ATS) volume. | FINRA |
| Fails to deliver | SEC fails-to-deliver records. | SEC |
| Stock prices | Daily OHLCV history and computed technical indicators. | Yahoo Finance |

## Macro & derivatives

| Dataset | What it covers | Source |
|---|---|---|
| Economic indicators | Rates, inflation, GDP, employment, and a release calendar. | FRED |
| Futures positioning | Weekly Commitments of Traders (COT) positioning. | CFTC |
| Market sentiment | CBOE VIX (from 1990) and put/call ratios. | CBOE |
| Capital returns | Buyback and at-the-market (ATM) equity programs. | SEC filings |

## Freshness & accuracy

Data is ingested continuously from the source of record — new filings, prices, and disclosures are picked up as they're published. We don't apply heuristics to classify financial data; values come from authoritative fields (entity types, SIC codes, XBRL tags) so numbers match the source.

---

# Changelog

What's new across the MCP server, the REST API, and the data behind them — newest first. Changes within `v1` are **additive**: new tools, endpoints, and fields are added; existing ones don't change shape or disappear. This log starts July 2026.

## 2026-07-13 — Docs

- **One-click connector setup.** Cursor (an *Add to Cursor* button), Claude Code (`claude mcp add`), and VS Code (`code --add-mcp`) now sign in over OAuth — no API key to manage. See [Connect the MCP server](/docs/mcp).
- **Tools in detail.** A new [reference page](/docs/mcp/tool-examples) shows ten flagship tools with their parameters, an example prompt, and a real sample of what they return.
- **Recipes.** Task-oriented [workflows](/docs/recipes) that chain several tools — analyze an earnings call, screen then deep-dive, track ownership shifts, build a short-squeeze view, value a company in context.
- **Guides.** An [MCP vs REST](/docs/mcp-vs-rest) decision guide and a [Claude Skill template](/docs/mcp/claude-skill) that encodes our research conventions.

## 2026-07-11 — API & data

- **Public REST API v1.** Every MCP tool now has a plain-JSON twin at `api.equibles.com/v1`, sharing your daily quota. See the [endpoint reference](/docs/api/endpoints).
- **REIT valuation.** `GetValuationMultiples` now returns P/FFO and P/AFFO for REITs, computed from each company's own SEC FFO/AFFO reconciliation, instead of leaning on P/E.
- **Short-squeeze scoring.** `GetShortSqueezeScores` became a composite rank — short interest as a percent of float, days to cover, the change in short share of volume, and fails-to-deliver, with catalyst boosts for price spikes, volume surges, and near-term earnings.

---

# Recipes

Single tools answer single questions. The real work happens when your agent chains several — screen, then dig into a name; read a call, then check the numbers behind it. Each recipe below is a short workflow with the tools it leans on and a prompt you can paste.

- [Analyze an earnings call end-to-end](/docs/recipes/earnings-call) — brief → themes → the fundamentals behind the quarter.
- [Screen, then deep-dive a name](/docs/recipes/screen-and-deep-dive) — narrow the universe, then pull the full picture on a match.
- [Track a stock's ownership shift](/docs/recipes/ownership-shift) — who's buying and selling across 13F, insiders, and Congress.
- [Build a short-squeeze view](/docs/recipes/short-squeeze) — score the board, then stress-test a candidate.
- [Value a company in context](/docs/recipes/value-in-context) — multiples vs peers, guidance, and capital returns.

Every recipe works the same way in any [connected client](/docs/mcp): describe the goal in plain English and let the model call the tools in order — you don't invoke them yourself. Prefer to wire it up in code? Each tool has a [REST twin](/docs/api/endpoints).

---

# Analyze an earnings call

Read a quarter the way an analyst does: start with what was said, then check it against the numbers.

## The flow

1. **Start with the brief.** `GetEarningsBrief` returns a TL;DR, the bullish and bearish points, and verbatim pull-quotes with speaker and role.
2. **Go deeper on themes.** `GetCallInsights` surfaces the key themes; `GetEarningsCallSpeakers` attributes remarks to each speaker.
3. **Check the numbers behind it.** `GetFinancialStatement` for the quarter, `GetRevenueBreakdown` for the segment/product/geography mix, and `GetGuidance` to see whether the outlook was raised, lowered, or held.
4. **Put it in context.** `GetValuationMultiples` shows whether the multiple still makes sense after the print.

## Prompt

> Walk me through NVIDIA's latest earnings call: the brief, the key themes, revenue by segment, and whether guidance went up — then tell me if the valuation still makes sense.

## What you get

A sourced read of the quarter — the narrative from the call, the segment numbers that back it, the direction of guidance, and the valuation the market is now paying — every figure traceable to the filing or transcript it came from.

---

# Screen, then deep-dive a name

Go from thousands of tickers to one thesis: filter the universe, then pull everything on the most interesting name.

## The flow

1. **Screen.** `ScreenStocks` combines range filters across market cap, price, 13F filer count and its change, short interest, days to cover, the squeeze and insider-sentiment scores, net insider buying, and the going-concern flag.
2. **See who owns it.** `GetTopHolders` for the biggest institutions; `GetTopBuyersSellers` for who added and trimmed last quarter.
3. **Check the insiders and Congress.** `GetInsiderTransactions` and `GetInsiderSentimentScores`, plus `GetCongressionalTrades`.
4. **Read the fundamentals and valuation.** `GetFinancialStatement` and `GetValuationMultiples` in context of the industry.
5. **Get the story.** `SearchCompanyDocuments` or `GetEarningsBrief` for the qualitative picture.

## Prompt

> Screen for profitable $2B+ software names trading under 6× EV/Revenue, then give me the full picture on the most interesting one — top holders, recent insider activity, last quarter's numbers, and how its valuation compares to peers.

## What you get

A shortlist you set the rules for, then a one-name deep dive that would otherwise take a dozen tabs — ownership, insider signal, fundamentals, and valuation, all sourced.

---

# Track a stock's ownership shift

Follow the money across every disclosure regime at once — institutions, insiders, Congress, and short sellers.

## The flow

1. **Institutions over time.** `GetOwnershipHistory` tracks 13F ownership quarter over quarter; `GetTopBuyersSellers` names the biggest adds and exits versus the prior quarter.
2. **Insiders.** `GetInsiderTransactions` for the raw Form 3/4 activity; `GetInsiderSentimentScores` for the composite read.
3. **Congress.** `GetCongressionalTrades` for disclosed trades by members.
4. **Short sellers.** `GetShortInterest` shows whether the float is getting more crowded.

## Prompt

> For Palantir, show how institutional ownership changed last quarter, recent insider buying or selling, any congressional trades, and where short interest sits now.

## What you get

A single view of who's on each side of the stock — smart money adding or trimming, insiders and lawmakers buying or selling, and whether the shorts are leaning in — instead of four separate data sources.

---

# Build a short-squeeze view

Find the crowded names, then pressure-test the one that looks real.

## The flow

1. **Score the board.** `GetShortSqueezeScores` with a liquidity floor (`minMarketCap` and/or `minDollarVolume`) so micro-caps don't dominate.
2. **Read the underlying series.** `GetShortInterest` (percent of float, days to cover), `GetShortVolume`, `GetOffExchangeVolume`, and `GetFailsToDeliver`.
3. **Check for a catalyst.** `GetEarningsBrief` or `ListInvestorEvents` — a squeeze needs a spark, and a near-term earnings date is often it.
4. **See who's on each side.** `GetTopHolders` and `GetInsiderTransactions`.

## Prompt

> Show the top short-squeeze scores among $500M+ stocks, then for the top name break down short interest, days to cover, fails-to-deliver, and whether earnings are coming up.

## What you get

A ranked, liquidity-filtered board of squeeze candidates, then the raw mechanics behind one — so you can tell a genuinely crowded, catalyst-close setup from a score that's just noise. The score is peer-relative; the series behind it are the facts.

---

# Value a company in context

"Cheap" and "expensive" only mean something in context. Build that context in one pass.

## The flow

1. **Multiples versus peers, and over time.** `GetValuationMultiples` puts EV/Revenue, EV/EBIT, and P/E next to the industry median and quartiles; `GetValuationMultiplesHistory` shows the trend. (For REITs the reply carries P/FFO and P/AFFO instead of leaning on P/E.)
2. **The earnings behind the multiple.** `GetFinancialStatement`, `GetNonGaapBridge` (how adjusted numbers reconcile to GAAP), and `GetCompanyKpis`.
3. **The forward view.** `GetGuidance` for management's own outlook and how it's trended.
4. **Capital returns.** `GetBuybackPrograms` and `GetAtmPrograms` — is the company buying its stock back, or issuing more?

## Prompt

> Is Apple expensive? Show its EV/Revenue and P/E versus the industry, how those multiples have trended, its latest guidance, and how aggressively it's buying back stock.

## What you get

A valuation you can defend — the multiple, the peer set it's measured against, the earnings and guidance that justify (or don't) the premium, and whether the company is shrinking or growing its share count. Nothing estimated; every input traces to a filing.