Endpoints and answers

Endpoints

The catalog

Every daily metric with its label, unit and group; the metric groups; the sections the token page shows right now (often none); and every tool with its price and its input as JSON Schema. The list changes as the site does, so read it rather than hard-coding it

{
  "what": "Everything the Blocktronics API serves: the same data the site shows, nothing more. …",
  "endpoints": {
    "GET /v1/catalog": "this list (free)",
    "POST /v1/tools/{tool}": "one tool below, its JSON input as the body",
    "…": ""
  },
  "prices": {
    "pull": 2,
    "signals": 1,
    "readout": 10,
    "unit": "credits"
  },
  "metrics": [
    {
      "name": "holders",
      "label": "Wallets holding $5+",
      "unit": "count",
      "group": "holders_all"
    },
    {
      "name": "netflow_usd",
      "label": "DEX netflow (buys − sells)",
      "unit": "usd",
      "group": "netflow"
    },
    "…"
  ],
  "metric_groups": [
    "cohorts",
    "cost_basis",
    "concentration",
    "netflow",
    "volume",
    "profitability",
    "realized_pnl",
    "smart_money",
    "holders_all"
  ],
  "sections": [
    "… only the sections the token page shows now"
  ],
  "tools": [
    {
      "name": "token_series",
      "title": "Token daily series",
      "price": "2 credits per token",
      "description": "…",
      "input": {
        "…": "its JSON Schema"
      }
    },
    "…"
  ]
}

The tools

POST /v1/tools/{tool} with the tool's input as the JSON body. Its path takes the tool's name; anything else is 404 unknown_tool.

A tool's answer

Every tool answers { tool, ok, charged, data, text, images }. This is token_series for one token

{
  "tool": "token_series",
  "ok": true,
  "charged": 2,
  "data": {
    "token": {
      "symbol": "DEGEN",
      "name": "Degen",
      "chain": "base",
      "chain_label": "Base",
      "address": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
      "terminal_url": "https://blocktronics.xyz/t/base/0x4ed4…"
    },
    "metrics": [
      "holders",
      "netflow_usd"
    ],
    "days": 30,
    "from": "2026-09-26",
    "to": "2026-10-25",
    "format": "columns",
    "summary": {
      "holders": {
        "label": "Wallets holding $5+",
        "unit": "count",
        "first": 4102,
        "last": 4041,
        "change": -61,
        "change_pct": -1.5,
        "min": 4012,
        "max": 4130,
        "null_days": 0
      },
      "netflow_usd": {
        "label": "DEX netflow (buys − sells)",
        "unit": "usd",
        "first": -1820,
        "last": 2251,
        "change": 4071,
        "change_pct": null,
        "min": -9120,
        "max": 15400,
        "total": 18250,
        "null_days": 1
      }
    },
    "unavailable": {},
    "data": {
      "day": [
        "2026-09-26",
        "…",
        "2026-10-25"
      ],
      "holders": [
        4102,
        "…",
        4041
      ],
      "netflow_usd": [
        -1820,
        "…",
        2251
      ]
    },
    "truncated": null,
    "data_freshness": "cached, settled through 2026-10-25",
    "reads": {
      "charged": 2,
      "refreshing": true,
      "…": ""
    }
  },
  "text": "DEGEN · Base · 30 days 2026-09-26 → 2026-10-25 (UTC) · columns\n- holders: 4,102 → 4,041 (-1.5%), range 4,012–4,130\n- netflow_usd: -$1.8k → +$2.3k, range -$9.1k–+$15.4k, total +$18.3k, 1 null days\nThis pull used 2 credits. Blocktronics is bringing this token up to the hour now; a pull in a few minutes has the newest hours.",
  "images": []
}

tool · ok

The tool that answered, and true when it did.

charged

Credits this answer took: 2 a pull (token_series: per token), the readout's 10 when it opened it, 0 for the free tools and on every refusal.

data

The tool's answer as JSON: the same structured answer the MCP gives an AI app.

text

The same answer in plain words, for people and models. A pull's text ends with what it used and, when the token is being brought up to the hour, says so.

images

render_chart's picture, base64, with its mime_type. Empty for every other tool.

data.token

The token that answered: symbol, name, chain, address and its page on the site. A token on several chains is one token, read as one.

data.data_freshness

The last settled UTC day the answer covers.

data.reads.refreshing

true when the token's stored data was over 15 minutes old and its refresh started behind this answer: a pull in a few minutes has the newest hours.

token_series' data

Pick metrics by name or by group from the catalog. token takes one token or a list of up to 5, each a symbol, chain:SYMBOL, an address or chain:0x….

metrics

The metrics answered, with any group you asked for expanded into its metrics.

days · from · to

How many days came back and the first and last of them (UTC). A young token has fewer: count them.

summary.<metric>

first, last, change, change_pct, min, max, total (dollar flows) and null_days over the days returned.

data

format "columns" (the default): { day: [...], <metric>: [...] }, one value per day. format "rows": [{ day, <metric>... }]. A missing day is null, never 0.

unavailable

Panels that couldn't be read for this token, each with the reason. Their metrics are null.

outliers

Days the outlier guard left out, with why. They are never counted and never returned as values.

truncated

Set when a rows answer was too large and kept only the latest days, with how many and a note. null otherwise.

tokens

Instead of the above, when token is a list: one answer like it per token, 2 credits each.

The answer, drawn

Holders, netflow and the grade, for a real token

{
  "metrics": [
    "holders",
    "holders_ge_100",
    "holders_ge_1k",
    "holders_ge_10k",
    "holders_ge_100k"
  ],
  "days": 2,
  "from": "2026-10-24",
  "to": "2026-10-25",
  "format": "columns",
  "summary": {
    "…": "first, last, change, min, max, total and null days for each metric"
  },
  "unavailable": {},
  "data": {
    "day": [
      "2026-10-24",
      "2026-10-25"
    ],
    "holders": [
      4052,
      4041
    ],
    "holders_ge_100": [
      1318,
      1320
    ],
    "holders_ge_1k": [
      409,
      410
    ],
    "holders_ge_10k": [
      95,
      95
    ],
    "holders_ge_100k": [
      26,
      26
    ]
  }
}

The query

Up to 5 tokens in one request, run as the tools above and priced as their sum. The balance must cover every pull before anything runs; if it can't, the answer is 402 insufficient and nothing is charged

tokensstring[]required

1 to 5 tokens, each a symbol, "chain:SYMBOL", an address or "chain:0x…".e.g. ["base:DEGEN", "base:AERO"]

chainstringoptional

The chain, for tokens given without one.baseethereumrobinhood

metricsstring[]optional

Daily metrics or groups from GET /v1/catalog. 2 credits per token.e.g. ["holders", "netflow_usd"]

daysintegeroptional

The most recent days, 1 to 60. Ignored when from or to is given.e.g. 30

from · tostringoptional

A span of days (YYYY-MM-DD, UTC) inside the stored days. Days outside them are left out, with a note; nothing is filled in.

todaybooleanoptional

Each token's hours so far today. 2 credits per token.

overviewbooleanoptional

Each token's grade, main figures and reading. 2 credits per token.

sectionsbooleanoptional

The sections each token's page shows. 5 credits per token with its launch bundles, 2 without them.

signalsbooleanoptional

Each token's read, lean and fired signals. 1 credit per token.

readoutbooleanoptional

Each token's full readout, signals included, at the site's price: 10 credits, then open 24 hours.

{
  "tokens": [
    {
      "query": "base:DEGEN",
      "token": {
        "symbol": "DEGEN",
        "chain": "base",
        "address": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
        "…": ""
      },
      "series": {
        "metrics": [
          "holders",
          "netflow_usd"
        ],
        "days": 14,
        "summary": {
          "…": ""
        },
        "data": {
          "…": ""
        }
      },
      "today": {
        "day": "2026-10-26",
        "partial": true,
        "everyone": {
          "net_flow_usd": 412,
          "volume_usd": 5828,
          "…": ""
        },
        "hours": [
          "…"
        ]
      }
    },
    {
      "query": "base:AERO",
      "token": {
        "symbol": "AERO",
        "chain": "base",
        "address": "0x9401…",
        "…": ""
      },
      "series": {
        "…": ""
      },
      "today": {
        "…": ""
      }
    }
  ],
  "charged": 8
}

tokens[]

One entry per token asked, in the order asked.

tokens[].query · token

What you asked for, and the token it resolved to.

tokens[].series

token_series' answer for that token, when you asked for metrics.

tokens[].today · overview · sections · readout

The today, token_overview, get_sections and token_signals answers, when you asked for them.

tokens[].errors

A part that failed, by name, with why. A part that failed isn't charged.

charged

What the whole request took.

Every part

What each figure means, and the tool that serves it

Other answers

400 tool_error when a tool can't answer the input (a token Blocktronics hasn't indexed, for one), 402 insufficient or refused when the balance can't cover it, and 422 unsupported_token for a token Blocktronics doesn't support. None is charged. Every code is in errors; ingesting a new token is in freshness and new tokens.

Next