> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dripstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Investor Profiles

> One investor, four endpoints: profile, picks, trades and benchmark — for 13F funds and media sources on one vocabulary.

A **profile** is one tracked investor, and the same four endpoints describe
every one of them. A writer's record and a fund manager's record answer the
same questions in the same field names, so a client that reads a fund can read
a source without a second parser.

The keys are shared; some values are not. `side` is `buy`/`sell` on a fund and
`long`/`short` on a source, and `kind` and `ruling` list their values per kind
in [Trades](#trades). A parser reads the keys once and branches on `kind`.

A track record is not a forecast. Every number here is computed from what was
published or filed; none of it is a recommendation.

## Two kinds, one vocabulary

| | 13F fund | Media source |
| - | - | - |
| Path | `/api/v2/funds/{slug}` | `/api/v2/sources/{sourceSlug}/profile` |
| What it is | An SEC 13F filer (or a fund group the detector linked) | A newsletter, blog, podcast or channel |
| A "pick" is | A change between filings — open, add, trim, close | A call mention — a quote, a thesis, a stated horizon |
| Holdings are | The chosen quarter's filed book | The lots still open today |
| Benchmark window | Filing-to-filing windows | Calendar months |
| Identity | `profile.platform` is `SEC_13F`, with the filing CIKs | `profile.platform` is the source platform, e.g. `SUBSTACK` |

`kind` says which one you are reading: `"13f"` or `"media"`.

`{slug}` for a fund is a bare CIK (`1067983`) or a name slug whose trailing
digits are the CIK (`berkshire-hathaway-1067983`). A source slug is the
normalized host (`bytesbeyondborders.substack.com`).

## The four endpoints

Every path below exists twice: on the account mount (plan required) and on the
wallet mount under `/api/v2/x402/…` (\$0.10 per call).

| Endpoint | Funds | Media |
| - | - | - |
| `…` (profile) | `/api/v2/funds/{slug}` | `/api/v2/sources/{sourceSlug}/profile` |
| `…/picks` | `/api/v2/funds/{slug}/picks` | `/api/v2/sources/{sourceSlug}/picks` |
| `…/trades` | `/api/v2/funds/{slug}/trades` | `/api/v2/sources/{sourceSlug}/trades` |
| `…/benchmark` | `/api/v2/funds/{slug}/benchmark` | `/api/v2/sources/{sourceSlug}/benchmark` |

**Access.** The account mount requires a PRO or EXPERT plan. There is no free
tier and no partial response: no credential, a rejected credential, or a
credential without a plan is `401` and returns no data. The wallet mount charges
**\$0.10 per call** — never per page — and needs no plan: a paying wallet reads
the full response, one payment one call. Account credentials on the wallet mount
are `403 wallet_only`; a plain request is `402` with the dual x402 / MPP
challenge.

**Units.** Every return is a fraction: `0.0521` is 5.21%. Every date is
`YYYY-MM-DD`. Nothing ends in `Pct`. The only dollars in any response are a 13F
filing's as-filed `valueUsd` — never P\&L, peak capital or an account return.
How the numbers are built is in the
[methodology](https://docs.dripstack.com/methodology).

## MCP tools

The same five surfaces are on the hosted MCP server (`/api/mcp`), plan-gated like
the account mount. Each returns exactly the JSON its HTTP twin returns — same
read model, not a second query:

| Tool | HTTP twin |
| - | - |
| `search_profiles` | discovery: funds by name/CIK, sources by name (no twin) |
| `get_profile` | `GET /api/v2/funds/{slug}` or `/sources/{sourceSlug}/profile` |
| `get_profile_picks` | the `/picks` route for the same profile |
| `get_profile_trades` | the `/trades` route for the same profile |
| `get_profile_benchmark` | the `/benchmark` route for the same profile |

Every tool takes one `profile` argument: a bare CIK (`1067983`), a fund slug
whose trailing digits are the CIK (`berkshire-hathaway-1067983`), or a source
slug (`bytesbeyondborders.substack.com`). `search_profiles` is the discovery
entry point — it returns `{ kind, id, name, cik | sourceSlug }` for both kinds.
Funds keep their REST list at `GET /api/v2/funds`; `search_sources` and
`list_sources` still return sources only, unchanged.

## Picks versus trades

A **pick** is the raw record: what the analyst said, or what the filing changed.
A **trade** is our reading of it — the $1 lot the call becomes, filled on a real
session, held until it is closed or its horizon runs out, and marked at the
latest close while it is still open. Each call opens its own lot: a repeated
recommendation adds a new $1 lot instead of merging into the open one, so
modeled exposure is one lot per call, not the analyst's sizing.

That distinction explains the two endpoints:

* `/picks` returns the mentions or the filing diffs, grouped by ticker, newest
  first. Nothing is priced; nothing is derived.
* `/trades` returns the legs with their fills, the trade each one opened, its
  `return`, SPY's `spyReturn` over the same window, and the `difference`.
  Every `pickId` on a trade event exists in `/picks` — see
  [Trades](#trades) for the one case where it is `null`.

A 13F fund's **holdings** (`profile.holdings`) are the chosen quarter's book, not
trades. A media profile's **holdings** are the lots still open today, with the
analyst's own horizon as `expires` — `null` when their words do not bucket
confidently, rather than a guessed default.

### The fill rule

A call fills at the **first close a reader could actually act on**: the post
day's own close when the post landed in time for a market-on-close order,
otherwise the next session's close. A 13F change fills at the first session
after the filing date — and a filing can land up to 45 days after quarter end,
so a fund's trades carry a real reporting lag the price series already reflects.

## Ranges select, and the benchmark windows

`from` and `to` choose which rows come back, and never re-derive anything:

* Trades are always derived over the whole history, so an add inside the range
  never reads as a new open.
* On `/benchmark` the range windows the **daily series**: it runs from the
  close before `from` to the close on `to`. `twr`, `spyTwr`, `difference`,
  drawdowns, risk and `growth` are rechained from exactly those sessions — a
  trade already open at the start comes in at that close, and back-to-back
  ranges chain to the combined range. `periods` are the rows overlapping the
  range, and `beat`/`compared` are counted over those rows. `benchmark.from` /
  `benchmark.to` echo the request.
* On `/picks` and `/trades` the range only selects which rows come back.

`limit` is capped at 100 for paged reads, with `total` beside it. Page size is
never a price: one call is one charge.

## `opinions=include|exclude` (media)

Every mention carries a sentiment, and some mentions are views that make no
trade. `opinions=exclude` is the site's **"Direct trades only"** toggle: own
trades and explicit calls to trade, dropping the views. The default is
`include`. It is available on `/profile`, `/picks`, `/trades` and `/benchmark`;
on the benchmark it rescores the record without the opinion-only calls.

## Stock picks returns the same stats

`GET /api/v2/sources/{sourceSlug}/stock-picks` (and its
`/api/v2/publications/{slug}/stock-picks` predecessor) still answers, and its
`stats` are now the shared engine summary — the same `trades`,
`avgReturnPerTrade`, `winRate`, `winRateClosed` and `unpricedCalls` as
`/profile`. There is one win rate definition and no `Pct` field anywhere; the
legacy `extras` block was removed.

## Profile

`GET /api/v2/funds/{slug}` and `GET /api/v2/sources/{sourceSlug}/profile`.

```bash theme={null}
curl "https://dripstack.com/api/v2/funds/berkshire-hathaway-1067983?quarter=2026-06-30" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "13f",
  "asOf": "2026-11-17",
  "profile": {
    "name": "Berkshire Hathaway Inc",
    "platform": "SEC_13F",
    "filers": [{ "cik": "0001067983", "name": "Berkshire Hathaway Inc" }],
    "filings": 12,
    "quarters": ["2026-03-31", "2026-06-30"]
  },
  "stats": {
    "trades": 57,
    "avgReturnPerTrade": -0.1549,
    "winRate": 0.3333,
    "winRateClosed": 0.3333,
    "unpricedCalls": 3
  },
  "holdings": {
    "quarter": "2026-06-30",
    "filedDate": "2026-08-14",
    "positions": 41,
    "valueUsd": 258000000000,
    "rows": [
      {
        "ticker": "AAPL",
        "name": "Apple Inc",
        "shares": 300000000,
        "valueUsd": 61000000000,
        "weight": 0.2364,
        "change": { "kind": "trim", "shares": -20000000, "fraction": -0.0625 }
      }
    ]
  },
  "assets": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc",
      "picks": 4,
      "bullish": 1,
      "bearish": 3,
      "neutral": 0,
      "firstPick": "2025-11-14",
      "lastPick": "2026-08-14"
    }
  ]
}
```

`quarter` picks the holdings quarter (`YYYY-MM-DD`), defaulting to the latest. A
media profile answers with `kind: "media"`, a `profile` block carrying the
record's `from`/`to` span and its `posts` / `picks` / `opinions` counts, and
`holdings` as open lots. The media route also takes `opinions` (default
`include`): with `opinions=exclude` the `stats`, the `holdings` and the `assets`
summary all come from the explicit-only record, so the open lots match
`/trades?opinions=exclude&status=open`.

```bash theme={null}
curl "https://dripstack.com/api/v2/sources/bytesbeyondborders.substack.com/profile" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "media",
  "asOf": "2026-11-18",
  "computedAt": "2026-11-18T14:03:22.000Z",
  "profile": {
    "name": "Bytes Beyond Borders",
    "platform": "SUBSTACK",
    "imageUrl": null,
    "siteUrl": "https://bytesbeyondborders.substack.com",
    "from": "2026-05-15",
    "to": "2026-11-17",
    "posts": 18,
    "picks": 34,
    "opinions": 9
  },
  "stats": {
    "trades": 12,
    "avgReturnPerTrade": 0.0841,
    "winRate": 0.5833,
    "winRateClosed": 0.6,
    "unpricedCalls": 1
  },
  "holdings": [
    {
      "lotId": "clx0callid0001/long",
      "pickId": "clx0callid0001",
      "ticker": "NVDA",
      "name": "NVIDIA Corp",
      "side": "long",
      "since": "2026-08-18",
      "entryPrice": 174.2,
      "markDate": "2026-11-17",
      "markPrice": 186.4,
      "openFraction": 1,
      "return": 0.07,
      "expires": "2028-08-18"
    }
  ],
  "assets": [
    {
      "ticker": "NVDA",
      "name": "NVIDIA Corp",
      "picks": 3,
      "bullish": 2,
      "bearish": 1,
      "neutral": 0,
      "firstPick": "2026-05-15",
      "lastPick": "2026-08-14"
    }
  ]
}
```

Each holding carries its `lotId` (stable across re-derivations), the `pickId`
that opened it, and the prices behind `return`: `entryPrice` at the fill and
`markPrice` at the latest close (`markDate`). Returns are fractions and
reproduce exactly — `return = (markPrice − entryPrice) / entryPrice` for a long,
flipped for a short. `markPrice: null` means no mark, so `return` is `null` too.
Two same-day lots are two rows, distinguished by `lotId`.

## Picks

`GET /api/v2/funds/{slug}/picks` and
`GET /api/v2/sources/{sourceSlug}/picks`.

Query: `from`, `to`, `ticker`, `limit` (1-100), `offset` — plus `opinions` on
the media route. `total` counts every matching pick before paging.

```bash theme={null}
curl "https://dripstack.com/api/v2/sources/bytesbeyondborders.substack.com/picks?limit=1&opinions=exclude" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "media",
  "from": null,
  "to": null,
  "total": 25,
  "limit": 1,
  "offset": 0,
  "assets": [
    {
      "ticker": "NVDA",
      "name": "NVIDIA Corp",
      "picks": [
        {
          "id": "clx0callid0001",
          "publishedAt": "2026-08-14T13:05:00.000Z",
          "postTitle": "The constraint is the compute",
          "postUrl": "https://bytesbeyondborders.substack.com/p/the-constraint",
          "action": "OPEN",
          "sentiment": "bullish",
          "quote": "I am adding to NVDA here.",
          "thesis": "Supply stays the binding constraint through 2027.",
          "timeframe": "next 2 years",
          "priceTarget": { "kind": "above", "value": 240, "currency": "USD" }
        }
      ]
    }
  ]
}
```

A fund's picks are changes between filings, and carry the filing facts instead:

```json theme={null}
{
  "kind": "13f",
  "from": "2026-01-01",
  "to": null,
  "total": 41,
  "limit": 100,
  "offset": 0,
  "assets": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc",
      "picks": [
        {
          "id": "AAPL#3",
          "quarter": "2026-06-30",
          "filedDate": "2026-08-14",
          "kind": "trim",
          "sentiment": "bearish",
          "shares": -20000000,
          "sharesAfter": 300000000,
          "fraction": -0.0625
        }
      ]
    }
  ]
}
```

A position held unchanged is not a pick: a 13F pick is always open, add, trim or
close. A leg that never resolved a price stays in `/trades` with its `ruling`
and is never dressed up as a pick.

## Trades

`GET /api/v2/funds/{slug}/trades` and
`GET /api/v2/sources/{sourceSlug}/trades` (the media twin — same params plus
`opinions`, same shape). Query: `from`, `to`, `ticker`, `status` (`open`,
`closed`, `all`), `limit` (1-100), `offset`.

`status` filters on the **asset's** standing — still held at the latest quarter,
or exited — because the engine scores no per-lot exit.

```bash theme={null}
curl "https://dripstack.com/api/v2/funds/berkshire-hathaway-1067983/trades?status=open&limit=1" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "13f",
  "asOf": "2026-11-17",
  "from": null,
  "to": null,
  "total": 3,
  "limit": 1,
  "offset": 0,
  "assets": [
    {
      "ticker": "AAPL",
      "name": "Apple Inc",
      "stats": {
        "trades": 2,
        "avgReturnPerTrade": 0.12,
        "winRate": 0.5,
        "winRateClosed": null,
        "unpricedCalls": 0
      },
      "lastPrice": 231.4,
      "events": [
        {
          "date": "2026-08-14",
          "kind": "add",
          "side": "buy",
          "fillDate": "2026-08-17",
          "price": 224.9,
          "pickId": "AAPL#1",
          "ruling": "counted",
          "trade": {
            "return": 0.0289,
            "spyReturn": 0.0112,
            "difference": 0.0177,
            "status": "open",
            "pieces": [
              {
                "shares": 20000000,
                "entryDate": "2026-08-17",
                "entryPrice": 224.9,
                "return": 0.0289
              }
            ]
          }
        }
      ]
    }
  ]
}
```

`ruling` says what the leg's scoring fate was: `counted`, `unpriced`,
`held_out` (a book move inside a detected fund group, not a trade), or
`not_reported` (a quarter that asserted nothing new).

### Media trades

`GET /api/v2/sources/{sourceSlug}/trades` — the same engine, opened up: every
event it ruled for the publication, with the `$1` lot each opening call became.
Query: `from`, `to`, `ticker`, `status` (`open`/`closed`/`all`, the asset's
standing), `opinions` (`include`/`exclude`), `limit` (1-100), `offset`. `total`
counts events.

```bash theme={null}
curl "https://dripstack.com/api/v2/sources/bytesbeyondborders.substack.com/trades?status=open&limit=1" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "media",
  "asOf": "2026-11-18",
  "computedAt": "2026-11-18T14:03:22.000Z",
  "from": null,
  "to": null,
  "total": 7,
  "limit": 1,
  "offset": 0,
  "assets": [
    {
      "ticker": "NVDA",
      "name": "NVIDIA Corp",
      "stats": {
        "trades": 2,
        "avgReturnPerTrade": 0.0841,
        "winRate": 1,
        "winRateClosed": null,
        "unpricedCalls": 0
      },
      "lastPrice": { "date": "2026-11-17", "close": 186.4 },
      "events": [
        {
          "date": "2026-08-14",
          "kind": "add",
          "side": "long",
          "fillDate": "2026-08-17",
          "price": 174.2,
          "pickId": "clx0callid0001",
          "ruling": "counted",
          "trade": {
            "return": 0.07,
            "spyReturn": 0.0112,
            "difference": 0.0588,
            "status": "open",
            "pieces": [{ "fraction": 1, "open": true, "price": 186.4, "return": 0.07 }]
          }
        }
      ]
    }
  ]
}
```

What the fields mean:

* `kind` is the engine's event: `open`, `add`, `restart`, `keep`, `close`,
  `trim`, `flip`, `expire`, plus the two that never traded — `no-trade` (the
  rules ruled the call out) and `no-price` (no session to fill on).
* `ruling` is that reading in one word: `counted`, `unpriced`, or `no_trade`.
  Nothing is dropped — an unpriced call keeps its event with `trade: null`.
* `trade` is the lot the event **opened**, with `status` (`open`, `closed`, or
  `partly open` — a `REDUCE` closes half) and `pieces`: each closed slice's
  `fraction`, `date`, `price`, `reason` and `return`, plus the still-open
  remainder as a piece with `open: true` at the latest mark. A close, a keep or
  an expiry has `trade: null` — closing is not opening.
* `pickId` is the `/picks` row behind the event, and every non-null `pickId` in
  `/trades` is a `/picks` id, always. An explicit exit call has no pick row — it
  ends an episode rather than stating a view — so its event carries
  `pickId: null` rather than pointing at an id `/picks` never returns.
* `pricingStatus` appears only on an `unpriced` event: `pending` while the
  background filler can still resolve the fill, `unresolvable` when the
  instrument never prices.

## Benchmark

`GET /api/v2/funds/{slug}/benchmark` and
`GET /api/v2/sources/{sourceSlug}/benchmark`. Query: `from`, `to`.

The score is time-weighted: the profile's daily series against **SPY bought
once at the profile's start and held** over the same days. `difference` is the
copy-trade answer.

```bash theme={null}
curl "https://dripstack.com/api/v2/funds/berkshire-hathaway-1067983/benchmark?from=2026-01-01" \
  -H "Authorization: Bearer pk_drip_..."
```

```json theme={null}
{
  "kind": "13f",
  "asOf": "2026-11-17",
  "benchmark": {
    "from": "2026-01-01",
    "to": "2026-11-17",
    "twr": 0.1832,
    "spyTwr": 0.0941,
    "difference": 0.0891,
    "beat": 2,
    "compared": 3,
    "sharpe": 1.14,
    "spySharpe": 0.92,
    "volatility": 0.281,
    "spyVolatility": 0.174,
    "alpha": 0.041,
    "beta": 0.87,
    "maxDrawdown": -0.112,
    "spyMaxDrawdown": -0.074,
    "investedShare": 0.87,
    "riskStatus": "provisional",
    "months": 11,
    "periods": [
      {
        "from": "2026-08-17",
        "to": "2026-11-17",
        "ongoing": true,
        "return": 0.0421,
        "spyReturn": 0.0188,
        "difference": 0.0233,
        "priced": 0.96,
        "partial": true
      }
    ],
    "growth": [
      { "date": "2026-11-16", "value": 1.031, "spyValue": 1.011 },
      { "date": "2026-11-17", "value": 1.042, "spyValue": 1.019 }
    ]
  }
}
```

* `riskStatus` is the risk maturity band: `insufficient` under 6 months,
  `provisional` to 35, `standard` at 36+. `months` is the month count behind it.
* `sharpe` and `volatility` score the profile's own daily line; `spySharpe` and
  `spyVolatility` are SPY's, computed the same way over the same days.
* `growth` is the trailing-3-month chart as levels rebased to `1` at the window
  start, not percentages.
* `investedShare` is the share of scored sessions with capital deployed — a
  record that is flat between trades reads below `1` even when its TWR is
  positive.
* Each period row carries `priced` (the share of the window's trades the engine
  could price, `1` when it covered none) and `partial`: coverage below complete.
  A 13F window is partial when some of its trades could not be priced; a media
  month is partial when it mixes trades already closed with ones still open.
* 13F periods are filing-to-filing windows; media periods are calendar months.

## Coverage honesty

The pipeline resolves prices in the background, so a record is only as complete
as its priced legs, and the API says so instead of dropping the gap:

* `stats.unpricedCalls` — trades that never resolved a price. Counted, never
  scored as 0%.
* `ruling` on a trade event — `unpriced`, `held_out`, `not_reported`, or
  `counted`.
* `pricingStatus` on an unpriced trade event — `pending` (the background filler
  may still resolve it) or `unresolvable` (it never will).
* `computedAt` on `/profile` and `/trades` — when that derivation ran. Pricing
  resolves between reads, so an `unpriced` event can become `counted` later;
  compare `computedAt` when two responses disagree.
* A 13F profile's holdings only cover the quarter asked for; the picked quarter
  is always echoed back as `holdings.quarter`.

The website shows the same gaps in its counters caption. If a number looks thin,
check the coverage fields before reading it as performance.

## Per analyst

The unit today is a **source profile**. An analyst who publishes in two places
is two profiles — there is no cross-source analyst view endpoint, and the two
records are not merged. To find a writer, search the curated catalog by name:

```bash theme={null}
curl "https://dripstack.com/api/v2/sources/search?q=doomberg" \
  -H "Authorization: Bearer pk_drip_..."
```

Search matches slug, title, **author name**, podcast show, newsletter, and site
URL across the curated catalog, and returns up to 3 matches with `sourceSlug`.
Feed that slug into `GET /api/v2/sources/{sourceSlug}/profile`. A non-curated
source still answers on its own slug if you already know it, it just will not
appear in search.

## Errors

| Status | Meaning |
| - | - |
| `400` | Invalid query parameters (bad day, `limit` above 100, unknown `status`) |
| `401` | Account mount: missing/rejected credential, or no PRO/EXPERT plan — no data |
| `402` | Wallet mount: payment required (dual x402 / MPP challenge) |
| `403` | Wrong mount: `wallet_only` on `/api/v2/x402/…`, `account_only` on `/api/v2/…` |
| `404` | The fund or source is not in the derived corpus |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.