> ## 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.

# Stock Picks

> Ticker-level analyst calls with two API versions: V2 (subscription or x402 pay-per-use) and legacy V1 (single-day paid).

A **stock pick** is a ticker-level call extracted from a source article — an
analyst recommendation, a long/short idea, an add, or an exit. Drip serves
these as structured JSON for AI agents, separate from the newsletter/article
workflow.

There are two API versions. Use **V2**; V1 exists for existing integrations and
stays available unchanged.

|                                   | V2 (recommended)                                            | V1 (legacy)                                                 |
| --------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| Routes                            | `GET /api/v2/stock-picks` · `GET /api/v2/stock-picks/quote` | `GET /api/v1/stock-picks` · `GET /api/v1/stock-picks/quote` |
| Access model                      | Subscription (PRO/EXPERT) **or** x402 pay-per-use           | Credits / x402 pay-per-use only                             |
| Time coverage                     | One day **or** date ranges (`from`/`to`)                    | One UTC calendar day only                                   |
| Filters, search, sort, pagination | ✅                                                           | ❌                                                           |
| Response envelope                 | `meta` + `pagination` + `picks[]`                           | `dateUsed` + `count` + `items[]`                            |
| Status                            | Active                                                      | Deprecated for new integrations (still available)           |

## V2 — `GET /api/v2/stock-picks`

The recommended endpoint. It resolves the caller's plan from the bearer
credential first, then either serves the request from the subscription window
**free of charge** or routes anonymous / FREE callers through the same
pay-per-use flow as V1.

### Subscription access (Bearer API key, OAuth token, or session JWT)

* **EXPERT** readers get full history. **PRO** is clamped to the live 7-day
  window.
* In-plan requests are **never charged** and count against the API key's
  monthly request allowance (`429` when exhausted).
* An explicit `date` outside the plan window returns `403`; out-of-window
  ranges are silently clamped — read `meta.allowedRange` / `meta.appliedRange`.

```bash theme={null}
# Latest picks in-window (free for PRO/EXPERT subscribers)
curl -H "Authorization: Bearer pk_drip_..." \
  "https://dripstack.com/api/v2/stock-picks"

# A date range, oldest-first, 3 days per page
curl -H "Authorization: Bearer pk_drip_..." \
  "https://dripstack.com/api/v2/stock-picks?from=2026-05-01&to=2026-05-31&sort=oldest&limitDays=3"
```

### Pay-per-use (anonymous or FREE)

No free API access. Call the free quote, confirm the `amountUsd`, then pay. The
paid path accepts `date` / `limit` only (filters and ranges are paid-tier
features).

```bash theme={null}
# 1. Free preflight — exact bundle price, no auth
curl "https://dripstack.com/api/v2/stock-picks/quote?date=2026-05-30"

# 2. Pay per the quoted amountUsd through your payment-aware client
#    (x402/MPP on the 402 challenge), then:
curl "https://dripstack.com/api/v2/stock-picks?date=2026-05-30"
```

### V2 query parameters

| Param           | Meaning                                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| `date`          | One UTC day (mutually exclusive with `from`/`to`)                              |
| `from` / `to`   | Inclusive UTC day range, clamped to the caller's plan window                   |
| `limit`         | Max pick rows per day (1-500, default 200)                                     |
| `limitDays`     | Max days per range page (1-30, default 7); pass `cursor` to page older         |
| `cursor`        | Older-than marker from the previous response's `pagination.nextCursor`         |
| `author`        | Exact author name filter (paid tiers)                                          |
| `direction`     | `LONG` or `SHORT` (paid tiers)                                                 |
| `query`         | Case-insensitive substring over ticker, author, publication title (paid tiers) |
| `sort`          | `newest` (default) or `oldest`                                                 |
| `includePrices` | Pass `false` to omit per-ticker performance (on by default)                    |

Each `picks[]` item includes `date`, `ticker`, `direction`, `action`, `author`,
`publicationSlug`, `publicationTitle`, `articleUrl` (Drip's sellable URL when a
post is attributed), `conviction`, `convictionLabel`, `evidenceQuote`,
`rationaleSnippet`, `publishedAt`, and `prices` (`entry`, `current`,
`returnPct` — direction-adjusted).

V2 errors: `400` invalid query, `401` bad bearer, `402` payment required,
`403` explicit date/range outside the plan window, `404` no picks (paid path),
`429` request allowance exhausted.

## V1 — `GET /api/v1/stock-picks` (legacy, still available)

The original endpoint. It always returns **one effective UTC calendar day** —
the latest day with picks by default, or `date=YYYY-MM-DD` for a specific day.
Pricing is a flat unit price × the number of distinct attributed source
articles in the response; call `GET /api/v1/stock-picks/quote` for the exact
total, then pass the quoted `dateUsed` on the paid request. A `404` means no
picks exist for that day — do not pay.

```bash theme={null}
# Free preflight
curl "https://dripstack.com/api/v1/stock-picks/quote"

# Paid list (credits bearer or x402/MPP client)
curl -H "Authorization: Bearer pk_drip_..." \
  "https://dripstack.com/api/v1/stock-picks"
```

Response: `dateUsed`, `startDate`, `endDate`, `asOf`, `count`, and `items[]`
with `ticker`, `tickerExchange`, `instrumentType`, `action`, `direction`,
`authorConviction`, `convictionLabel`, `activePick`, `evidenceQuote`,
`rationaleSnippet`, `articleTitle`, `articleUrl`, `author`, `publishedAt`,
`publicationSlug`, and `postSlug`.

## Migrating from V1 to V2

1. **Switch URLs** — `/api/v1/stock-picks` → `/api/v2/stock-picks` and
   `/api/v1/stock-picks/quote` → `/api/v2/stock-picks/quote`. Single-day
   callers can keep passing `date=YYYY-MM-DD` unchanged.
2. **Authenticate** — if the caller has a PRO or EXPERT plan (Bearer API key,
   OAuth, or JWT), in-window reads become free, no quote or payment needed. The
   paid path for everyone else stays quote → confirm → pay.
3. **Adapt the response** — `items[]` becomes `picks[]`, `dateUsed` /
   `startDate` / `endDate` become `meta` + a `date` on each pick, and the item
   fields change:

| V1 field                                                         | V2 field                                                         |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| `items[]`                                                        | `picks[]`                                                        |
| `dateUsed` / `startDate` / `endDate`                             | `meta.asOf` / `meta.appliedRange`, plus `date` per pick          |
| `authorConviction`                                               | `conviction`                                                     |
| `articleUrl`                                                     | Drip sellable URL when a post is attributed                      |
| `tickerExchange`, `instrumentType`, `activePick`, `articleTitle` | not returned (use `publicationTitle`, `author`, `direction`)     |
| —                                                                | `publicationTitle`, `prices` (`entry` / `current` / `returnPct`) |

4. **Pagination** — for ranges use `limitDays` + `cursor`; the response's
   `pagination.nextCursor` continues older. Previously impossible beyond one day.
5. **Errors** — keep treating `404` as "no picks, do not pay". New: `403` for an
   explicit out-of-window `date`, `429` for an exhausted API-key allowance.
6. **MCP** — prefer `quote_stock_picks_v2` / `list_stock_picks_v2`
   (`confirmSpend: true` on the paid path only). The V1 tools
   (`quote_stock_picks` / `list_stock_picks`) remain available.

## Hosted MCP

The four stock-picks tools map 1:1 to these routes:

| MCP tool               | HTTP route                      | Paid?                                                       |
| ---------------------- | ------------------------------- | ----------------------------------------------------------- |
| `quote_stock_picks_v2` | `GET /api/v2/stock-picks/quote` | Free, no auth                                               |
| `list_stock_picks_v2`  | `GET /api/v2/stock-picks`       | Subscribers free; x402 for FREE/anon (`confirmSpend: true`) |
| `quote_stock_picks`    | `GET /api/v1/stock-picks/quote` | Free, no auth                                               |
| `list_stock_picks`     | `GET /api/v1/stock-picks`       | Credits (`confirmSpend: true`)                              |

MCP defaults to V2 (`list_stock_picks_v2`). On the paid path, always call the
matching quote tool first, show `amountUsd` as `$X.XX`, confirm with the user,
then call with `confirmSpend: true`.