API reference
Two ways to consume every feed: a WebSocket stream for realtime delivery, and a REST
endpoint for recent history. One consistent JSON schema across both. Base URL:
https://feeds.247terminal.com
Quickstart
Three steps from zero to a live stream.
1. Get a key
Subscribe to one or more feeds, then generate an API key in your dashboard. The key is shown once - store it somewhere safe.
2. Make your first request
curl "https://feeds.247terminal.com/v1/feeds/general-feed/items?limit=5" \
-H "Authorization: Bearer $KEY"
Not sure which feeds your key covers? Open a WebSocket - the
hello message lists them.
3. Run the reference client
A reference client is available to download. It discovers your entitled feeds, pulls recent history, streams live events, and backfills any gap on reconnect. Node 18+.
curl -O https://feeds.247terminal.com/examples/feed-client.mjs
npm install ws
FEEDS_KEY=nf_xxxxxxxx node feed-client.mjs
entitled: truth-social, fomc, macro-data, earnings-reports, major-news-publications, social, markets, general-feed
subscribed: general-feed
HIST 2026-08-24 12:30:19 [earnings-reports,general-feed] PR Newswire
BITMINE IMMERSION TECHNOLOGIES (BMNR) ANNOUNCES ETH HOLDINGS REACH 5.85 MILLION TOKENS
https://www.prnewswire.com/news-releases/bitmine-immersion-...
LIVE 2026-08-25 09:31:06 [major-news-publications] Wall Street Journal
COINBASE IN ADVANCED TALKS TO ACQUIRE DERIBIT
https://www.wsj.com/finance/coinbase-deribit-talks Authentication
All feed access uses an API key. Generate one in your dashboard (1 active key on Trader, up to 10 on Enterprise; to rotate a Trader key, revoke it and create a new one). Keys are shown once - store them securely. A key streams and backfills every feed your account is subscribed to.
Authorization: Bearer nf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
For WebSocket, pass the key in the Authorization header, or
as a ?key= query parameter when a header isn't available.
Delivery
Every feed is delivered in real time, with no artificial delay - the same instant on the WebSocket stream and in REST history. Typical end-to-end latency is under 300 ms from the moment an item is ingested.
Latency targets are typical production observations, not guarantees - real delivery varies with the source, your network and load.
REST - recent history
Fetch recent items for a feed, newest first.
GET /v1/feeds/{feed}/items?limit=100
curl "https://feeds.247terminal.com/v1/feeds/major-news-publications/items?limit=100" \
-H "Authorization: Bearer $KEY" Query parameters
| Param | Type | Description |
|---|---|---|
| limit | int | 1-500, default 100 |
| since_id | int | Return items after this id, ascending. For reconnect backfill. |
| cursor | int | Return items before this id, descending. For paging older history. |
| format | string | json (default) or msgpack. Same as sending Accept: application/msgpack. See Binary. |
Response
next_cursor is the id to pass as
cursor for the next page of older items. It is
null when fewer items than limit
are returned - there is no more history.
{
"feed": "major-news-publications",
"items": [
{
"id": 48213,
"feeds": ["major-news-publications"],
"source": "news_outlets",
"source_name": "Wall Street Journal",
"link": "https://www.wsj.com/finance/coinbase-deribit-talks",
"headline": "COINBASE IN ADVANCED TALKS TO ACQUIRE DERIBIT",
"body": "COINBASE IN ADVANCED TALKS TO ACQUIRE DERIBIT",
"type": "news_update",
"category": "headlines",
"kind": "wsj",
"exclusive": true,
"relevance": "crypto",
"coins": [{"symbol": "COIN", "match_type": "keyword"}],
"time": 1753009999000,
"source_id": "https://www.wsj.com/finance/coinbase-deribit-talks"
}
],
"next_cursor": null,
"next_since_id": null
} WebSocket - realtime
Open one connection, subscribe to the feeds you want, and receive every item in real time as it is ingested.
wss://feeds.247terminal.com/v1/stream
wscat -c "wss://feeds.247terminal.com/v1/stream" \
-H "Authorization: Bearer $KEY"
# on connect the server sends:
{"type": "hello", "entitled": ["truth-social", "major-news-publications", "macro-data"], "tiers": {"truth-social": "realtime", "major-news-publications": "realtime", "macro-data": "realtime"}, "format": "json"}
# subscribe to a subset (or all) of your entitled feeds:
> {"subscribe": ["truth-social", "major-news-publications"]}
{"type": "subscribed", "feeds": ["truth-social", "major-news-publications"]}
# then events arrive as they happen - same shape as the REST items:
{"id": 48214, "feeds": ["truth-social"], "type": "truth_post",
"source": "truth_social", "source_name": "Truth Social",
"link": "https://truthsocial.com/@realDonaldTrump/117153498897353817",
"handle": "realDonaldTrump", "body": "...", "time": 1753009999500,
"source_id": "117153498897353817"} Message types
| Type | Meaning |
|---|---|
| hello | Sent on connect. Lists the feeds your key is entitled to and the active format (json or msgpack). |
| subscribed | Confirms your active subscriptions. |
| (event) | A feed item. Carries id, feeds, and the payload. |
| pong | Reply to a client-sent {"type": "ping"}. |
| error | Malformed message. |
The server sends a WebSocket ping every 5s and closes connections that have not answered
one (or sent a {"type": "ping"}) for 20s; most clients answer pings automatically. If your
client cannot see protocol pings (browsers, Python websockets),
send {"type": "ping"} every 5s and treat a missing
{"type": "pong"} within about 10s as a dead connection. Exceeding 1MB of unread buffer drops the connection as a slow consumer.
Gap-free reconnect
Every item - over WebSocket and REST - carries the same monotonic
id. To reconnect without gaps or duplicates, subscribe
before you backfill and page the REST backfill to completion:
// 1. reconnect, attach your message handler, send {"subscribe": [...]}
// 2. WAIT for the {"type":"subscribed"} ack, buffering every live event that arrives
// 3. backfill from the last id you processed, following next_since_id until it is null:
GET /v1/feeds/major-news-publications/items?since_id=48214&limit=500 // → next_since_id: 48714
GET /v1/feeds/major-news-publications/items?since_id=48714&limit=500 // → next_since_id: null (done)
// 4. process the backfill, then drain the live buffer, skipping any id already seen
Waiting for the subscribed ack guarantees no live event
is dropped during subscription setup; paging until next_since_id
is null covers outages longer than one page. Ids always increase but are not contiguous -
a jump in ids, for example after a server restart, does not mean you missed an item. On
Trader, a backfill reaches back at most 30 days.
Binary (MessagePack)
The stream and the feed items endpoint can also speak MessagePack
instead of JSON. The fields, ids and message types are identical - only the encoding
changes. It is standard MessagePack, readable by any msgpack library. Integers above
232, such as time, are sent as int64; with msgpackr in
JavaScript, decode with new Unpackr({ int64AsType: 'number', mapsAsObjects: true }) - the default
decoder returns them as BigInt.
# WebSocket: connect with ?format=msgpack - every frame (hello, subscribed, items) is binary.
# Commands may be sent as msgpack binary frames or JSON text frames.
wss://feeds.247terminal.com/v1/stream?format=msgpack
# REST: send Accept: application/msgpack (or add ?format=msgpack)
curl "https://feeds.247terminal.com/v1/feeds/fomc/items?limit=100" \
-H "Authorization: Bearer $KEY" -H "Accept: application/msgpack" --output items.msgpack # Python - pip install websockets msgpack
import asyncio, msgpack, websockets
async def main():
url = "wss://feeds.247terminal.com/v1/stream?format=msgpack"
async with websockets.connect(url, additional_headers={"Authorization": f"Bearer {KEY}"}) as ws:
async for frame in ws:
msg = msgpack.unpackb(frame)
if msg.get("type") == "hello":
await ws.send(msgpack.packb({"subscribe": msg["entitled"]}))
elif "id" in msg:
print(msg["id"], msg["headline"])
asyncio.run(main())
The hello message carries format so
you can confirm which encoding is active. Error responses (401, 403, 429) stay JSON. An
unknown format value closes the stream with code 4000 and returns
400 on REST.
Feeds & payloads
REST items and WebSocket events share one shape. These fields are on every item, on both transports:
| Field | Type | Description |
|---|---|---|
| id | int | Monotonic feed id. Use it for since_id and cursor. |
| feeds | string[] | Feeds this item belongs to. An item can be in more than one. |
| time | int | Epoch milliseconds, at detection. |
| source | string | Machine-readable origin bucket, e.g. news_outlets, cpi, truth_social. |
| source_name | string | Publisher name, ready to display - "Wall Street Journal", "Federal Reserve", "SEC EDGAR", "CNBC (@CNBC)". |
| link | string | Canonical URL at the source - the article, filing, release or post the item came from. |
| headline | string | Wire headline, uppercase. Empty string on media-only posts, where image / video carry the content. |
| body | string | Item text, uppercase. Multi-line for parsed releases. Mirrors headline when a source supplies only one of the two. |
| price_at_news | object | null | Enterprise only, REST. Price of each detected token at the moment of the news, keyed by symbol: {"BTC": {"price": 64244.9, "time": 1785330497568}}, where time is the trade's epoch ms. Filled asynchronously after the item is stored, one symbol at a time, and only for tokens with a liquid perpetual market. null means not priced yet or not priceable. Not sent on the WebSocket stream - re-read an item over REST a few minutes after it arrives to pick up its price. |
| source_id | string | The origin's own id. Stable across feeds - use it to dedupe an item that arrives on two feeds. |
| type | string | news_update, truth_post, direct, telegram, discord. Treat an unrecognized value as a generic item. |
| relevance | string | On press items that passed classification: why it qualified, e.g. crypto. Absent when the item was delivered on a detected token before classification. major-news-publications carries exclusives that are crypto related or name a tradable token; the filter is customizable per key on request. |
| category | string | null | Coarse grouping, independent of feed membership: macro, headlines, crypto, truth, or null. |
| coins | object[] | Suggested tradable coins, most-mentioned first: [{"symbol": "BTC", "match_type": "keyword"}]. match_type is keyword (name or alias in the text), explicit (written as $BTC or (BTC)) or implied (macro-economic releases such as CPI, NFP or FOMC that name no coin, defaulting to BTC and ETH). Empty when nothing was detected; absent on sources that skip detection, including Truth Social posts. |
Items carry extra fields depending on where they came from - exclusive,
handle, kind, catalog,
image, video.
Treat anything outside the table above as optional. title
and icon are display
helpers carried over from our own terminal - safe to ignore. For the publisher name,
always read source_name.
The feeds:
General Feed "general-feed"
Every market-moving event we cover, curated onto a single channel.
Truth Social "truth-social"
Alert on every new Donald Trump post on Truth Social: the raw post in full as structured data, followed by wire-style summary headlines.
Major News Publications "major-news-publications"
Scoops and exclusives from major publications, with the canonical link on every item. Filters are fully customizable. Current live rule: exclusives that are crypto related or name a tradable token. Filters can be changed independently by publication, topic, keyword, token, asset, author, geography, event or exclusion.
Economic Data "macro-data"
US economic releases parsed into numbers at publication, against consensus.
Earnings Reports "earnings-reports"
Earnings results parsed from the EDGAR filing the moment it lands, against consensus, for AAPL, AMZN, GOOGL, MSFT, META, NVDA, HOOD, MSTR, TSLA, COIN, AVGO, AMD, MU, ORCL, PLTR, CRM, JPM, LLY, WMT, COST, NFLX, MRVL, SMCI, DELL, CRWD, PANW, UBER, GS, BAC, V, MA, DIS, XOM, INTC, LRCX and AMAT. Also carries SEC insider filings, Strategy 8-K and KPI updates, and corporate treasury press releases.
Social "social"
Market-moving social posts, screened for impact before delivery.
Crypto Listings "crypto-listings"
New listings the moment the exchange announces them: Binance, Robinhood, Upbit and Bithumb.
Strategy (MSTR) "strategy-mstr"
Everything Strategy: 8-K filings with ATM raises and buybacks, weekly BTC purchases and USD reserve changes from the Strategy metrics tracker, insider Form 4 and 144 filings from Michael Saylor and Phong Le, posts from @saylor, @phongle and @Strategy, and the Coinbase BTC premium against Binance.
Bitmine (BMNR) "bitmine-bmnr"
Everything Bitmine: every PR Newswire release including the weekly ETH holdings update, 8-K filings summarized, insider Form 4 and 144 filings from Tom Lee and Chi Tsang, and posts from @fundstrat and @BitMNR.
Hyperliquid "hyperliquid"
Everything Hyperliquid: Hyperliquid Strategies (PURR) 8-K, 10-Q, 10-K and other SEC filings, earnings results, insider Form 4 and 144 filings from David Schamis and the HYPS board, posts from @HyperliquidX, @HyperFND, @chameleon_jeff and @dschamis, Hyperliquid-related posts from @HyperliquidPC, the Hyperliquid Discord announcements channel, the MLM onchain Telegram channel, and Hyperliquid blog and Hyperliquid Policy Center posts.
Base / Coinbase "base-coinbase"
Coinbase and Base as they publish: Coinbase (COIN) 8-K, 10-Q, 10-K and other SEC filings, earnings results, Brian Armstrong insider Form 4 and 144 filings, Coinbase investor relations press releases, and posts from @coinbase, @brian_armstrong, @base and @jessepollak.
Robinhood "robinhood"
Robinhood as it publishes: Robinhood Markets (HOOD) 8-K, 10-Q, 10-K and other SEC filings, earnings results, Vlad Tenev insider Form 4 and 144 filings, Robinhood newsroom releases, Robinhood crypto and stock-token listings, $5M+ bridge deposits into Robinhood Chain, and posts from @vladtenev, @RobinhoodApp, @RobinhoodComms, @RobinhoodCrypto and @ponsdotfamily.
Zcash "zcash"
Zcash as it publishes: Zcash Foundation, Electric Coin Co and Zcash Open Development Lab blog posts, Zebra, zcashd and Zallet releases, Zcash Community Forum posts from core developers and the Foundation, an alert whenever $10M+ of ZEC leaves the shielded pools in one transaction, posts from @Zcash, @zooko, @DefuseSec, @jswihart and @ebfull, and @mert when he posts about Zcash.
DeFi Tracking "defi"
DeFi buyback triggers as they happen: USDe supply read directly from the Ethereum contract, alerted when spot supply tops each $ENA fee-switch milestone ($7.5B, $10B, $15B, $20B, $25B) and when the 14-day average clears it, plus Maple monthly revenue prints with the buyback rate and the implied $SYRUP buyback under the MIP-021 rules-based program (July to December 2026), for months where that buyback reaches $1M.
AI "ai"
The AI industry as it publishes: OpenAI, Anthropic, Google DeepMind and NVIDIA newsroom posts, BIS press releases and Federal Register export-control rules on chips and Entity List changes, posts from @sama, @demishassabis and @SpaceXAI, and AI-classified exclusives from the major publications.
US / Iran "us-iran"
The US-Iran track in one feed: every Donald Trump Truth Social post, Iran-related OFAC sanctions actions and list updates, Iran-related Treasury and OFAC press releases, posts from Iranian officials (@araghchi, @IRIMFA_EN, @IRIMFA_SPOX, @Gharibabadi, @PGSA_IRAN, @Ebrahimazizi33, @Drvelayati_ir, @MKhamenei_ir) and @CMShehbaz, UAE NCEMA security alerts, UKMTO maritime alerts, @BarakRavid, and a flash alert whenever WTI or Brent moves 5% within a minute.
Markets "markets"
Large token transfers and CoW Protocol order flow.
Alerts "alerts"
Market alerts as they trigger: large Hyperliquid TWAP orders (from $2M, higher bars on BTC, ETH, SOL, HYPE and ZEC) with size, duration, pace and wallet, and price alerts across tracked crypto assets and majors: sharp moves over 10-second to multi-minute windows, one-minute flash moves, cross-venue divergences and stablecoin depegs.
Bankruptcy Filings "bankruptcy-filings"
Chapter 11 petitions from US bankruptcy courts, filtered to crypto companies and S&P 500 names.
FOMC "fomc"
Fed decisions, statements, projections, minutes and Beige Book, speeches from Warsh, Waller and Williams, and Nick Timiraos on X and in the WSJ.
Project Blogs "project-blogs"
Official blogs and announcement pages of tracked projects: Ethereum Foundation, Tether, Zcash Foundation, Electric Coin Co, Canton Network, Arbitrum, Arbitrum Foundation, OKX, Chainlink, Sui, Litecoin, Circle, Drift, TRON DAO, XRP Ledger, Aave, BNB Chain, Arc, Solana, Morpho, Ethena, World, Plasma, LayerZero, Avalanche, Crypto.com, Ripple, Ondo Finance, Uniswap, Bittensor, Hyperliquid, Coinbase investor relations, the Robinhood newsroom, Anthropic, Lighter and the Zcash Open Development Lab.
Governance Forums "governance-forums"
New proposals and discussions on governance forums: Jupiter, Ethena, Aave, Arbitrum, Uniswap, Solana SIMD, Hyperliquid Policy and the Zcash Community Forum.
Errors & limits
| Code | Meaning |
|---|---|
| 400 | since_id or cursor is not a whole number, or format is not json or msgpack. |
| 401 | Missing or invalid API key. |
| 403 | Key is valid but not subscribed to that feed. |
| 404 | Unknown feed. |
| 429 | Rate limit exceeded. See the Retry-After header. |
| 4000 / 4001 / 4003 / 4008 | WebSocket close codes: unsupported format / invalid key / no active subscription or authorization revoked / connection limit reached. |
| 1001 / 1008 / 1009 / 1011 / 1006 | Server shutting down / slow consumer (too much unread data buffered) / too many messages before auth completed / temporary server error / heartbeat timeout (no close frame). Reconnect with backoff. |
Rate limits
REST is limited per key to a burst of 30 requests, refilling at 2 per second. Every
response carries X-RateLimit-Limit and
X-RateLimit-Remaining; a 429
also sets Retry-After (seconds). WebSocket allows up to 2
concurrent connections per key. The stream needs no polling - hold one connection open
and use REST only to backfill after a disconnect.
History retention
Trader keys can read the last 30 days of each feed over REST, enough to backfill after a reconnect or a cold start. Enterprise keys get the full history with no cap. Items older than your plan's window are simply not returned.
Revoking a key or canceling a subscription takes effect within seconds, including on connected WebSockets.
Payload stability
The fields in the table above are the contract - we will not rename or remove them without
notifying every active key by email first. We do add new optional fields as we add sources,
so parse defensively and ignore what you do not recognize.
feeds only ever contains feeds that currently exist; match on
the slug you subscribed to rather than assuming a single value.