> ## Documentation Index > Fetch the complete documentation index at: https://docs.dripstack.xyz/llms.txt > Use this file to discover all available pages before exploring further. # List stock-picker calls for one day (paid). > Returns structured stock-picker calls for AI-agent consumption. Covers one UTC effective calendar day, not a range. Defaults to latest day with picks. Use `date=YYYY-MM-DD` for a specific day or `period=latest` as an explicit alias. Do not send both. Rows without `publishedAt` may use extraction time internally. Returns 404 when no picks exist for the resolved day — do not pay on 404. ## OpenAPI ````yaml https://dripstack.xyz/openapi.json get /api/v1/stock-picks openapi: 3.1.0 info: title: Drip summary: Premium financial newsletter and podcast API with micropayment access. version: 0.1.0 description: > Paid API for searching and browsing Drip's premium financial newsletters and podcasts, resolving publications and direct post links, and purchasing synthesized post summaries for investing research and market analysis. ## Payment Flow Paid routes return HTTP 402 with a dual challenge. Use an x402 or MPP payment-aware client. 1. Plain request returns 402 with `WWW-Authenticate` (MPP) and `PAYMENT-REQUIRED` (x402) headers. 2. Retry the same request through a payment-aware client, or manually with `Authorization: Payment ` (MPP) or `PAYMENT-SIGNATURE` header (x402). 3. On success (200), response includes `synthesizedSummary` and `paymentInfo`. **Pricing:** Discovery `x-payment-info.offers[]` is advisory. Runtime 402 challenge is authoritative. Price may scale with content (e.g. stock-picks by source article count). **Error codes:** 402 = payment required, do not retry without payment. 503 = summary not ready, retry later. 404 = content not found, do not pay. contact: name: Drip email: support@dripstack.com url: https://dripstack.xyz license: name: Proprietary url: https://dripstack.xyz/terms x-guidance: > # Drip API Reference ## Discovery Prefer `GET /openapi.json` (OpenAPI 3.1) for route shapes, JSON schemas, and paid-route `x-payment-info.offers[]` metadata. If OpenAPI is unavailable, use `GET /.well-known/x402` for the paid resource list in `METHOD /path` form. Root `x-discovery.ownershipProofs` is a Drip vendor extension, not part of core MPP discovery. ## Routes ### `GET /api/v1/search` Searches imported premium financial newsletters and podcasts by topic. Use this as the default discovery route for topic browsing rather than loading the whole publication catalog. Query parameters: - `q` (required): natural-language search query - `limit` (optional): number of article results to return, from 1-30; use `10` by default - `mode` (optional): `hybrid` by default; `fts` is lexical only Response includes `items[]`, ranked post candidates with `publicationSlug`, `slug`, `title`, `subtitle`, `publishedAt`, `snippet`, `whyMatched`, and relevance fields. Use `publicationSlug` + `slug` from a selected item to fetch the paid article or podcast post. For user-facing search options, render `{title} ({publicationSlug}, {YYYY-MM-DD})` when `publishedAt` is present, or `{title} ({publicationSlug})` when no date is available. Convert ISO timestamps to date-only `YYYY-MM-DD`. Do not show `slug`, `subtitle`, `snippet`, `whyMatched`, relevance scores, or other internal metadata in user-facing menus. Treat search results as candidates, not evidence; answer substantive questions only from fetched paid summaries. ### `GET /api/v1/publications` Lists every indexed newsletter, podcast, and publication with `slug`, `title`, `description`, `siteUrl`, and `lastSyncedAt`. Use this only when the user explicitly wants to browse the full catalog or asks what publications are available. ### `GET /api/v1/publications/search` Searches indexed publications by slug, title, author, podcast show, newsletter, or site URL. Required query parameter: `q` (minimum 2 characters). Returns up to 3 matches with `publicationSlug`, `title`, `author`, and `siteUrl`. ### `GET /api/v1/publications/{publicationSlug}` Returns publication metadata plus `posts`: post summaries with `slug`, `title`, `subtitle`, `publishedAt`, and `priceCents`. Returns `404` if the publication is not in the database. Optional post-list query parameter: `limit` (1-100). ### `GET /api/v1/publications/{publicationSlug}/{postSlug}` (paid) Returns post metadata and `synthesizedSummary` after payment. Returns `404` if the publication or post is not found, `503` with code `summary_not_ready` when the summary is not ready yet (retry later; no payment challenge), and `402` if payment is required. Unpaid responses include a dual payment challenge: MPP in `WWW-Authenticate: Payment ...` and x402 v2 in `PAYMENT-REQUIRED`. Retry the same request with `Authorization: Payment ...` for MPP or `PAYMENT-SIGNATURE` for x402 v2. ### `GET /api/v1/stock-picks` Returns stock-picker calls for AI-agent consumption after x402/MPP payment. This is a specialized paid route for ticker-level picks, analyst calls, recommendations, and investment ideas; it is not part of the normal newsletter/podcast search, selection, and paid-summary workflow. This endpoint always returns one effective UTC calendar day, not a rolling date range. By default, it returns the latest day that has stock picks. Pass `date=YYYY-MM-DD` to request one effective UTC day. Optional `period=latest` is an explicit alias for the default. Do not send `date` and `period` together. Optional `limit` is 1-500 and defaults to 200. The effective day is based on article `publishedAt`; when publication time is missing, the server may use extraction time internally. Returned items do not include extraction time, so treat `publishedAt` as source article context only and omit date context when it is null. Response includes `dateUsed`, `startDate`, `endDate`, `asOf`, `count`, and `items[]`. `dateUsed` is the canonical returned day; `startDate` and `endDate` are the same as `dateUsed` for this single-day response. Each item includes `ticker`, `tickerExchange`, `instrumentType`, `action`, `direction`, `authorConviction`, `convictionLabel`, `activePick`, `evidenceQuote`, `rationaleSnippet`, `articleTitle`, `articleUrl`, `author`, `publishedAt`, `publicationSlug`, and `postSlug`. Returns `404` when no stock picks exist for the requested or resolved day — do not pay on `404`. Plain requests return `402` only when matching paid picks exist. Runtime price is based on the number of distinct attributed source articles in the returned picks. After settlement, the server records a sale for each distinct attributed source article. ## Payment Paid post routes return HTTP `402` with a dual challenge: MPP in `WWW-Authenticate: Payment ...` and x402 v2 in `PAYMENT-REQUIRED`. Use an x402 or MPP payment-aware client. If plain HTTP returns `402`, retry the same request through the payment-aware client instead of treating it as a final failure. Infer the live price from the paid endpoint response or payment challenge. OpenAPI `x-payment-info.offers[]` is advisory and may show Base USDC x402, Tempo, and Stripe charges or catalog floor prices; per-post pricing comes from the runtime challenge. Always trust the live `402` challenge over discovery offers. ## Agent flows ### Topic search Use when the user asks a general finance question, asks what writers or podcasts are saying, or wants article/podcast post recommendations. 1. Call `GET /api/v1/search?q={query}&limit=10`. 2. Present returned `items[]` as candidates using only title, publication slug, and date. 3. Keep each candidate's `publicationSlug` and `slug` for the paid fetch URL. 4. Fetch selected article summaries with `GET /api/v1/publications/{publicationSlug}/{postSlug}` through a payment-aware client. 5. Summarize or synthesize only from fetched `synthesizedSummary` text. ### Specific publication Use when the user names a publication, author, podcast show, newsletter, or shares a Substack publication URL. 1. Call `GET /api/v1/publications/search?q={query}` unless the normalized slug is obvious. 2. If one match is clearly right, call `GET /api/v1/publications/{publicationSlug}`. 3. Present 3-5 recent post titles from `posts[]`. 4. Fetch selected post summaries through the paid post route. ### Browse catalog Use when the user asks to see available newsletters, podcasts, or publications before choosing one. 1. Call `GET /api/v1/publications`. 2. Present publications as `Publication Title (slug) — short description`. 3. After the user chooses a publication, call `GET /api/v1/publications/{publicationSlug}`. 4. Fetch selected post bodies through the paid post route. ### Stock picks Use when the user asks for stock-picker calls, stock recommendations, recent investment picks, analyst calls, or ticker-level long/short ideas. 1. Call `GET /api/v1/stock-picks` through an x402 or MPP payment-aware client for the latest UTC effective day with picks. Read `dateUsed` and `asOf` from the response. 2. Call `GET /api/v1/stock-picks?date={YYYY-MM-DD}` when the user asks for a specific day. 3. Use `period=latest` only when an explicit latest-period parameter is useful; it is equivalent to omitting `date`. 4. If the response is `404`, no picks exist for that day — do not pay; try another date or tell the user none are available. 5. Present picks with ticker, action, direction, conviction, active/inactive status, evidence quote, rationale snippet, article title, source publication, and source URL. 6. Treat `publishedAt` as the article publication time; if it is null, omit date context rather than inventing one. 7. Keep `publicationSlug` and `postSlug` for optional follow-up paid article-summary fetches. ### Direct article Use when the user shares a direct article URL, podcast post URL, or a specific post slug. 1. Resolve `publicationSlug` and `postSlug` from the URL or context. 2. Probe the paid endpoint first when needed to inspect the live `402` challenge and price. 3. Call `GET /api/v1/publications/{publicationSlug}/{postSlug}` through a payment-aware client after the user has clearly asked to read, buy, summarize, or use that post. 4. Return a curated summary by default; include raw/full content only when explicitly requested. ## Fetched article response handling For one fetched article, return a curated summary with synthesis, notable claims, caveats, implications, and source context. For multiple fetched articles, compare the relevant claims, tensions, mechanisms, caveats, and implications across sources. Append source references for fetched articles with title, publication, date when available, and source URL when available. If a paid fetch fails, surface the failure rather than substituting model knowledge. If some selected articles succeed and others fail, synthesize only from successfully fetched articles and name the failed fetches. Runtime pricing note: paid post challenges use the stored per-post USD price when present, else at least $0.1. servers: - url: https://dripstack.xyz security: [] tags: - name: Search description: Search premium newsletters and podcasts by topic. - name: Publications description: List, search, and import newsletters, podcasts, and publications. - name: Posts description: Fetch, unlock, and list individual article and podcast post content. - name: Stock Picks description: Daily stock-picker calls, analyst recommendations, and investment ideas. paths: /api/v1/stock-picks: get: tags: - Stock Picks summary: List stock-picker calls for one day (paid). description: >- Returns structured stock-picker calls for AI-agent consumption. Covers one UTC effective calendar day, not a range. Defaults to latest day with picks. Use `date=YYYY-MM-DD` for a specific day or `period=latest` as an explicit alias. Do not send both. Rows without `publishedAt` may use extraction time internally. Returns 404 when no picks exist for the resolved day — do not pay on 404. operationId: listStockPicks parameters: - name: Authorization in: header required: false schema: type: string description: >- MPP (Payment HTTP Authentication Scheme): after HTTP 402, retry with `Authorization: Payment `. - name: PAYMENT-SIGNATURE in: header required: false schema: type: string description: >- x402 v2: after HTTP 402, retry with the encoded payment payload from the `PAYMENT-REQUIRED` challenge (same header name as in `@x402/core` HTTP transport). - name: date in: query required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- UTC effective calendar day to return. Mutually exclusive with `period`. When omitted, the server resolves the latest day with picks. - name: period in: query required: false schema: type: string enum: - latest description: >- When `latest`, same as omitting `date` (latest effective day with picks). Mutually exclusive with `date`. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 200 description: >- Maximum number of stock-pick calls returned (1-500). Defaults to 200. responses: '200': description: Stock-picker calls after successful payment. content: application/json: schema: $ref: '#/components/schemas/PublicStockPicksResponse' '400': description: Invalid query params. content: application/json: schema: $ref: '#/components/schemas/PublicStockPicksInvalidQueryResponse' '402': description: Payment Required headers: WWW-Authenticate: description: >- MPP `Payment` HTTP Authentication Scheme challenge (realm must match origin). schema: type: string PAYMENT-REQUIRED: description: x402 v2 encoded payment requirements (see x402 seller docs). schema: type: string content: application/problem+json: schema: type: object required: - type - title - status - detail properties: type: type: string description: Problem type URI. title: type: string description: Short human-readable summary. status: type: integer enum: - 402 description: HTTP status code. detail: type: string description: Human-readable explanation of the payment requirement. challengeId: type: string description: Unique challenge id for payment correlation. '404': description: No stock picks for the requested or resolved day. content: application/json: schema: $ref: '#/components/schemas/PublicStockPicksNotFoundResponse' '500': description: Stock picks failed. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: schemas: PublicStockPicksResponse: type: object additionalProperties: false required: - dateUsed - startDate - endDate - asOf - count - items properties: dateUsed: type: string description: >- Single UTC effective calendar day returned (`publishedAt`, or extraction time internally when publication time is missing). startDate: type: string description: Same as `dateUsed` for single-day responses. endDate: type: string description: Same as `dateUsed` for single-day responses. asOf: type: string description: Server timestamp when the response was generated. count: type: integer minimum: 0 description: Number of stock-pick items returned. items: type: array description: Stock-picker calls for the resolved single day. items: $ref: '#/components/schemas/PublicStockPickItem' example: dateUsed: '2026-06-14' startDate: '2026-06-14' endDate: '2026-06-14' asOf: '2026-06-15T10:30:00Z' count: 2 items: - id: sp_abc123 callId: call_def456 author: Luke Gromen articleTitle: The Dollar Endgame articleUrl: https://thefr.substack.com/p/dollar-endgame publishedAt: '2026-06-14T09:00:00Z' ticker: GLD tickerExchange: NYSE instrumentType: ETF action: NEW_POSITION direction: LONG authorConviction: 4 convictionLabel: High activePick: true evidenceQuote: >- Gold remains the only asset that balances sovereign balance sheet risk. rationaleSnippet: >- Rising fiscal deficits and de-dollarization trends support gold allocation. publicationSlug: the-fr postSlug: dollar-endgame PublicStockPicksInvalidQueryResponse: type: object required: - error - issues properties: error: type: string description: Human-readable error message. issues: type: object description: Field-level validation errors keyed by parameter name. PublicStockPicksNotFoundResponse: type: object additionalProperties: false required: - error properties: error: type: string description: Human-readable error message (e.g. no picks for the requested day). ErrorMessage: type: object additionalProperties: false required: - error properties: error: type: string description: Human-readable error message. PublicStockPickItem: type: object additionalProperties: false required: - id - callId - author - articleTitle - articleUrl - publishedAt - ticker - tickerExchange - instrumentType - action - direction - authorConviction - convictionLabel - activePick - evidenceQuote - rationaleSnippet - publicationSlug - postSlug properties: id: type: string description: Public stock-pick row id. callId: type: string description: Stable extraction call id for this pick. author: type: string description: Author or analyst attributed to the pick. articleTitle: type: string description: Source article title. articleUrl: type: string description: Source article URL. publishedAt: type: - string - 'null' description: >- Source article publication timestamp when available. If null, omit date context in user-facing output. ticker: type: string description: Ticker or symbol mentioned by the pick. tickerExchange: type: - string - 'null' description: Exchange when known, such as NASDAQ or NYSE. instrumentType: type: string enum: - EQUITY - ETF - OPTION - OTHER description: Type of instrument discussed by the pick. action: type: string enum: - NEW_POSITION - ADD - HOLD - RECOMMENDATION - REDUCE - EXIT description: Author's action or recommendation type. direction: type: string enum: - LONG - SHORT description: Directional exposure implied by the pick. authorConviction: type: integer minimum: 0 maximum: 5 description: Normalized conviction score from 0-5. convictionLabel: type: string description: Human-readable conviction label. activePick: type: boolean description: Whether the source still frames this as an active pick. evidenceQuote: type: string description: Short quote supporting the extracted pick. rationaleSnippet: type: - string - 'null' description: Short rationale summary when available. publicationSlug: type: - string - 'null' description: Source publication slug for optional follow-up article fetches. postSlug: type: - string - 'null' description: Source post slug for optional follow-up article fetches. ````