# DripStack

> Agent-first API for discovering publications, importing Substack feeds, and fetching post summaries with wallet-based payment. Start with the OpenAPI document, search by topic or browse publications, then request paid content when needed.

- App: `https://dripstack.com`
- OpenAPI: `https://dripstack.com/openapi.json`
- Hosted MCP: `https://dripstack.com/api/mcp`
- Onboarding skill: `https://dripstack.com/SKILL.md`
- Agentic market listing: https://agentic.market

## What this site does

- Searches imported articles by topic
- Lists curated publications
- Fetches one publication and its post summaries
- Imports a publication from its normalized host
- Returns synthesized post summaries (`synthesizedSummary`) from a paid endpoint
- Returns stock-picker calls from a paid endpoint (V2 preferred — `/api/v2/stock-picks`; V1 still available)
- Exposes the same discovery + unlock flow over Streamable HTTP MCP

## Payment

- Paid routes use **USDC x402** on Base or Solana (`exact` scheme). After HTTP `402`, retry with `PAYMENT-SIGNATURE` (x402 v2) or `Authorization: Payment ...` (MPP).
- Default access floor is `1 USD` unless a post-specific price overrides it; stock-picks charge `0.5 USD` per distinct source article (see `/stock-picks/quote`).
- OpenAPI advertises advisory `x-payment-info.offers[]` (Base/Solana USDC x402, Tempo, Stripe); the live `402` challenge is authoritative.
- Plain `curl` is fine for free routes; paid routes require a payment-aware client (e.g. agentic wallet).
- Prefer OAuth for Hosted MCP paid tools (Cursor Connect / `codex mcp login` / host OAuth). Discovery stays public on `/api/mcp` (no transport 401) — probe `/.well-known/oauth-protected-resource` → AS `/api/oauth` (or run host login after adding the MCP URL). CLI / `mcp-remote` can keep `Authorization: Bearer pk_drip_…` (API key from the dashboard). JWT sessions are not accepted for paid MCP tools.

## Endpoints

- `GET /api/v1/search`: Search imported posts by topic (`q, optional limit (1-30), mode`); Default discovery route for topic questions
- `GET /api/v1/companies`: Look up a company profile by ticker, domain, qid, CIK, or name (`ticker, domain, qid, cik, or name; optional limit (1-10)`); Identity lookup, not article search; multiple identifiers are AND (qid > ticker > domain > cik > name); empty match returns items: []
- `GET /api/v1/companies/{companyId}`: Get one company profile by id; Returns 404 if unknown or not a company
- `GET /api/v1/publications`: List curated publications
- `GET /api/v1/publications/search`: Search curated publications by name, author, slug, or site URL; Returns up to 3 matches
- `GET /api/v1/publications/{publicationSlug}`: Get publication metadata and post summaries with priceCents (`optional limit (1-100)`); Works for any indexed slug; returns 404 if not in database
- `GET /api/v1/publications/top-selling`: List highest-earning publications (`optional limit (1-100)`); Ranked by creator earnings; use only when browsing popular publications
- `GET /api/v1/posts/top-selling`: List most purchased posts (`optional limit (1-100)`); Free post cards; unlock via the paid publication-post route
- `GET /api/v1/podcasts`: List curated podcasts
- `GET /api/v1/podcasts/{publicationSlug}`: Get podcast metadata and episode summaries with priceCents (`optional limit (1-100)`); Returns 404 if the slug is not a podcast
- `GET /api/v1/publications/{publicationSlug}/{postSlug}`: Get one synthesized post summary (synthesizedSummary); paid route; Returns 503 summary_not_ready until ready
- `GET /api/v1/stock-picks/quote`: Quote stock-picks bundle amountUsd for one UTC day (`optional date (YYYY-MM-DD), optional limit (1-500)`); V1 (legacy — still available). Free preflight before paid stock-picks; returns 404 when none for that day. New integrations: use /api/v2/stock-picks/quote
- `GET /api/v1/stock-picks`: Get stock-picker calls (`optional date (YYYY-MM-DD), optional limit (1-500)`); paid route; V1 (legacy — still available). Defaults to latest UTC effective day with picks; returns 404 when none for that day. New integrations: use /api/v2/stock-picks
- `GET /api/v2/stock-picks/quote`: Quote stock-picks bundle amountUsd for one UTC day (V2, free) (`optional date (YYYY-MM-DD), optional limit (1-500)`); V2 — recommended. Free preflight, no auth; same price logic as V1 quote. Returns 404 when none for that day
- `GET /api/v2/stock-picks`: Get stock-picker calls (V2 — preferred over V1) (`date, or from/to range; optional limit, limitDays, cursor, author, direction, query, sort, includePrices`); paid route; V2 — recommended. Bearer PRO/EXPERT are served within their plan window and never charged; anonymous/FREE pay per use via x402 (same bundle pricing as V1). V1 stays available for existing integrations
- `GET /api/v1/me`: Auth introspection for the current API key or OAuth token; Requires bearer pk_drip_… or mcp_at_… with mcp:unlock; rejects session JWT
- `GET /api/v1/me/credits`: Purchased credit balance plus topUpUrl / dashboardUrl; Requires bearer pk_drip_… or mcp_at_… with mcp:unlock; rejects session JWT
- `GET /api/v1/me/credits/activity`: Cursor-paginated credit ledger activity (`optional limit (1-50), optional cursor`); Requires bearer pk_drip_… or mcp_at_… with mcp:unlock; rejects session JWT
- `GET /api/v1/me/unlocks`: Cursor-paginated posts unlocked for lifetime access (`optional limit (1-50), optional cursor`); Requires bearer pk_drip_… or mcp_at_… with mcp:unlock; rejects session JWT
- MCP `https://dripstack.com/api/mcp`: tools `search_posts`, `search_entities`, `search_companies`, `get_company`, `list_publications`, `search_publications`, `get_publication`, `list_podcasts`, `get_podcast`, `list_top_selling_posts`, `list_top_selling_publications`, `quote_stock_picks` / `quote_stock_picks_v2` (free), `get_account` / `get_credits_balance` / `list_credit_activity` / `list_unlocked_posts` (OAuth or API key), `unlock_post`, `list_stock_picks` / `list_stock_picks_v2` (OAuth or API key + purchased credits; V1 still available, prefer V2); prompts `research-topic`, `browse-publication`, `list-stock-picks`; resources `drip://docs/api`, `drip://publications`, `drip://publications/{slug}` (no paid post bodies). PRM: `https://dripstack.com/.well-known/oauth-protected-resource`; AS: `https://dripstack.com/api/oauth`

## Publication slugs

- Publication slugs are normalized hosts
- Example: `https://bytesbeyondborders.substack.com` -> `bytesbeyondborders.substack.com`
- For custom domains, remove leading `www.`

## Recommended agent flow

### Topic search (default)

1. Read `https://dripstack.com/openapi.json` (see `info.x-guidance` for full flows)
2. Call `GET /api/v1/search?q={query}&limit=10`
3. Present `items[]` as candidates; keep each item's `publicationSlug` and `slug`
4. Call `GET /api/v1/publications/{publicationSlug}/{postSlug}` with a payment-aware client for selected posts
5. If `503 summary_not_ready`, retry later; if `402`, pay via x402 and retry with `PAYMENT-SIGNATURE`

### Specific publication

1. Call `GET /api/v1/publications/{publicationSlug}`
2. Read `posts[]`, choose a `post.slug`
3. Call the paid post route with a payment-aware client

## Practical notes

- Prefer the OpenAPI document before guessing request or response shapes
- Use publication and post slugs exactly as returned by the API
- Summarize only from fetched `synthesizedSummary` text, not from search snippets alone

## Examples

- `https://dripstack.com/api/v1/search?q=stablecoins&limit=10`
- `https://dripstack.com/api/v1/publications`
- `https://dripstack.com/api/v1/publications/bytesbeyondborders.substack.com`
- `https://dripstack.com/api/v1/publications/bytesbeyondborders.substack.com/some-post-slug`
- `https://dripstack.com/api/v2/stock-picks/quote?date=2026-08-26` (free price preview — V2)
- `https://dripstack.com/api/v2/stock-picks?date=2026-08-26` (V2 — subscription bearer or pay-per-use)