API Docs

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.

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":      "sol_0",
  "period":        "24h",
  "from_block":    290000000,
  "to_block":      290100000,
  "transaction_definition":         "successful user-submitted",
  "failed_transactions_included":   false,
  "system_transactions_included":   false
}

• 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.

Recommended fields & endpoint tiers

These fields are optional at submission time — but each one unlocks a higher data-status badge and strengthens trust on the site.

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.

{
  "txDefinition": {
    "successful": "included",
    "failed":     "excluded",
    "system":     "excluded",
    "internal":   "n-a",
    "batched":    "individually",
    "rollup":     "n-a",
    "window":     "rolling-24h"
  }
}

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:

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