API and widgets

BitBasic's data as JSON, and widgets you can put on your own site. Free, read-only, no key needed.

The API

Every endpoint is a GET under https://bitbasic.com/api/v1 and answers in JSON. It serves the same data as the dashboards, from BitBasic's own copy, so it never waits on a chain.

Amounts: Token amounts are exact base units as strings, with the token's decimals and symbol beside them: {"base_units": "200000000000000000000000", "decimals": 18, "symbol": "AZTEC"} is 200,000 AZTEC. They don't fit in a JSON number.
Times and percentages: Times are ISO 8601 in UTC (2026-10-28T12:59:40Z). Percentages run from 0 to 100, to two decimals.
Freshness: Each chain response says how fresh its data is: freshness.updated_at is when BitBasic last read it, and freshness.stale turns true when that is more than stale_after_seconds ago, the same rule that marks a dashboard card "Stale". Check it before you show a figure as current.
Rate limit: 60 requests a minute per IP address. Every response has X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get a 429 with Retry-After in seconds. Need more? Write to us.
Caching and CORS: Responses may be cached for 30 seconds; the fastest data refreshes every minute, so polling more often only spends your limit. Any website may call the API from the browser (Access-Control-Allow-Origin: *). No cookies are set.
Versions: Within v1 we only add fields and endpoints, so ignore fields you don't know. Anything that would break existing code comes as /api/v2, with v1 kept running for a while.

Endpoints

{chain} is a chain's slug from the chain list ("aztec", "mina", "concordium"). The examples use Aztec with made-up rows; follow the request links for live data.

GET `/api/v1/chains`

Every chain BitBasic covers, with its token, its own words for validators, epochs and blocks, and links to its other endpoints (null where it has no such data).

Try it: https://bitbasic.com/api/v1/chains

Example response

{
    "data": [
        {
            "slug": "aztec",
            "name": "Aztec",
            "description": "Privacy-first layer 2 on Ethereum. Sequencer set, epochs, committee, governance and slashing.",
            "token": {
                "symbol": "AZTEC",
                "decimals": 18
            },
            "terms": {
                "validator": "Sequencer",
                "epoch": "epoch",
                "slot": "slot",
                "block": "checkpoint"
            },
            "links": {
                "dashboard": "https://bitbasic.com/aztec",
                "network_widget": "https://bitbasic.com/embed/aztec/network",
                "api": {
                    "network": "https://bitbasic.com/api/v1/chains/aztec/network",
                    "validators": "https://bitbasic.com/api/v1/chains/aztec/validators",
                    "epochs": "https://bitbasic.com/api/v1/chains/aztec/epochs",
                    "blocks": "https://bitbasic.com/api/v1/chains/aztec/blocks",
                    "providers": "https://bitbasic.com/api/v1/chains/aztec/providers"
                }
            }
        },
        {
            "slug": "mina",
            "name": "Mina",
            "description": "The succinct zero-knowledge blockchain. Block production, epochs and the staking ledger.",
            "token": {
                "symbol": "MINA",
                "decimals": 9
            },
            "terms": {
                "validator": "Block producer",
                "epoch": "epoch",
                "slot": "slot",
                "block": "block"
            },
            "links": {
                "dashboard": "https://bitbasic.com/mina",
                "network_widget": "https://bitbasic.com/embed/mina/network",
                "api": {
                    "network": "https://bitbasic.com/api/v1/chains/mina/network",
                    "validators": "https://bitbasic.com/api/v1/chains/mina/validators",
                    "epochs": "https://bitbasic.com/api/v1/chains/mina/epochs",
                    "blocks": "https://bitbasic.com/api/v1/chains/mina/blocks",
                    "providers": null
                }
            }
        },
        {
            "slug": "concordium",
            "name": "Concordium",
            "description": "The identity-aware layer 1. Validators, paydays, suspensions and block production.",
            "token": {
                "symbol": "CCD",
                "decimals": 6
            },
            "terms": {
                "validator": "Validator",
                "epoch": "payday",
                "slot": "epoch",
                "block": "block"
            },
            "links": {
                "dashboard": "https://bitbasic.com/concordium",
                "network_widget": "https://bitbasic.com/embed/concordium/network",
                "api": {
                    "network": "https://bitbasic.com/api/v1/chains/concordium/network",
                    "validators": "https://bitbasic.com/api/v1/chains/concordium/validators",
                    "epochs": "https://bitbasic.com/api/v1/chains/concordium/epochs",
                    "blocks": "https://bitbasic.com/api/v1/chains/concordium/blocks",
                    "providers": null
                }
            }
        }
    ]
}

GET `/api/v1/chains/{chain}`

One chain, as in the list.

Try it: https://bitbasic.com/api/v1/chains/aztec

Example response

{
    "data": {
        "slug": "aztec",
        "name": "Aztec",
        "description": "Privacy-first layer 2 on Ethereum. Sequencer set, epochs, committee, governance and slashing.",
        "token": {
            "symbol": "AZTEC",
            "decimals": 18
        },
        "terms": {
            "validator": "Sequencer",
            "epoch": "epoch",
            "slot": "slot",
            "block": "checkpoint"
        },
        "links": {
            "dashboard": "https://bitbasic.com/aztec",
            "network_widget": "https://bitbasic.com/embed/aztec/network",
            "api": {
                "network": "https://bitbasic.com/api/v1/chains/aztec/network",
                "validators": "https://bitbasic.com/api/v1/chains/aztec/validators",
                "epochs": "https://bitbasic.com/api/v1/chains/aztec/epochs",
                "blocks": "https://bitbasic.com/api/v1/chains/aztec/blocks",
                "providers": "https://bitbasic.com/api/v1/chains/aztec/providers"
            }
        }
    }
}

GET `/api/v1/chains/{chain}/network`

Where the chain is in its epoch, the validator set, total stake and network health. Health "label" reads "No recent data" when the reading is stale. "data" is null until BitBasic's first reading.

Try it: https://bitbasic.com/api/v1/chains/aztec/network

Example response

{
    "data": {
        "chain": "aztec",
        "epoch": {
            "number": 676,
            "name": "#676",
            "label": "Epoch #676",
            "started_at": "2026-10-28T19:02:23Z",
            "ends_at": "2026-10-28T19:40:47Z",
            "slot": 28,
            "slots": 32,
            "slot_duration_seconds": 72,
            "progress_percent": 87.5
        },
        "height": 2052,
        "validators": {
            "active": 3219,
            "queued": 12,
            "exiting": 3
        },
        "committee_size": 48,
        "total_stake": {
            "base_units": "643800000000000000000000000",
            "decimals": 18,
            "symbol": "AZTEC"
        },
        "health": {
            "score": 95.3,
            "label": "Healthy",
            "basis": "122 of 128 slots had a checkpoint in epochs #672–#675",
            "healthy_from": 85.0,
            "degraded_from": 70.0
        },
        "details": [
            {
                "label": "Proven checkpoint",
                "value": "#2,040",
                "hint": null
            }
        ]
    },
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 300,
        "refresh_interval_seconds": 60
    }
}

GET `/api/v1/chains/{chain}/validators`

The validator list, sorted like the dashboard table. Block counts cover the history BitBasic holds, from "production_counted_since". A page past the last one is an empty list.

Parameter	Values
status	active, queued, exiting, inactive, exited. Default: all.
sort	stake, produced, proposal_rate, attestation_rate, delegators. Default: the chain's, as on the dashboard (blocks produced on Aztec, stake elsewhere). Unknown values sort last.
direction	asc or desc. Default: desc.
page	From 1. Default: 1.
per_page	1 to 100. Default: 25.

Try it: https://bitbasic.com/api/v1/chains/aztec/validators?status=active

Example response

{
    "data": [
        {
            "address": "0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
            "name": null,
            "display_name": "0x4b1f5a…8e9f",
            "status": "active",
            "status_label": "Active",
            "stake": {
                "base_units": "200000000000000000000000",
                "decimals": 18,
                "symbol": "AZTEC"
            },
            "delegators": null,
            "is_bitnordic": false,
            "provider": {
                "key": "12",
                "name": "Example Staking"
            },
            "blocks": {
                "produced": 42,
                "missed": 3,
                "proposal_rate_percent": 93.33
            },
            "attestations": null,
            "first_seen_at": "2026-09-28T19:00:00Z",
            "last_seen_at": "2026-10-28T19:23:00Z",
            "links": {
                "dashboard": "https://bitbasic.com/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
                "api": "https://bitbasic.com/api/v1/chains/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
                "widget": "https://bitbasic.com/embed/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f"
            }
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 25,
        "total": 3219,
        "last_page": 129,
        "next": "https://bitbasic.com/api/v1/chains/aztec/validators?status=active&page=2",
        "prev": null
    },
    "sort": {
        "by": "produced",
        "direction": "desc"
    },
    "production_counted_since": "2026-10-21T19:00:00Z",
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 5400,
        "refresh_interval_seconds": 1800
    }
}

GET `/api/v1/chains/{chain}/validators/{address}`

One validator by address (or validator id on Concordium). EVM addresses match in any case.

Try it: https://bitbasic.com/api/v1/chains/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f

Example response

{
    "data": {
        "address": "0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
        "name": null,
        "display_name": "0x4b1f5a…8e9f",
        "status": "active",
        "status_label": "Active",
        "stake": {
            "base_units": "200000000000000000000000",
            "decimals": 18,
            "symbol": "AZTEC"
        },
        "delegators": null,
        "is_bitnordic": false,
        "provider": {
            "key": "12",
            "name": "Example Staking"
        },
        "blocks": {
            "produced": 42,
            "missed": 3,
            "proposal_rate_percent": 93.33
        },
        "attestations": null,
        "first_seen_at": "2026-09-28T19:00:00Z",
        "last_seen_at": "2026-10-28T19:23:00Z",
        "links": {
            "dashboard": "https://bitbasic.com/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
            "api": "https://bitbasic.com/api/v1/chains/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
            "widget": "https://bitbasic.com/embed/aztec/validators/0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f"
        }
    },
    "production_counted_since": "2026-10-21T19:00:00Z",
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 5400,
        "refresh_interval_seconds": 1800
    }
}

GET `/api/v1/chains/{chain}/epochs`

Recent epochs, newest first, with how many of their slots got a block.

Parameter	Values
limit	1 to 100. Default: 24.

Try it: https://bitbasic.com/api/v1/chains/aztec/epochs?limit=1

Example response

{
    "data": [
        {
            "number": 675,
            "name": "#675",
            "label": "Epoch #675",
            "started_at": "2026-10-28T18:24:00Z",
            "complete": true,
            "slots": 32,
            "blocks_produced": 29,
            "blocks_missed": 3,
            "fill_rate_percent": 90.63,
            "committee_size": 48,
            "attestations": null
        }
    ],
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 300,
        "refresh_interval_seconds": 60
    }
}

GET `/api/v1/chains/{chain}/blocks`

Recent blocks, newest first, with their producer.

Parameter	Values
limit	1 to 100. Default: 10.

Try it: https://bitbasic.com/api/v1/chains/aztec/blocks?limit=1

Example response

{
    "data": [
        {
            "height": 2052,
            "hash": "0x3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a3f9a",
            "slot": 21659,
            "epoch": 676,
            "producer": {
                "address": "0x4b1f5a0e9c3d2b7a8e6f0c1d2e3f4a5b6c7d8e9f",
                "name": null
            },
            "produced_at": "2026-10-28T19:34:00Z",
            "transactions": null
        }
    ],
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 300,
        "refresh_interval_seconds": 60
    }
}

GET `/api/v1/chains/{chain}/providers`

Staking providers, largest first, and how concentrated the active set is across them. Only on chains with providers (the "providers" link in the chain list).

Try it: https://bitbasic.com/api/v1/chains/aztec/providers

Example response

{
    "data": [
        {
            "key": "12",
            "name": "Example Staking",
            "description": "Runs validators for delegators.",
            "website": "https://staking.example",
            "admin_address": "0x9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
            "commission_percent": 10.0,
            "is_bitnordic": false,
            "validators": {
                "active": 11,
                "other": 3
            },
            "queued_keys": 3,
            "active_stake": {
                "base_units": "2200000000000000000000000",
                "decimals": 18,
                "symbol": "AZTEC"
            },
            "active_share_percent": 0.34,
            "blocks": {
                "produced": 420,
                "missed": 31,
                "proposal_rate_percent": 93.13
            },
            "links": {
                "dashboard": "https://bitbasic.com/aztec/providers/12"
            }
        }
    ],
    "concentration": {
        "providers": 41,
        "top3_share_percent": 18.42,
        "nakamoto_coefficient": 7,
        "unlinked_validators": 1210,
        "unlinked_share_percent": 37.59
    },
    "freshness": {
        "updated_at": "2026-10-28T19:34:57Z",
        "stale": false,
        "stale_after_seconds": 10800,
        "refresh_interval_seconds": 3600
    }
}

Errors

Errors have one shape: an error object with the HTTP status, a stable code to branch on and a message for people. Unknown chains, validators and paths are 404, as are lists a chain doesn't have (their link in the chain list is null). Invalid parameters are 422, with what was wrong in fields.

404 not_found

{
    "error": {
        "status": 404,
        "code": "not_found",
        "message": "Unknown validator."
    }
}

422 invalid_parameters

{
    "error": {
        "status": 422,
        "code": "invalid_parameters",
        "message": "Some query parameters are invalid.",
        "fields": {
            "sort": [
                "The selected sort is invalid."
            ]
        }
    }
}

429 too_many_requests

{
    "error": {
        "status": 429,
        "code": "too_many_requests",
        "message": "Too many requests: the limit is 60 a minute per IP address. Try again in 42 seconds.",
        "retry_after_seconds": 42
    }
}

Widgets

A live card for your site: a network's health and epoch, or one validator's status and production. Widgets refresh themselves every minute, set no cookies, run no scripts and load nothing from anyone else, so they add nothing to your cookie banner. Pick one, copy the code and paste it into your page.

Network Widget Theme

Code to paste

Choose a widget above to get its code.

Preview

Network: https://bitbasic.com/embed/{chain}/network
Validator: https://bitbasic.com/embed/{chain}/validators/{address}
Theme: Add ?theme=light or ?theme=dark to fix the colours; without it (or with ?theme=auto) the widget follows the visitor's light or dark setting.
Size: Widgets fit frames from 300 pixels wide. The code above sets a height that fits: 260 pixels for a network, 220 for a validator.
Limit: 120 widget loads a minute per visitor IP address, plenty for a page with several widgets.

Terms

The API and widgets are free and come as is, under BitBasic's terms of use: credit "BitBasic by BitNordic" with a link to bitbasic.com (widgets do this for you), keep to the rate limit, don't present the data as advice, and don't suggest that BitNordic endorses you. We may change or stop the service, and block traffic that overloads it.

API and widgets

The API

Endpoints

GET /api/v1/chains

GET /api/v1/chains/{chain}

GET /api/v1/chains/{chain}/network

GET /api/v1/chains/{chain}/validators

GET /api/v1/chains/{chain}/validators/{address}

GET /api/v1/chains/{chain}/epochs

GET /api/v1/chains/{chain}/blocks

GET /api/v1/chains/{chain}/providers

Errors

Widgets

Terms

GET `/api/v1/chains`

GET `/api/v1/chains/{chain}`

GET `/api/v1/chains/{chain}/network`

GET `/api/v1/chains/{chain}/validators`

GET `/api/v1/chains/{chain}/validators/{address}`

GET `/api/v1/chains/{chain}/epochs`

GET `/api/v1/chains/{chain}/blocks`

GET `/api/v1/chains/{chain}/providers`