Skip to main content
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 for those integrations. Other documented API routes continue to use /api/v1.

​
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 clamped to the allowed window. A PRO range with no overlap returns 403 — read meta.allowedRange / meta.appliedRange.

​
Pay-per-use (anonymous or FREE)

No free API access. Call the free quote, confirm the amountUsd, then pay with an x402 client or a bearer credential backed by Drip credits. Freeze the quote’s dateUsed and use the same limit on the paid request. The paid path selects one day using date / limit; sort orders that day’s rows. Ranges, author / direction / query filters, pagination, and prices apply to subscription reads and are ignored on the paid path. Stock-pick bundles are charged per request. A purchase does not create a lifetime post unlock.

​
V2 query parameters

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, tickerExchange, instrumentType, assetId, assetResolutionStatus, and asset. assetResolutionStatus is RESOLVED, UNRESOLVED, or PENDING. Use assetId and asset (id, name, kind, symbol, exchangeMic, currency) for identity; a ticker alone can refer to different assets. asset and assetId are null until resolved. instrumentType is the legacy extraction type; asset.kind identifies resolved equities, ETFs, or crypto. Historical subscription reads may also include prices (entry, current, returnPct, currency). Returns are direction-adjusted. Prices are omitted for the current day, pay-per-use requests, includePrices=false, unresolved assets, and unavailable or mismatched provider data. A successful subscription query can return picks: []. On the paid path, no matching picks returns 404. Free quote responses include dateUsed, startDate, endDate, asOf, count, attributedPostCount, amountUsd, and posts[] containing publicationSlug and per-source amountUsd; quotes do not expose post slugs or pick rows. V2 errors: 400 invalid query, 401 bad bearer, 402 payment required, 403 outside the plan window or insufficient credits, 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.
Response: dateUsed, startDate, endDate, asOf, count, and items[] with ticker, tickerExchange, instrumentType, action, direction, authorConviction, convictionLabel, activePick, evidenceQuote, rationaleSnippet, articleTitle, articleUrl, author, publishedAt, publicationSlug, postSlug, assetId, assetResolutionStatus, and asset.

​
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:
  1. Pagination — for ranges use limitDays + cursor; the response’s pagination.nextCursor continues older. Previously impossible beyond one day.
  2. 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.
  3. 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: Use V2 explicitly (list_stock_picks_v2). Both list tools require an API key or OAuth token with mcp:unlock; anonymous wallet payments use HTTP instead. 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.