Payment methods are split by mount: the plain
/api/v2/... routes accept
Bearer API keys, session JWTs, and MCP OAuth only; the /api/v2/x402/...
twins accept wallet payments (x402 / MPP) only. Wrong-mount credentials get
403 account_only / 403 wallet_only.
GET /api/v2/stock-picks
Resolves the caller’s plan from the bearer credential first, then either serves
the request from the subscription window free of charge, serves the Free
tier’s delayed window free, or routes anonymous callers through the pay-per-use
flow.
Subscription access (Bearer API key, OAuth token, or session JWT)
- EXPERT readers get the full archive. PRO is clamped to a 90-day rolling window.
- In-plan requests are never charged and count against the API key’s monthly
request allowance — Personal 100,000/month, Enterprise 1,000,000/month
(
429when exhausted). - Plans also publish a per-minute request ceiling (Personal 60, Enterprise 600). It is on the pricing page but not enforced yet — do not rely on it.
- An explicit
dateoutside the plan window returns403; out-of-window ranges are clamped. A PRO range with no overlap returns403— readmeta.allowedRange/meta.appliedRange.
Callers without a plan
Rejected with403 subscription_required — there is no free tier. Subscribe,
or use the wallet mount for pay-per-use access.
Pay-per-use (anonymous)
No free API access without a credential. Call the free quote, confirm theamountUsd, then pay with
an x402 client or a bearer credential backed by Drip credits. Pricing is a
flat day rate per UTC day served; a from/to range costs the day rate ×
charged days (empty days are skipped, max 30 days per request). Freeze the
quote’s dateUsed for a single day and use the same limit on the paid
request; for a range, pass the same from/to. Author / direction / query
filters, pagination, and prices apply to subscription reads and are ignored on
the paid path.
Bundles are charged per request. A purchase does not create a lifetime post
unlock.
Query parameters
Response envelope
Three top-level keys, always present:meta.plan is FREE, PRO, EXPERT, or PAID (pay-per-use). meta.allowedRange
is the plan’s full window — null for EXPERT full history and for PAID requests.
meta.appliedRange is your request intersected with that window. meta.asOf is
the server timestamp. meta.requestAllowance is the plan’s monthly allowance
(Personal 100,000, Enterprise 1,000,000), null when paid.
Pick fields
assetResolutionStatus is RESOLVED, UNRESOLVED, or PENDING. asset carries
id, name, kind (EQUITY/ETF/CRYPTO), symbol, exchangeMic,
currency. A ticker alone can refer to different assets — key on assetId.
timeframe preserves the author’s wording; it is not normalized into a duration.
priceTarget applies to the returned instrument. It has kind (above, below,
or range), value, optional valueHigh for a range, and currency.
underlyingTarget has the same target fields plus label and unit
(price or percent), and applies to an underlying asset — for example, a gold
target attached to a gold-miner pick. Do not compare an underlyingTarget to the
instrument’s share price.
prices carries entry, current, returnPct, currency, with returnPct
adjusted for the author’s direction. Prices are omitted for the current day,
pay-per-use requests, includePrices=false, unresolved assets, and unavailable
or mismatched provider data.
Example — subscriber read (one day)
Example — range page (EXPERT, prices omitted for the current day)
Example — filtered read
author and query apply to subscription reads. They match the author exactly
and substring-match ticker, author, and publication title respectively.
Example — empty day
A valid day with no picks is a200, not an error. Do not pay on an empty
bundle.
Quote response
GET /api/v2/stock-picks/quote is free and returns no pick rows — it prices the
bundle at the flat day rate × charged days. dateUsed is the day that will
actually be charged on a single-day quote (null on multi-day quotes); freeze
it and reuse the same limit on the paid request.
404 means nothing to buy for that day — stop, do not pay. Prices are per
charged day; the bundle total is the sum of days[].amountUsd.
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.
Hosted MCP
list_stock_picks_v2 requires an API key or OAuth token with mcp:unlock;
anonymous wallet payments use HTTP instead. On the paid path, call the quote
tool first, show amountUsd as $X.XX, confirm with the user, then call
list_stock_picks_v2 with confirmSpend: true.
