Use the API with your key

Authenticate with your key, read the response format, page through lists, and handle errors and rate limits.

1. 1Your key

   The API lives at /api/v1 and every request needs a key. Keys are issued by BlockBoard: there is no self-service sign-up yet. A key looks like bb_ab12cd34_…: the first part, bb_ab12cd34, is its public name; the rest is the secret. You see the whole key once, when it is handed to you. Keep it like a password: we only store a fingerprint of it and cannot show it again. If it leaks, ask for it to be revoked and for a new one.

   Send it in a header, never in the address: Authorization: Bearer <key>, or X-API-Key: <key>. A key in the address is ignored.

2. 2First request

   curl https://blockboard.net/api/v1/status \ -H "Authorization: Bearer $BB_KEY"

   /api/v1 lists every endpoint, and /api/v1/openapi.json describes them all in OpenAPI 3, for tools that generate a client. Both need the key too.

3. 3What comes back

   Every answer is JSON with the same shape:

   { "data": [ … ], "meta": { "as_of": "2026-11-14T09:30:00Z", "count": 50, "next_cursor": "eyJz…" } }

   data is a list, or one object. as_of is how fresh the data is, count is how many items are in data, and next_cursor is there when more pages follow. Times are ISO 8601 in UTC (ending in Z), numbers come unformatted (1234567.89, not «1.2M») and field names are in snake_case. Answers are never cached: ask again for fresh data.

4. 4Pages, filters and order

   Lists come in pages. limit sets the size, from 1 to 500 (50 by default). To get the next page, send the next_cursor you received as cursor, with the same filters and order; when next_cursor is null you have everything. Pages stay consistent while new items arrive.

   sort takes a field name, or the name with a minus sign for descending order (sort=-updated_at). Each endpoint lists the fields it can sort by and the filters it takes. A parameter the endpoint does not know is an error rather than being ignored, so a typo never returns everything.

5. 5Errors

   An error comes with its HTTP status and a body like {"error": {"code": "invalid_parameter", "message": "…", "details": …}}. The codes:

   • unauthorized (401): no key, or a key that is not valid. It does not say which.
   • account_required, account_inactive (403): the endpoint is about an account and the key has none, or that account is no longer active.
   • invalid_parameter, unknown_parameter, invalid_cursor (400): fix the request; details says what is wrong and what is allowed.
   • not_found (404), method_not_allowed (405): that method does not exist for that path. Almost everything is GET; the few actions say POST or DELETE.
   • rate_limited, live_quota_exceeded (429): see Limits.
   • internal_error (500): our side; try again later.

6. 6Limits

   Each key may make a set number of requests a minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the next minute). Past the limit the answer is 429 with Retry-After: wait that many seconds. The API is for programs on a server: browsers on other sites cannot call it.

   A few endpoints work out their answer live when you call them, such as a calculation read from the chain, a route quote for an amount, or a fresh recheck. They also count against a second, lower quota per minute and per day (UTC). The index at /api/v1 marks them in live_quota (always, or when_live when only some calls count), and /api/v1/status shows your quota. Their answers carry X-Live-Quota-Limit-Minute, X-Live-Quota-Limit-Day and X-Live-Quota-Remaining-Day. Past it the answer is 429 live_quota_exceeded with Retry-After; everything else keeps working.

7. 7Your own data

   A key can be linked to a BlockBoard account. Then the endpoints under /api/v1/me return that account's own data, and only that account's. A key without an account reads public data only, and /me answers 403 account_required. If the account is suspended or closed, /me answers 403 account_inactive for that key, while public data keeps working. Nothing in a request can point the key at another account.

   All data comes from BlockBoard. Identifiers are BlockBoard's own and stay the same between calls, so you can store them.

8. 8Narratives

   Everything on the Narratives pages: story threads, the overview, the bubbles by sector, the emerging-narratives radar with its rounds, funds and projects, and the topic catalogue. Story links are site paths such as /story/<key>.

   • /narratives/threads: live threads (one protagonist and what is told about it), paged. Fields: entity_id, label, kind, stories, newsrooms (most in one story), news_media (distinct in the thread), pieces, first_at, last_at, days, recent and previous (stories this week and the week before), direction (up, down, flat, or new while the archive is too short), momentum, attention_pct, price_change_7d, price_pct, gap (attention minus price rank), comparable, companions, also (merged twin entities), top_stories and recent_stories (key, title, url, at, newsrooms, event_type), narratives (slug, label, stories, category) and daily (new stories per day, 21 days). Filters: kind, direction. Sort: momentum (default, descending), stories, recent, newsrooms, news_media, attention_pct, price_change_7d, last_at, label.
   • /narratives/threads/{entity_id}: one thread with the same fields plus canonical_entity_id (a merged twin answers with the thread it joined), stand (now, before, newsrooms, pieces, price_change, companions, biggest, pace, coverage, price, verdict, meaning; null while the archive is short), asset (id, symbol, name), activity (day, stories, price_usd), newsrooms_top (name, stories), each narrative's state, state_label, tone and why this week, and window_days. 404 when there is no live thread.
   • /narratives/threads/{entity_id}/series: new stories per day and the coin's daily price. days (1 to 365, 21 by default), or from/to.
   • /narratives/overview: the overview panel: threads, stories, week, last_week, week_change, daily, rising, fading, top, gaining, falling (each entity_id, label, recent, previous, change, delta), points (attention against price), tones and tone_total, mix, pairs, share, talk_ahead, move_ahead, widest, week_widest, symbols, tiles, digest (label, name, detail, href), radar counts, window_days, archive_days, comparable. A change carries recent, previous, pct (null under five stories), sign, rank, strength, text and short.
   • /narratives/bubbles: narratives by sector in three windows (24h, 7d, 30d). Each view: window, total_stories, market_perf, search_snaps, search_snaps_before, covered, links (a, b, stories) and readings: slug, label, family, sector, stories, stories_before, stories_change, share, search_interest, search_interest_before, market_cap, perf, vs_market, cap_change, volume, volume_change, tvl, tvl_change_7d, coins, headlines (title, url, newsrooms), daily, related, state, state_label, tone, score, why, threads and radar (its radar categories with rounds, projects to watch and sales). Filters: window, state, family. /narratives/bubbles/{slug} gives one narrative in the three windows.
   • /narratives/radar: the emerging-narratives radar: generated_at, computed_at, window_days, readings, climate and movement (gaining, steady, fading, span). A reading: slug, label, bubble, excluded, coin_sector, rounds, rounds_before, is_new, quality_rounds, quality_funds, amount, growth, news, news_before, share, reference_views and reference_views_change (encyclopedia page views), social (casts, video, search and their _change), vs_market, volume_change, tvl, tvl_change, category_cap_change, presales, watch, parts, score, state, state_label, tone, sentence, weekly_rounds, weekly_news, since, history, stage, stage_label, stage_since, weeks. The climate: investment_activity, investment_trend, fear_greed, mood, altcoin_index, season, btc_dominance, market_cap_change, sentence. Filters: state, stage, include_excluded.
   • /narratives/radar/{slug}: one narrative: reading, sentence, brief, window, listed_share, rounds, window_rounds (round keys), funds, groups (funds that invest together), projects, outcomes (what happened after each round), valuations, climate, new_coins.
   • /narratives/radar/{slug}/history: one reading per day (day, score, state, stage, rounds, quality_rounds, news, amount, share, parts, reconstructed, computed_at), paged, from/to, sort day.
   • /narratives/radar/{slug}/signals: the raw daily signals behind a category: reference_views, casts, video, search, category_cap_change, category_projects, each a list of day and value. metric picks one; from/to (90 days by default).
   • /narratives/projects/{slug}: a project that raised a round: project (slug, name, category, raised, last_at, quality, funds, listed, symbol, token, match, news, news_items, social, noise, presale_href, open_sale, sales, valuation, outcome, rounds), sentence, funds, outcomes, rank_money, rank_noise, peers, narrative.
   • /narratives/rounds: funding rounds, paged: total, rows, facets (categories, stages, amounts, funds) and categories_top. A round: id, key, project, project_slug, project_url, presale_project_id, asset_id, at, precision, amount_usd, valuation_usd, stage, stage_group, category, category_label, investors (slug, name, lead, quality), leads, quality, headline, story_id, story_url, origin (story, presales or both), evidence_url, href, source_count. Filters: category, stage, amount (lt5, 5-25, 25-100, gt100, in millions), fund, days (30, 90, all), from/to. Sort: at (default, descending), amount, valuation, project. /narratives/rounds/biggest: the largest rounds, days and limit.
   • /narratives/funds: funds behind the rounds, paged: slug, name, url, score, curated, quality, rounds, leads, rounds_window, leads_window, amount_window, categories, perf, perf_n, tier, tier_info, projects_count. Filters: quality, active, category. Sort: score (default), rounds, leads, rounds_window, amount_window, perf, name. /narratives/funds/{slug} adds intro, co_investors and its rounds in projects. /narratives/funds/top-month: what top funds bought this month, each with round_list. /narratives/funds/first-entries: top funds entering a narrative for the first time this month (category, round).
   • /narratives/catalog: the fixed vocabulary: narratives, windows, bubble_states, radar_states, radar_stages, radar_categories, round_stages, round_amounts, signal_metrics.
   • /narratives/topics: topics and sectors stories are filed under, paged: slug, label, kind, parent, asset_id, description, active, sort, stories. Filters: kind, include_inactive; sort sort, label, slug. /narratives/topics/{slug}: the topic, its assets and its stories (story_id, key, title, url, confidence, because, at), paged, from/to, sort at or confidence.

9. 9Alerts

   The public alerts of BlockBoard: four fixed rules, each with its threshold in the open. Alerts you set up yourself are under /api/v1/me.

   • /alerts: what fired in the last days (7 by default, up to 30), paged. Each row: rule (service_down, big_theft, unexplained_move, fast_consensus), section (market, security, news), level, title, detail, at, link (a big theft links to its incident in this API), subject, subject_kind, and as on the page kind, name, rule_label, badge, badge_tone, meta, figure, figure_tone, under, pinned, repeats and first. Filters: section, rule, level, from/to; dedupe=false gives every firing instead of one row per thing. meta adds window_days, total and shown.
   • /alerts/summary: this week by category (key, label, lead, rules, count, days per day, last row), day_labels and the six highlights.
   • /alerts/rules: each rule with name, watches, condition, measured (why that number), section, fired and daily; meta has theft_threshold_usd (the live 90th percentile), theft_percentile and consensus (newsrooms and minutes).

10. 10Security

    The archive of thefts, exploits and frauds, and the hacks of DeFi protocols.

    • /security/incidents: every incident, paged. Records of the same theft (same victim within two days) are merged into one row, as in the alert; merge=false gives each record. Fields: id, day, entity, summary, technique, chains, amount_usd, amount_text (as written, sometimes in coins), no_loss, percentile (place of the amount in the archive), above_alert_threshold, other_amounts (the other records of the same theft), records, reference_url (the news or statement, when there is one), first_seen_at, updated_at. Filters: from/to (day of the incident), min_amount, q, chain, technique, include_no_loss. Sort: day (default -day), amount_usd, first_seen_at, entity.
    • /security/incidents/{id}: one incident with the same fields and funds: what was recovered, returned or frozen (kind, amount_text, scope), or null. Funds are fetched once and kept an hour; a fetch counts against the live quota.
    • /security/incidents/stats: count, with_amount, total_usd, median_usd, p90_usd, alert_threshold_usd, since, by_year and by_technique, for from/to.
    • /security/protocol-hacks: hacks of DeFi protocols: id, name, day, amount_usd, returned_usd, classification, technique and protocol_slug (the protocol in Yields). Filters: from/to, q, protocol, min_amount, classification. Sort: day, amount_usd, returned_usd, name.

11. 11Presales

    Token sales, presales, public sales, auctions, airdrops and funding rounds, as on the Presales pages. Where a sale happens (an exchange, a launchpad, a sale read from the chain) is named in platform. Every figure says how we know it in provenance: basis is on_chain, platform (both verified), registry (a regulatory filing, with the link to the document) or declared (what the project announced, with no name and no link). If the Presales section is switched off, every endpoint here answers 404.

    • GET /api/v1/presales/sales: the sales table. state open (default), upcoming, ended, all or stale; filters q, kind (presale, public_sale, auction, node_sale, airdrop, vc_round), platform, flag (a flag code), investor, cat (sector), raised (lt100k, 100k-1m, 1m-10m, 10m, none), ends (7, 30, 90, past30, none), ends_from/ends_to (YYYY-MM-DD), kyc (yes, no, unknown); sort closing, date, amount, risk, sources or news. data has total, states with their counts, kinds, categories, sectors, kyc_counts, platforms, sorts and rows. Each row: sale_id, project (slug, name, ticker, logo, sector, chains), kind, kind_label, stage, phase, platform, status, status_raw, status_label, start_at, end_at, date_text, when, countdown, window_gone, is_stale, price_usd, price_is_auction_start, target_usd, raised_usd, committed_usd, amount, amount_kind, progress, participants, valuation_usd, fdv_usd, initial_mcap_usd, investors, multiple, thin_gain, impossible, cashable, compared (what today's price is compared with: basis market or dex, price, pair, liquidity), reward, pools, risk_level, worst_tier, flags, stories, track, kyc, provenance, onchain (money seen reaching the sale wallet), link (where to take part), phases, confidence, source_count, first_seen_at, updated_at.
    • GET /api/v1/presales/upcoming: the same table for sales not open yet, plus weeks (the next four weeks).
    • GET /api/v1/presales/sales/{sale_id}: one sale, the row plus allocation, details (press, contract check, market), refs (what each source says, platform named or declared), date_changes and value_changes. …/snapshots: raised, committed and participants over time (from, to, paged).
    • GET /api/v1/presales/projects: every project (q, sector, chain, has_token; sort name, first_seen_at, updated_at, sales, last_sale_at). …/projects/{slug}: the full sheet: project with links, contracts and chain check, KPIs, primary_link, checked, flags, history, checklist, faq, price steps and series, every sale, investors, stories, automatic checks and following (whether the key's account follows it; null without an account). …/prices: daily price (basis market or dex) and each sale's price. …/changes: dates, figures and flags that changed (from, to).
    • GET /api/v1/presales/overview: what deserves attention and why, high risk, closing and opening soon, the figures of the top strip (box) and four weeks.
    • GET /api/v1/presales/flags: red and green flags, one row per project (sig risk, info, all or a code). …/flags/feed: every flag, newest first, also retired ones (code, severity, active, from, to; sort detected_at). …/flag-types: what every code, tier, check and basis means, and the values every filter takes.
    • GET /api/v1/presales/results: how sold tokens trade against their sale price (per d30, d90, y1, all), by platform, ecosystem, sector, size and news. …/after: sold tokens that trade now (q, sort date, best, worst).
    • GET /api/v1/presales/rounds: funding rounds (q, sec=true to include regulatory filings, sort date, amount, news, from, to), with sector totals and weekly money. …/investors and …/platforms: who backs and who sells, with how their tokens trade.
    • GET /api/v1/presales/calendar: one month (month YYYY-MM; kind, cat, raised, kyc, q, from, to): days with what opens and closes and the money closing, bars and events.
    • GET /api/v1/presales/launchpads/{category}/coins: the coins that came out of a launchpad, with price, market cap, highs and lows and their change (sort rank, market_cap, change_1y, change_30d, symbol).
    • POST /api/v1/presales/projects/{slug}/recheck: ask for the project to be read and checked again on the next pass. Counts against the live quota. Answers {slug, queued, state, requested_at}.

12. 12Presales you follow

    With a key linked to an account. Following a project is the same alert as the Follow button on the site: it is sent like your other alerts and managed in My alerts.

    • GET /api/v1/me/presales/following: each followed project with alert_id, project_slug, project, name, active, quiet_minutes, fired_count, last_fired_at, created_at.
    • POST /api/v1/me/presales/{slug}/follow: follow it (answers {following, alert_id}; the same alert if it was already followed; 400 when the account already has the maximum number of alerts).
    • DELETE /api/v1/me/presales/{slug}/follow: stop following it ({following: false}).

13. 13Yields

    The Yields section: every pool with what it pays and where that comes from, our rating, a daily history per pool, the protocols, the deposit calculator, Find a pool and the exchange launchpools. Pool ids (pool_…) are BlockBoard's own.

    • /yields/pools: the table, paged (up to 5,000 rows deep). Each pool: id, protocol (slug, name, category, family, url, logo), chain, symbol, tokens, underlying_tokens, pool_meta, variant, pool_address, tvl_usd, tvl_unverified, tvl_check, tvl_note, apy (total, base, activity what real activity pays, reward token emissions, emission_share, mean_30d, change_7d, change_7d_raw, mean_life, sigma, held_up_by, state collateral/idle/unreported, doubtful, flagged_unusual, estimated), stablecoin, il_risk, exposure, history_days, years, pool_type, fee_pct, fee_dynamic, volume_1d_usd, pool_created_at, risk (level, reason, basis, at), score, grade, link (url, kind, label, exact), calc_format, calc_format_label, context (the news about the protocol: story_key, title, at, url, repeat), first_seen_at, updated_at, last_listed_at. meta.table has the totals and what each filter hides. Filters, as in the advanced filter: chain, tok, tokmode, xtok, wrap, t1/t2, apy_min/apy_max, real, tvl_min, vol_min, fee, proj, fam, age_min, risk, ptype, keep, the tab kind (stable, single, no-il) and zero=1 for pools that pay (almost) nothing. Sort, always descending: -tvl, -apy, -base, -change.
    • /yields/pools/{id}: one pool with everything above plus aka, protocol_tvl_usd_reported, app_url, app_url_status, facts (where each figure comes from: pool_list, market_indexer, protocol_api, onchain, rule, and when), score_parts, badges, rank (class and position), context_stories, hacks and the protocol's audits, age, oracles and TVL.
    • /yields/pools/{id}/history: one point per day since the daily snapshot started: day, tvl_usd, apy_base, apy_reward, apy_total, apy_mean_30d, score, grade, tvl_unverified. from/to, paged, oldest first.
    • /yields/count and /yields/facets: how many pools a filter returns (count, tvl_usd, zero, active, hidden), and what the filter offers (networks, protocols, protocol families, tokens, token families). /yields/reference: the fixed vocabularies (pool types, fee buckets, ages, grades, classes, calculator formats, thresholds).
    • /yields/overview: capital, pools, protocols and networks, stablecoin yield against fed_funds_rate and treasury_10y, real vs emissions, buckets, top networks and protocols, risers and fallers.
    • /yields/ranking: our rating, top pools of a class (stable, eth, btc, other, pairs or all; limit up to 100) with rank, moved, score, grade, blocks, badges; meta has grade_counts, class_counts, rated_total. /yields/ranking/history: the daily top 100 of each class (class, from/to), or one pool's position with pool_id.
    • /yields/protocols (filters q, family, category, with_pools; sort name, tvl_usd, pools, pools_tvl_usd, updated_at) and /yields/protocols/{slug} (with its hacks, pools, news and bad_news).
    • /yields/calculator/pools?q= finds a pool for the calculator. /yields/calculator?pool= is the deposit calculator, live: pair pools we can read are read on-chain. Without amount it gives the form data (format, tokens, current price, 90-day pair history); with amount (unit usd or a token index, lo/hi for a concentrated range, inv) the split per token (legs), in_range and earnings at today's APY over 1 month, 3 months and 1 year.
    • /yields/match: Find a pool. amt, hold (stable, eth, btc, sol, other), risk, watch (passive, active), chain; up to five pools with real_apy, risk, link and reasons. Not advice.
    • /yields/launchpools: exchange launchpools, paged: id, exchange, product, token, reward_total, state, dates, days_left, url, best_apr, best_clean_apr, staked_usd and per coin options (stake, apr, staked, staked_usd, limits per user, reward, participants, only, doubts). Filters state (live, open, upcoming, ended, all), exchange, stake, earn, min_apr, trust, q; sort end, apr, staked or start. /yields/launchpools/{id}: one.

14. 14Bridges

    Bridges & Swaps: the bridge catalog, networks and tokens, which bridges cover a crossing and live route quotes.

    • /bridges/providers (also /bridges): every bridge, paged: slug, name, kind, kind_label, domain, url, link_template, link_proof, link_proof_url, link_ok (whether its link is shown now), status, status_note, chains, tokens, typical_seconds, typical_time, return_note, security, about, incidents, live_quotes, logo, position, domain_watch (last check, last good check, hidden, expiry, certificate issuers), reviewed_at, updated_at. Filters kind, chain, token, status; sort name, slug, position, typical_seconds, updated_at.
    • /bridges/providers/{slug}: one bridge with its last domain_checks. /bridges/providers/{slug}/domain-checks: the whole history of the domain watch, paged: checked_at, verdict (ok, rotated, suspicious, error), reasons (dns, cert, redirect), cert_issuer, cert_not_after, domain_expires, final_host; filters verdict, from/to.
    • /bridges/chains: networks (key, name, chain_id, family, gas_symbol, logo, notes), and the closed ones in meta.sunset. /bridges/chains/{chain}/tokens: its tokens by relevance, paged, with q: address, symbol, name, decimals, rank, market_cap, volume_24h, native, core, listed_in_count.
    • /bridges/coverage: with from, token, to and optionally receive, which bridges cover the crossing, with their link and typical time. No quote is asked.
    • /bridges/routes: the same plus amount: every bridge on the crossing is asked for a live quote, and the routes come by what you receive: receive, cost, gas_usd, fixed_fees, seconds, time_text, link, about, badges (Best, Fastest), mode, estimated_via_third_party; with form, asked, notes and the disclaimer. Only a call with an amount and a complete crossing counts against the live quota. Information, not advice.

Last updated Nov 14, 2026