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

ParamTypeDescription
limitint1-500, default 100
since_idintReturn items after this id, ascending. For reconnect backfill.
cursorintReturn items before this id, descending. For paging older history.
formatstringjson (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

TypeMeaning
helloSent on connect. Lists the feeds your key is entitled to and the active format (json or msgpack).
subscribedConfirms your active subscriptions.
(event)A feed item. Carries id, feeds, and the payload.
pongReply to a client-sent {"type": "ping"}.
errorMalformed 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:

FieldTypeDescription
idintMonotonic feed id. Use it for since_id and cursor.
feedsstring[]Feeds this item belongs to. An item can be in more than one.
timeintEpoch milliseconds, at detection.
sourcestringMachine-readable origin bucket, e.g. news_outlets, cpi, truth_social.
source_namestringPublisher name, ready to display - "Wall Street Journal", "Federal Reserve", "SEC EDGAR", "CNBC (@CNBC)".
linkstringCanonical URL at the source - the article, filing, release or post the item came from.
headlinestringWire headline, uppercase. Empty string on media-only posts, where image / video carry the content.
bodystringItem text, uppercase. Multi-line for parsed releases. Mirrors headline when a source supplies only one of the two.
price_at_newsobject | nullEnterprise 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_idstringThe origin's own id. Stable across feeds - use it to dedupe an item that arrives on two feeds.
typestringnews_update, truth_post, direct, telegram, discord. Treat an unrecognized value as a generic item.
relevancestringOn 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.
categorystring | nullCoarse grouping, independent of feed membership: macro, headlines, crypto, truth, or null.
coinsobject[]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

CodeMeaning
400since_id or cursor is not a whole number, or format is not json or msgpack.
401Missing or invalid API key.
403Key is valid but not subscribed to that feed.
404Unknown feed.
429Rate limit exceeded. See the Retry-After header.
4000 / 4001 / 4003 / 4008WebSocket close codes: unsupported format / invalid key / no active subscription or authorization revoked / connection limit reached.
1001 / 1008 / 1009 / 1011 / 1006Server 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.