DeepValues MCP

The one endpoint that needs no key. Send {} for a dv_sk_test_ sandbox key (real data, small daily quota, never billed, no /research). Send {"email":"…"} for a dv_sk_live_ key on a new prepaid account; the first key for an email carries 1 starter credit ($1.00). Send it with an existing key as the bearer to mint a sibling key on the same account (rotation). The raw key is returned once. The email is a contact label, not a credential. Limited to 10 keys per address per day. The raw key is in the result once: keep it and send it as Authorization: Bearer on REST calls (or have the host re-add this server with that header). With a key already configured, mints a sibling on the same account. (POST https://app.deepvalues.ai/api/v1/keys — free; needs no credentials)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Contact address for a dv_sk_live_ key (1 starter credit the first time). Omit for a never-billed dv_sk_test_ sandbox key."
    },
    "label": {
      "type": "string",
      "maxLength": 80,
      "description": "Optional name for the key."
    }
  },
  "additionalProperties": false
}

{
  "title": "Mint an API key — no account, session or browser needed",
  "readOnlyHint": false,
  "openWorldHint": true,
  "idempotentHint": false,
  "destructiveHint": false
}

Returns the calling key, the exact balance of the ledger behind it (balanceMicro: integer micro-credits, 1 credit = $1.00 = 1,000,000), what is left in each daily quota bucket, and the environment. Free, and consumes no quota. (GET https://app.deepvalues.ai/api/v1/keys/me — free; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "title": "This key: exact credit balance, remaining quota, environment",
  "readOnlyHint": true,
  "openWorldHint": true
}

Lists the prepaid credit packs this key can buy (1 credit = $1.00). Free. (GET https://app.deepvalues.ai/api/v1/credits/checkout — free; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "title": "Credit packs on sale",
  "readOnlyHint": true,
  "openWorldHint": true
}

Creates a one-time Stripe Checkout Session for a credit pack, bound to the calling live key’s account. When the payment completes the credits land on that balance; poll GET /keys/me. This is what a 402 `topUp.checkoutEndpoint` points at. Free, consumes no quota. (POST https://app.deepvalues.ai/api/v1/credits/checkout — free; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "required": [
    "pack"
  ],
  "properties": {
    "pack": {
      "type": "string",
      "description": "Credit pack to buy, e.g. \"1000\". The `credits_packs` tool lists the packs on sale."
    }
  },
  "additionalProperties": false
}

{
  "title": "Get a Stripe Checkout URL that tops up this key’s balance",
  "readOnlyHint": false,
  "openWorldHint": true,
  "idempotentHint": false,
  "destructiveHint": false
}

Every endpoint’s per-call price (credits, USD and atomic USDC), the free allowances, the daily quotas, and how an agent pays without a human: x402 in USDC — per call with no key, or as a prepaid top-up of a key — when it is switched on, or a Stripe Checkout link a human pays. Also served at /api/v1/pricing.json. Needs no key, costs nothing, consumes no quota. (GET https://app.deepvalues.ai/api/v1/pricing — free; needs no credentials)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "title": "Machine-readable price list and the ways to pay",
  "readOnlyHint": true,
  "openWorldHint": true
}

Returns the calling key, its scopes, environment, and today's usage across all 3 buckets. Self-billing: counts as 1 metadata call. (GET https://app.deepvalues.ai/api/v1/account — free; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "title": "Account info + current quota usage",
  "readOnlyHint": true,
  "openWorldHint": true
}

Returns a system prompt + structured context block, scoped to one ticker. Drop it into OpenAI/Anthropic/any LLM SDK to ground your chatbot in current Deep Values data without months of plumbing. Bills 3 metadata units. (GET https://app.deepvalues.ai/api/v1/ai-context/{ticker} — 0.005 credits per call; works with no credentials up to 1 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    },
    "token_budget": {
      "type": "integer",
      "default": 6000,
      "maximum": 16000,
      "minimum": 1000
    }
  },
  "additionalProperties": false
}

{
  "title": "Drop-in AI grounding context (DIFFERENTIATED)",
  "readOnlyHint": true,
  "openWorldHint": true
}

Full briefing, bull case, bear case, valuation, investment plan and fair-value range as one structured JSON document. 3 credits ($3.00) per successful call, ai_research quota 50/day. Returns the latest completed briefing for the ticker — the same one its public company page shows; a fresh run cannot be started through the API yet (404 when none exists). Never keyless, not in the sandbox. (GET https://app.deepvalues.ai/api/v1/research/{ticker} — 3 credits per call; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    },
    "language": {
      "enum": [
        "English",
        "Chinese"
      ],
      "type": "string",
      "default": "English"
    }
  },
  "additionalProperties": false
}

{
  "title": "AI multi-analyst research briefing (HEADLINE)",
  "readOnlyHint": true,
  "openWorldHint": true
}

Per-method intrinsic value per share (DCF on free cash flow, owner earnings, Damodaran two-stage), their equal-weight blend, Monte Carlo bounds and the implied gap to the current price. The blend is checked against the price before it is served: if it fails a check (not positive, more than 20x the price, a price older than five days, no price, or `currency_consistent`: statements left in a currency other than the USD price), the valuation fields are null, `withheld` is true, `checks.failed` names the check and the call is not charged. A value under 0.05x the price is served with the flag `iv_far_below_price`. A value built from statements converted to USD carries `fx` (`from` the filer's currency, `to` USD, `rate`, `rate_date`, `rate_type`) on `values.intrinsic_value_per_share` and each method input; `currency_unverified` in `checks.flags` means the statement currency is not known for this ticker, so the check did not run. A method with no value is null in `methods`, never 0, and `methods_unavailable` says why (`code`, `family`: negative_cash_flow, financial_company, withheld or missing_inputs, and the pipeline's `reason`). For a one-call answer with holders and a verdict, use /brief/{ticker}. (GET https://app.deepvalues.ai/api/v1/intrinsic-value/{ticker} — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "DCF + Owner Earnings + Damodaran intrinsic value",
  "readOnlyHint": true,
  "openWorldHint": true
}

Call this when the question is about what was known on a past date (a backtest, an audit, "what did the 10-K say at the time"), not about the current restated figures. Returns, for each fiscal period filed on or before `date`, the value as it stood on that date (the original filing, or a later filing for the same period if it came before `date`), the filing date, the XBRL tag, a sec.gov link, and `restated_after_date` when a later filing changed it. Values are as printed, not split-adjusted. Inputs: `ticker` (path), `date` (YYYY-MM-DD, required), `metrics` (comma-separated snake_case names, default revenues,net_income,eps_diluted,operating_cash_flow,free_cash_flow,stockholders_equity,total_debt,shares_outstanding), `period` (annual|quarterly), `limit` (periods, default 4). Example: GET /as-filed/AAPL?date=2020-02-01&metrics=revenues,net_income. If the company had filed none of it by `date`, the answer has no periods, the flag `nothing_filed_by_date` and `earliest_filed` (the first filing date on record). A 503 `as-filed-unavailable` means there is no as-filed history for the company to answer from; it is not charged, and GET /fundamentals has the current figures. 0.01 credits. (GET https://app.deepvalues.ai/api/v1/as-filed/{ticker} — 0.01 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker",
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "The day to look back from (YYYY-MM-DD, 2009-01-01 or later, not in the future)."
    },
    "limit": {
      "type": "integer",
      "default": 4,
      "maximum": 20,
      "minimum": 1,
      "description": "How many of the most recent periods filed by `date` to return."
    },
    "period": {
      "enum": [
        "annual",
        "quarterly"
      ],
      "type": "string",
      "default": "annual"
    },
    "ticker": {
      "type": "string",
      "pattern": "^[A-Z]{1,5}([.-][A-Z]{1,2})?$"
    },
    "metrics": {
      "type": "string",
      "description": "Comma-separated metric names (snake_case), at most 20."
    }
  },
  "additionalProperties": false
}

{
  "title": "Point-in-time fundamentals: what was filed as of a date, before restatement",
  "readOnlyHint": true,
  "openWorldHint": true
}

Call this first when asked whether a listed company looks cheap or expensive, what it is worth, or which well-known investors own it: one call returns the intrinsic value per share (with each valuation method as an input), the owner-earnings value, the margin of safety against the current price, a deterministic verdict sentence about where the price sits against our value range, the top tracked 13F holders and their last move, and the company profile. Every number carries its unit, period, as-of date and a sec.gov source link, and `checks` lists the sanity checks it passed. A value built from statements filed in another currency and converted to USD carries `fx` (original currency, rate, rate date) and passes `currency_consistent`; when the currency is not known the flag `currency_unverified` says the check did not run. If the valuation fails a check (for example an intrinsic value more than 20x the price, or statements left in a currency other than the USD price), the valuation figures are withheld, `withheld` is true, `checks.failed` names the check, and the call is not charged. Input: `ticker` (path), e.g. GET /brief/KO. The first brief each UTC day is free per key and per keyless address; after that 0.30 credits. Data and analysis, not investment advice. (GET https://app.deepvalues.ai/api/v1/brief/{ticker} — 0.3 credits per call; works with no credentials up to 1 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string",
      "pattern": "^[A-Z]{1,5}([.-][A-Z]{1,2})?$",
      "description": "US listing symbol, e.g. KO or BRK.B."
    }
  },
  "additionalProperties": false
}

{
  "title": "One-call valuation brief: intrinsic value, margin of safety, verdict, guru holders",
  "readOnlyHint": true,
  "openWorldHint": true
}

Returns every guru from our 60-name roster who held the requested ticker as of the latest 13F-HR quarter (or a specific historical quarter). Each row includes shares, USD value, % of portfolio, and the auto-classified delta vs the prior quarter. (GET https://app.deepvalues.ai/api/v1/smart-money/holdings — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string",
      "pattern": "^[A-Z]{1,5}([.-][A-Z]{1,2})?$"
    },
    "quarter_end": {
      "type": "string",
      "format": "date",
      "description": "ISO date; default = latest available"
    }
  },
  "additionalProperties": false
}

{
  "title": "Which curated gurus hold this ticker",
  "readOnlyHint": true,
  "openWorldHint": true
}

All 13F position changes meeting the materiality threshold (new positions, full exits, ≥25% share-count shifts, OR ≥$100M position size) across our entire 60-guru roster, in the requested window. (GET https://app.deepvalues.ai/api/v1/smart-money/changes — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "since"
  ],
  "properties": {
    "since": {
      "type": "string",
      "description": "ISO date OR YYYY-QN format. Filters on the QUARTER a position belongs to (quarter_end), not on when it was filed."
    },
    "status": {
      "enum": [
        "new",
        "added",
        "trimmed",
        "exited"
      ],
      "type": "string"
    },
    "filed_since": {
      "type": "string",
      "format": "date",
      "description": "Only rows that reached us on or after this date (each row carries filed_at). Use it to poll for genuinely new 13F filings; `since` alone cannot tell a filing from this week from one made months ago in the same quarter."
    },
    "min_position_usd": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

{
  "title": "Material guru moves in a time window",
  "readOnlyHint": true,
  "openWorldHint": true
}

The Follow the Pros feed. Every material 13F move — new position, full exit, a share count that moved by 25%, or a position of $100M or more — ordered by the date the filing became public, with a deterministic verdict line on each row. The verdict is identical for every caller: it compares the price when the investor traded, the price now and Deep Values' intrinsic value band, and it never predicts a return or recommends an action. Every row carries the company's legal name beside the ticker (`name`, e.g. "Occidental Petroleum"), or null where we hold none — null rather than the ticker echoed back, so a caller can tell a real name from a placeholder. Rows whose EDGAR filing date we do not yet hold fall back to when the row reached us and say so with filed_at_known: false. (GET https://app.deepvalues.ai/api/v1/gurus/moves — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "maximum": 200
    },
    "slugs": {
      "type": "string",
      "description": "Comma-separated guru slugs; default is every guru."
    },
    "filed_since": {
      "type": "string",
      "format": "date",
      "description": "Only moves filed on or after this date. Poll with it."
    }
  },
  "additionalProperties": false
}

{
  "title": "Material guru moves, newest filing first, each with its verdict",
  "readOnlyHint": true,
  "openWorldHint": true
}

One guru's disclosed move in one ticker, with the sentence Deep Values publishes about it and every number behind it: the company's legal name beside the ticker (`name`, null where we hold none), the three dates (traded by, filed, seen), the quarter-end close, the current price, and the intrinsic value band. `value` is the callable band (the blend ±25%) and is null whenever the verdict is not a call; `estimates` always carries what the valuation methods actually said, their lowest and highest central estimate, so a reader told we cannot call it can see why. One of six deterministic states — below_value, inside_band, above_value, ran_ahead, too_uncertain, no_value — computed the same way for every caller. The band is Deep Values' blended intrinsic value plus or minus 25%, and `too_uncertain` ("Our estimates disagree too much to call this one.") replaces the three band states when the methods' own central estimates are more than 3x apart, or one of them is not positive: the blend still exists, but `value` is null because it is not a range anyone should be told a price sits inside; `estimates` shows how far apart the methods are. It is distinct from `no_value`, which means no valuation was computed at all. Before the band is published its mid is checked against the current price (positive, at most 20x the price, a price under five days old; under 0.05x is served with the flag `iv_far_below_price`) and for currency (`currency_consistent`: the statements behind it are in USD, the price's currency, or were converted to USD; a converted band carries `fx` on `values.value_band_mid` naming the original currency and rate; when the currency is not known the answer carries the flag `currency_unverified` instead); on a failure `value` and `estimates` are null, the verdict reads `no_value`, `withheld` is true, `checks.failed` names the check, and the call is not charged. (GET https://app.deepvalues.ai/api/v1/verdict/{ticker} — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker",
    "guru"
  ],
  "properties": {
    "guru": {
      "type": "string"
    },
    "ticker": {
      "type": "string"
    },
    "quarter": {
      "type": "string",
      "format": "date",
      "description": "Quarter end; default = the most recent quarter we hold."
    }
  },
  "additionalProperties": false
}

{
  "title": "The verdict line for one filed move",
  "readOnlyHint": true,
  "openWorldHint": true
}

The same move as /verdict, flattened into a brief: what the investor did, when, at what price, against our value band, plus the verdict sentence. It carries NO quantity and NO instruction — `sizing` reads "not provided; the reader decides". It describes a public filing and a published value range; it is not advice and not a prediction. (GET https://app.deepvalues.ai/api/v1/mirror-brief/{ticker} — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker",
    "guru"
  ],
  "properties": {
    "guru": {
      "type": "string"
    },
    "ticker": {
      "type": "string"
    },
    "quarter": {
      "type": "string",
      "format": "date"
    }
  },
  "additionalProperties": false
}

{
  "title": "An impersonal brief on one filed move, for an agent to act on",
  "readOnlyHint": true,
  "openWorldHint": true
}

60 hand-picked institutional investors — every name a serious value investor would recognize. Filter by style. (GET https://app.deepvalues.ai/api/v1/gurus — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 200
    },
    "style": {
      "enum": [
        "value",
        "growth",
        "activist",
        "macro",
        "quant"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "Curated guru roster",
  "readOnlyHint": true,
  "openWorldHint": true
}

One guru: bio + top holdings (GET https://app.deepvalues.ai/api/v1/gurus/{slug} — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "One guru: bio + top holdings",
  "readOnlyHint": true,
  "openWorldHint": true
}

One guru's full portfolio at a quarter (GET https://app.deepvalues.ai/api/v1/gurus/{slug}/portfolio — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string"
    },
    "as_of": {
      "type": "string",
      "format": "date"
    }
  },
  "additionalProperties": false
}

{
  "title": "One guru's full portfolio at a quarter",
  "readOnlyHint": true,
  "openWorldHint": true
}

Public investment theses with structured metadata — sentiment, conviction, price target, anchored DVI run. Filter by ticker, conviction, or sentiment. (GET https://app.deepvalues.ai/api/v1/theses — 0.005 credits per call; works with no credentials up to 5 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "maximum": 200
    },
    "ticker": {
      "type": "string"
    },
    "sentiment": {
      "enum": [
        "bullish",
        "bearish",
        "neutral"
      ],
      "type": "string"
    },
    "min_conviction": {
      "type": "integer",
      "maximum": 5,
      "minimum": 1
    }
  },
  "additionalProperties": false
}

{
  "title": "Structured human investment theses",
  "readOnlyHint": true,
  "openWorldHint": true
}

US corporate equities ÷ GDP, with zones (significantly undervalued through significantly overvalued) and historical percentile. (GET https://app.deepvalues.ai/api/v1/indicators/buffett — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "history_years": {
      "type": "integer",
      "default": 5,
      "maximum": 50
    }
  },
  "additionalProperties": false
}

{
  "title": "Buffett Indicator with zone classification",
  "readOnlyHint": true,
  "openWorldHint": true
}

Shiller PE with historical percentile (GET https://app.deepvalues.ai/api/v1/indicators/shiller-pe — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "history_years": {
      "type": "integer",
      "default": 5,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

{
  "title": "Shiller PE with historical percentile",
  "readOnlyHint": true,
  "openWorldHint": true
}

Value-investor sentiment rollup (not WSB noise) (GET https://app.deepvalues.ai/api/v1/sentiment/{ticker} — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "source": {
      "enum": [
        "reddit",
        "stocktwits",
        "combined"
      ],
      "type": "string",
      "default": "combined"
    },
    "ticker": {
      "type": "string"
    },
    "window": {
      "enum": [
        "24h",
        "7d",
        "30d"
      ],
      "type": "string",
      "default": "7d"
    }
  },
  "additionalProperties": false
}

{
  "title": "Value-investor sentiment rollup (not WSB noise)",
  "readOnlyHint": true,
  "openWorldHint": true
}

Sentiment-scored news (GET https://app.deepvalues.ai/api/v1/news/{ticker} — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "since": {
      "type": "string",
      "format": "date"
    },
    "ticker": {
      "type": "string"
    },
    "sentiment": {
      "enum": [
        "bullish",
        "bearish",
        "neutral"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "Sentiment-scored news",
  "readOnlyHint": true,
  "openWorldHint": true
}

Company search (GET https://app.deepvalues.ai/api/v1/companies — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

{
  "title": "Company search",
  "readOnlyHint": true,
  "openWorldHint": true
}

Company overview (GET https://app.deepvalues.ai/api/v1/companies/{ticker}/overview — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "Company overview",
  "readOnlyHint": true,
  "openWorldHint": true
}

Income + balance + cashflow (GET https://app.deepvalues.ai/api/v1/fundamentals/{ticker} — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 5,
      "maximum": 20
    },
    "period": {
      "enum": [
        "annual",
        "quarterly"
      ],
      "type": "string",
      "default": "annual"
    },
    "ticker": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "Income + balance + cashflow",
  "readOnlyHint": true,
  "openWorldHint": true
}

SEC filings (10-K, 10-Q, 8-K, etc) (GET https://app.deepvalues.ai/api/v1/filings/{ticker} — 0.001 credits per call; works with no credentials up to 25 call(s)/day per address)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "form": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 50
    },
    "ticker": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "title": "SEC filings (10-K, 10-Q, 8-K, etc)",
  "readOnlyHint": true,
  "openWorldHint": true
}

List webhook subscriptions (GET https://app.deepvalues.ai/api/v1/webhooks — free; needs a connected account or a dv_sk_ key)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "title": "List webhook subscriptions",
  "readOnlyHint": true,
  "openWorldHint": true
}