Listing Spec

Everything a chain needs to expose to be listed on Blocktivity — the required JSON shape, audit endpoints, transaction-definition rules, history coverage and verification.

How it works

Blocktivity is designed to be self-sustaining. We ask each chain to own its data — to provide a stable API endpoint that counts its own transactions — rather than requiring Blocktivity to run chain-specific indexers. This means:

  • A chain can be listed with a single required endpoint (daily transaction count).
  • The chain controls its data accuracy and uptime.
  • Blocktivity publishes honest data-status labels rather than pretending to independently verify everything.

The more endpoints a chain provides, the higher the data-status it can achieve. But the minimum ask is intentionally low so that any chain can participate.

Required fields

A chain cannot be listed without all of these. Submit them via the Add Your Chain form.

FieldTypeNotes
namestringChain display name. Drives the coin URL slug (e.g. Bitcoin Cash → /coin/bitcoin-cash).
symbolstringTicker symbol. Uppercased on store. Only a fallback for the chain slug, when the name yields none.
websitestringOfficial chain website (https required)
contactEmailstringContact email for listing correspondence.
txEndpointstringURL returning the chain's daily transaction count in the tx-endpoint.schema.json shape (https required). This is the minimum required endpoint.

The tx-endpoint shape

The URL you provide in txEndpoint must return a JSON object. Required fields: 

// Required
{
  "transactions":  1204887,                   // integer ≥ 0
  "period_start":  "2026-06-27T00:00:00Z",    // ISO 8601 UTC
  "period_end":    "2026-06-27T23:59:59Z",    // ISO 8601 UTC
  "updated_at":    "2026-06-27T14:15:00Z"     // must be within 24h of fetch time
}

// Optional but strongly recommended
{
  "chain":         "Solana",
  "chain_id":      "mainnet",
  "period":        "24h",
  "from_block":    290000000,
  "to_block":      290100000,
  "transaction_definition":         "successful user-submitted",
  "failed_transactions_included":   false,
  "system_transactions_included":   false
}

Required

FieldTypeNotes
transactionsintegerTransaction count for the reported period, per the chain's disclosed txDefinition (required)
period_startstringISO 8601 UTC timestamp for the start of the counted period (required)
period_endstringISO 8601 UTC timestamp for the end of the counted period (required)
updated_atstringISO 8601 UTC timestamp when this response was last calculated. Blocktivity uses this for freshness checks. Must be within 24 hours of fetch time to avoid a stale status. (required)

Optional but strongly recommended

FieldTypeNotes
chainstringHuman-readable chain name (optional)
chain_idstringChain network identifier, e.g. mainnet (optional)
period"24h"Reporting period. Must be 24h — daily is the only supported period.
from_blockintegerFirst block included in the count (optional, aids auditability)
to_blockintegerLast block included in the count (optional, aids auditability)
transaction_definitionstringHuman-readable description of what is counted, e.g. successful user transactions only (optional)
failed_transactions_includedbooleanWhether failed transactions are included in the count (optional)
system_transactions_includedbooleanWhether system/protocol-internal transactions are included in the count (optional)
  • Blocktivity fetches this endpoint hourly. Ensure it is stable and returns within 10 seconds.
  • If updated_at is more than 24 hours old, the chain will be marked stale.
  • Additional fields in the response are ignored — additionalProperties is allowed.

Transaction-definition disclosure

All 7 fields of txDefinition are required. They are displayed on your coin page so visitors understand exactly what your number means. See Methodology → Transaction definition for the full field reference.

FieldTypeNotes
successful"included" | "excluded"Are successful transactions counted?
included — Included in the count
excluded — Excluded from the count
failed"included" | "excluded"Are failed transactions counted?
included — Included in the count
excluded — Excluded from the count
system"included" | "excluded"Are system/protocol-internal transactions counted?
included — Included in the count
excluded — Excluded from the count
internal"included" | "excluded" | "n-a"Are internal (sub-call) transactions counted? Use n-a if the concept does not apply to this chain.
included — Included in the count
excluded — Excluded from the count
n-a — Not applicable to this chain
batched"as-batch" | "individually"Are batched transactions counted once (as-batch) or once per inner transaction (individually)?
as-batch — The batch counts as one transaction
individually — Each transaction in the batch counts
rollup"l2-user-tx" | "l1-settlement" | "both" | "n-a"For rollup chains: which layer is counted? Use n-a for non-rollup chains.
l2-user-tx — L2 user transactions
l1-settlement — L1 settlement transactions
both — Both L2 user and L1 settlement
n-a — Not applicable to this chain
window"utc-day" | "rolling-24h"Counting window: UTC calendar day (00:00–24:00 UTC) or rolling last 24 hours.
utc-day — UTC calendar day (00:00-24:00 UTC)
rolling-24h — Rolling last 24 hours
{
  "txDefinition": {
    "successful": "included",
    "failed":     "excluded",
    "system":     "excluded",
    "internal":   "n-a",
    "batched":    "individually",
    "rollup":     "n-a",
    "window":     "rolling-24h"
  }
}

Date-range endpoint — earns the Full history badge

Optional, and set up once your chain is listed. What we ask for: one endpoint that accepts a start and end date and returns per-day activity for that window.

Worked example:

GET /v1/activity?from=2021-01-01&to=2021-03-31

{ "data": [ { "date": "2021-01-01", "tx": 412903 },
            { "date": "2021-01-02", "tx": 398117 } ] }

What we promise about load

One call per hour for the current reading. When we first list you we will walk your history backwards in windows of up to 90 days, one window per hour, until we reach your genesis — then we stop. If we ever miss an hour, we re-request that day once. We never issue more than one range request per hour for your chain, and we never run them in parallel.

A window cap is fine — if 90 days is too much, tell us and we'll use whatever you allow.

With it, your chain shows Full history. Without it, Tracked since <date> — still listed, still ranked identically. Nobody is excluded.

Already listed? Add a range endpoint any time — we backfill from it and the badge appears retroactively.

Authenticity verification

Authenticity verification proves that the submission came from a legitimate party. It does not verify the truth of the transaction numbers. Five methods are accepted:

MethodAlso sendDetails
dns-txtdomainDomain to which a TXT record blocktivity-verify=<token> has been added
well-known-fileurlURL of the uploaded /.well-known/blocktivity.json verification file
githubrepoUrlOfficial GitHub repository or organisation URL from which verification was completed
socialpostUrlURL of the public post from the official social account containing the verification code
explorerdomainDomain of the official explorer whose operator verified the endpoint

Authenticity verification is optional at submission time and can be completed asynchronously via the claim flow. Unverified submissions receive provisional status; verified submissions from official teams qualify for official-api status.

Test your endpoint

Paste your txEndpoint URL to check it against the required JSON shape before submitting.

Common errors

HTTPNameCause
400Validation errorMissing required fields, invalid types, or a txDefinition field is missing.
400Honeypot triggeredThe _confirm field in the payload was non-empty (bot protection).
429Rate limitedToo many submission attempts from the same IP.
500Internal errorServer error — try again; if persistent, contact us via the contact form.

Important

To appear accurately on Blocktivity, your chain must provide a stable transaction-activity endpoint. If your endpoint fails, your chain may be marked stale or removed from the active leaderboard until the issue is fixed.

Submit your chain →

Questions? Contact us or check the Methodology for data-status definitions.