side is buy/sell on a fund and
long/short on a source, and kind and ruling list their values per kind
in Trades. A parser reads the keys once and branches on kind.
A track record is not a forecast. Every number here is computed from what was
published or filed; none of it is a recommendation.
Two kinds, one vocabulary
kind says which one you are reading: "13f" or "media".
{slug} for a fund is a bare CIK (1067983) or a name slug whose trailing
digits are the CIK (berkshire-hathaway-1067983). A source slug is the
normalized host (bytesbeyondborders.substack.com).
The four endpoints
Every path below exists twice: on the account mount (plan required) and on the wallet mount under/api/v2/x402/… ($0.10 per call).
Access. The account mount requires a PRO or EXPERT plan. There is no free
tier and no partial response: no credential, a rejected credential, or a
credential without a plan is
401 and returns no data. The wallet mount charges
$0.10 per call — never per page — and needs no plan: a paying wallet reads
the full response, one payment one call. Account credentials on the wallet mount
are 403 wallet_only; a plain request is 402 with the dual x402 / MPP
challenge.
Units. Every return is a fraction: 0.0521 is 5.21%. Every date is
YYYY-MM-DD. Nothing ends in Pct. The only dollars in any response are a 13F
filing’s as-filed valueUsd — never P&L, peak capital or an account return.
How the numbers are built is in the
methodology.
MCP tools
The same five surfaces are on the hosted MCP server (/api/mcp), plan-gated like
the account mount. Each returns exactly the JSON its HTTP twin returns — same
read model, not a second query:
Every tool takes one
profile argument: a bare CIK (1067983), a fund slug
whose trailing digits are the CIK (berkshire-hathaway-1067983), or a source
slug (bytesbeyondborders.substack.com). search_profiles is the discovery
entry point — it returns { kind, id, name, cik | sourceSlug } for both kinds.
Funds keep their REST list at GET /api/v2/funds; search_sources and
list_sources still return sources only, unchanged.
Picks versus trades
A pick is the raw record: what the analyst said, or what the filing changed. A trade is our reading of it — the $1 lot the call becomes, filled on a real session, held until it is closed or its horizon runs out, and marked at the latest close while it is still open. Each call opens its own lot: a repeated recommendation adds a new $1 lot instead of merging into the open one, so modeled exposure is one lot per call, not the analyst’s sizing. That distinction explains the two endpoints:/picksreturns the mentions or the filing diffs, grouped by ticker, newest first. Nothing is priced; nothing is derived./tradesreturns the legs with their fills, the trade each one opened, itsreturn, SPY’sspyReturnover the same window, and thedifference. EverypickIdon a trade event exists in/picks— see Trades for the one case where it isnull.
profile.holdings) are the chosen quarter’s book, not
trades. A media profile’s holdings are the lots still open today, with the
analyst’s own horizon as expires — null when their words do not bucket
confidently, rather than a guessed default.
The fill rule
A call fills at the first close a reader could actually act on: the post day’s own close when the post landed in time for a market-on-close order, otherwise the next session’s close. A 13F change fills at the first session after the filing date — and a filing can land up to 45 days after quarter end, so a fund’s trades carry a real reporting lag the price series already reflects.Ranges select, and the benchmark windows
from and to choose which rows come back, and never re-derive anything:
- Trades are always derived over the whole history, so an add inside the range never reads as a new open.
- On
/benchmarkthe range windows the daily series: it runs from the close beforefromto the close onto.twr,spyTwr,difference, drawdowns, risk andgrowthare rechained from exactly those sessions — a trade already open at the start comes in at that close, and back-to-back ranges chain to the combined range.periodsare the rows overlapping the range, andbeat/comparedare counted over those rows.benchmark.from/benchmark.toecho the request. - On
/picksand/tradesthe range only selects which rows come back.
limit is capped at 100 for paged reads, with total beside it. Page size is
never a price: one call is one charge.
opinions=include|exclude (media)
Every mention carries a sentiment, and some mentions are views that make no
trade. opinions=exclude is the site’s “Direct trades only” toggle: own
trades and explicit calls to trade, dropping the views. The default is
include. It is available on /profile, /picks, /trades and /benchmark;
on the benchmark it rescores the record without the opinion-only calls.
Stock picks returns the same stats
GET /api/v2/sources/{sourceSlug}/stock-picks (and its
/api/v2/publications/{slug}/stock-picks predecessor) still answers, and its
stats are now the shared engine summary — the same trades,
avgReturnPerTrade, winRate, winRateClosed and unpricedCalls as
/profile. There is one win rate definition and no Pct field anywhere; the
legacy extras block was removed.
Profile
GET /api/v2/funds/{slug} and GET /api/v2/sources/{sourceSlug}/profile.
quarter picks the holdings quarter (YYYY-MM-DD), defaulting to the latest. A
media profile answers with kind: "media", a profile block carrying the
record’s from/to span and its posts / picks / opinions counts, and
holdings as open lots. The media route also takes opinions (default
include): with opinions=exclude the stats, the holdings and the assets
summary all come from the explicit-only record, so the open lots match
/trades?opinions=exclude&status=open.
lotId (stable across re-derivations), the pickId
that opened it, and the prices behind return: entryPrice at the fill and
markPrice at the latest close (markDate). Returns are fractions and
reproduce exactly — return = (markPrice − entryPrice) / entryPrice for a long,
flipped for a short. markPrice: null means no mark, so return is null too.
Two same-day lots are two rows, distinguished by lotId.
Picks
GET /api/v2/funds/{slug}/picks and
GET /api/v2/sources/{sourceSlug}/picks.
Query: from, to, ticker, limit (1-100), offset — plus opinions on
the media route. total counts every matching pick before paging.
/trades with its ruling
and is never dressed up as a pick.
Trades
GET /api/v2/funds/{slug}/trades and
GET /api/v2/sources/{sourceSlug}/trades (the media twin — same params plus
opinions, same shape). Query: from, to, ticker, status (open,
closed, all), limit (1-100), offset.
status filters on the asset’s standing — still held at the latest quarter,
or exited — because the engine scores no per-lot exit.
ruling says what the leg’s scoring fate was: counted, unpriced,
held_out (a book move inside a detected fund group, not a trade), or
not_reported (a quarter that asserted nothing new).
Media trades
GET /api/v2/sources/{sourceSlug}/trades — the same engine, opened up: every
event it ruled for the publication, with the $1 lot each opening call became.
Query: from, to, ticker, status (open/closed/all, the asset’s
standing), opinions (include/exclude), limit (1-100), offset. total
counts events.
kindis the engine’s event:open,add,restart,keep,close,trim,flip,expire, plus the two that never traded —no-trade(the rules ruled the call out) andno-price(no session to fill on).rulingis that reading in one word:counted,unpriced, orno_trade. Nothing is dropped — an unpriced call keeps its event withtrade: null.tradeis the lot the event opened, withstatus(open,closed, orpartly open— aREDUCEcloses half) andpieces: each closed slice’sfraction,date,price,reasonandreturn, plus the still-open remainder as a piece withopen: trueat the latest mark. A close, a keep or an expiry hastrade: null— closing is not opening.pickIdis the/picksrow behind the event, and every non-nullpickIdin/tradesis a/picksid, always. An explicit exit call has no pick row — it ends an episode rather than stating a view — so its event carriespickId: nullrather than pointing at an id/picksnever returns.pricingStatusappears only on anunpricedevent:pendingwhile the background filler can still resolve the fill,unresolvablewhen the instrument never prices.
Benchmark
GET /api/v2/funds/{slug}/benchmark and
GET /api/v2/sources/{sourceSlug}/benchmark. Query: from, to.
The score is time-weighted: the profile’s daily series against SPY bought
once at the profile’s start and held over the same days. difference is the
copy-trade answer.
riskStatusis the risk maturity band:insufficientunder 6 months,provisionalto 35,standardat 36+.monthsis the month count behind it.sharpeandvolatilityscore the profile’s own daily line;spySharpeandspyVolatilityare SPY’s, computed the same way over the same days.growthis the trailing-3-month chart as levels rebased to1at the window start, not percentages.investedShareis the share of scored sessions with capital deployed — a record that is flat between trades reads below1even when its TWR is positive.- Each period row carries
priced(the share of the window’s trades the engine could price,1when it covered none) andpartial: coverage below complete. A 13F window is partial when some of its trades could not be priced; a media month is partial when it mixes trades already closed with ones still open. - 13F periods are filing-to-filing windows; media periods are calendar months.
Coverage honesty
The pipeline resolves prices in the background, so a record is only as complete as its priced legs, and the API says so instead of dropping the gap:stats.unpricedCalls— trades that never resolved a price. Counted, never scored as 0%.rulingon a trade event —unpriced,held_out,not_reported, orcounted.pricingStatuson an unpriced trade event —pending(the background filler may still resolve it) orunresolvable(it never will).computedAton/profileand/trades— when that derivation ran. Pricing resolves between reads, so anunpricedevent can becomecountedlater; comparecomputedAtwhen two responses disagree.- A 13F profile’s holdings only cover the quarter asked for; the picked quarter
is always echoed back as
holdings.quarter.
Per analyst
The unit today is a source profile. An analyst who publishes in two places is two profiles — there is no cross-source analyst view endpoint, and the two records are not merged. To find a writer, search the curated catalog by name:sourceSlug.
Feed that slug into GET /api/v2/sources/{sourceSlug}/profile. A non-curated
source still answers on its own slug if you already know it, it just will not
appear in search.

