Skip to main content

multichain-analytics-indexer

CI coverage PyPI License

A Python library and command line for indexing and analysing blockchain accounts and transactions, in each chain's own terms. It keeps what it reads in a local database, syncs incrementally, and produces metrics and exports for analysis.

This version supports Algorand, Solana and NEAR. See the roadmap for what comes next.

Install

pip install multichain-analytics-indexer

Python 3.11 or newer.

Quick start

From Python:

from multichain_indexer import Indexer

with Indexer("algorand") as indexer:  # testnet by default
    address = "JCN7TCSQEG6YHAQ7F6BS73J2UDXI2L7S7WJU35LYMIK22IL264ZRJO55QM"
    print(indexer.account(address).balance)  # microAlgos
    print(indexer.sync(address).records_fetched)
    print(indexer.metrics(days=30, account=address).transactions)

AsyncIndexer has the same methods as coroutines.

From the command line:

multichain-indexer index account JCN7TCSQEG6YHAQ7F6BS73J2UDXI2L7S7WJU35LYMIK22IL264ZRJO55QM
Address        JCN7TCSQEG6YHAQ7F6BS73J2UDXI2L7S7WJU35LYMIK22IL264ZRJO55QM
Balance        0.482 ALGO
Min balance    0.3 ALGO
Participation  Offline
Rekeyed to     not rekeyed
ASAs held      2
Apps opted in  0
ASAs created   0
Apps created   0
As of round    68936216

2026-11-03 10:52  5KIYIOY7WTMLMIWC6BVGWBUTQCMXKQDHC7H6Y3CY4CG5ZU2ILBDA  transfer  1000 of ASA 106414664  0.001 ALGO

Algorand

Reads the official Algorand Indexer REST API over aiohttp, which gives async requests and the HTTP status needed to recognise rate limits. py-algorand-sdk (algosdk) handles address validation and encoding, before any request is sent.

Option Meaning
--network testnet The default. Uses Nodely's free public endpoint.
--network mainnet Must be asked for explicitly.
--network localnet AlgoKit LocalNet, at http://localhost:8980.

Set ALGORAND_<NETWORK>_INDEXER_SERVER and ALGORAND_<NETWORK>_INDEXER_TOKEN in .env to use your own endpoint. See .env.example.

Commands

multichain-indexer index account <address>
multichain-indexer index asset <asa-id>
multichain-indexer index app <app-id>
multichain-indexer sync <address>
multichain-indexer metrics --days 30
multichain-indexer export --format parquet --output transactions.parquet

sync stores an account's history, then only fetches rounds it has not seen:

Synced JCN7TCSQEG6YHAQ7F6BS73J2UDXI2L7S7WJU35LYMIK22IL264ZRJO55QM on algorand testnet: 108 transactions up to height 68936400, 3 requests in 1.3s
Synced JCN7TCSQEG6YHAQ7F6BS73J2UDXI2L7S7WJU35LYMIK22IL264ZRJO55QM on algorand testnet: 0 transactions up to height 68936403, 2 requests in 1.0s

metrics works on what has been stored:

{
  "chain": "algorand",
  "network": "testnet",
  "days": 30,
  "account": null,
  "transactions": 24,
  "transactions_per_day": {
    "2026-10-08": 13,
    "2026-10-09": 4,
    "2026-10-12": 4,
    "2026-11-03": 3
  },
  "active_accounts": 3,
  "total_fees": 24000,
  "failure_rate": 0.0,
  "native": {
    "fees_microalgos": 24000,
    "app_calls": 0,
    "asa_opt_ins": 0,
    "group_transaction_share": 0.0,
    "inner_transactions": 0,
    "top_asas_by_transfers": [
      {
        "asa_id": 106414664,
        "transfers": 24
      }
    ]
  }
}

What is recorded

Every transaction has shared fields (id, time, sender, receiver, amount, fee, status, chain, network) and a native block with Algorand's own concepts:

  • ASAs: create, reconfigure, destroy, opt-in, opt-out, transfer, clawback, freeze and unfreeze.
  • Applications: app ID, on-completion, and logs decoded as ARC-4 return values, text or raw bytes.
  • Inner transactions: kept as a tree under their parent.
  • Atomic groups: the group ID.
  • Rekeying: rekey_to on the transaction, and auth_addr on transactions and accounts.
  • Accounts: minimum balance, participation status, ASA holdings.

A few things worth knowing when reading the numbers:

  • amount is in microAlgos for a payment and in the ASA's base units for an asset transfer.
  • fee is the transaction's fee plus those of its inner transactions.
  • Active accounts counts distinct senders.
  • Every record is final: Algorand has instant finality, and a transaction that fails never reaches a block.

Solana

Reads the Solana JSON-RPC API over aiohttp. solders validates public keys, before any request is sent. A mint or program records no creator on-chain, so creator is empty and the mint and upgrade authorities are in native.

Option Meaning
--network devnet The default.
--network testnet The public testnet endpoint.
--network mainnet Must be asked for explicitly.
--network localnet solana-test-validator, at http://localhost:8899.

Set SOLANA_<NETWORK>_RPC_SERVER in .env to use your own endpoint, and SOLANA_<NETWORK>_COMMITMENT to choose confirmed (the default) or finalized.

A sync makes one getTransaction per signature, and public endpoints limit that method tightly: at 1 request per second they still answered HTTP 429, and at 1 every 2 seconds they did not, so that is the default. Raise it with MCI_REQUESTS_PER_SECOND on a dedicated endpoint. If a public endpoint keeps answering 429, the error says so and suggests one. The Solana page has the measurements.

Commands

multichain-indexer --chain solana index account <address>
multichain-indexer --chain solana index token <mint>
multichain-indexer --chain solana index program <program-id>
multichain-indexer --chain solana sync <address>
multichain-indexer --chain solana metrics --days 30
multichain-indexer --chain solana export --format csv --output transactions.csv
Synced FwcsNmTLbf8VVqxuBMjEDTh39gXR87n3vAnAwvAiPtRy on solana devnet: 6 transactions up to height 519016039, 8 requests in 15.2s
Synced FwcsNmTLbf8VVqxuBMjEDTh39gXR87n3vAnAwvAiPtRy on solana devnet: 0 transactions up to height 519016125, 2 requests in 2.8s

Transaction versions

Legacy, v0 and v1 transactions are all read. Priority fees are in lamports for every version, so metrics compare correctly:

Compute unit limit Priority fee
v1 transactionConfig.computeUnitLimit transactionConfig.priorityFee, the total
v0, legacy Compute Budget instruction Compute Budget price per unit, times the limit

What is recorded

The native block holds the slot, transaction version, compute units, priority fee, address lookup tables, every instruction including inner ones, and SOL, SPL Token and Token-2022 transfers. Accounts include their SPL token accounts.

  • amount is the first transfer in the transaction: in lamports, or in a token's base units when native.amount_mint is set. All transfers are in native.
  • sender is the fee payer.
  • status is pending until finalized, then final or failed. Pending records are fetched again on the next sync.

NEAR

NEAR's RPC cannot list an account's transactions, so two sources are used:

Data Source Default
Account state, access keys, chain head NEAR's standard JSON-RPC (view_account, view_access_key_list) dRPC's public endpoints
Account history, with receipts and outcomes An indexing service, chosen by configuration The FastNEAR Transactions API

No API key is needed to start. Read what this history can and cannot promise before relying on it.

Option Meaning
--network testnet The default.
--network mainnet Must be asked for explicitly.
--network localnet A NEAR sandbox at http://localhost:3030. Account and contract lookups only, unless you set a history server.

Set NEAR_<NETWORK>_RPC_SERVER, NEAR_<NETWORK>_HISTORY_SERVER, and NEAR_<NETWORK>_HISTORY_API_KEY in .env. NEAR_<NETWORK>_HISTORY_SOURCE chooses the service; adding another needs one new class, with no change to the parser or to core/.

A history service links many more transactions to an account than an explorer shows. By default a sync keeps the ones the account signed or received, which is the set NearBlocks lists for it. NEAR_<NETWORK>_HISTORY_SCOPE=all also keeps those where the account only received a receipt or is named in an action's arguments or an event log. Metrics count what the syncs stored, so they follow this setting; sync into a new database after changing it.

An RPC endpoint on the wrong network stops with WrongNetwork. The history server's network cannot be checked, so set NEAR_<NETWORK>_HISTORY_SERVER with care.

Commands

multichain-indexer --chain near index account <account-id>
multichain-indexer --chain near index contract <account-id>
multichain-indexer --chain near sync <account-id>
multichain-indexer --chain near metrics --days 30
multichain-indexer --chain near export --format csv --output transactions.csv
Account ID    f781edbfe07287152e3912cb698af4155234df3c2d9c23bf625f675b8f6de5fa
Kind          near-implicit
Exists        yes
Balance       0.732016766023559899999994 NEAR
Staked        0 NEAR
Storage used  182 bytes
Contract      no
Access keys   1 (0 function-call)
Shard         9
As of block   276744703

2026-09-04 07:40  GEZx7KDqDdLbyViv4BvHhKmUSCBmTekLvmM2Q22bkidH  Batch  failed  0.000000000000000000000002 NEAR  0.0004703005168722 NEAR  19.753 Tgas  3
2026-09-04 07:36  HUnm1ZN6wKv3hXgsy3xnTkVwCFiAeoCJ9GH2KjHyaubS  FunctionCall  final  0.000000000000000000000001 NEAR  0.0002665409479373 NEAR  10.190 Tgas  2
Synced f781edbfe07287152e3912cb698af4155234df3c2d9c23bf625f675b8f6de5fa on near testnet: 20 transactions up to height 276744722, 7 requests in 9.4s
Synced f781edbfe07287152e3912cb698af4155234df3c2d9c23bf625f675b8f6de5fa on near testnet: 0 transactions up to height 276744748, 4 requests in 3.5s

What is recorded

The native block holds the block height, every action with its method, decoded arguments, gas and attached deposit, and every receipt with its outcome, logs, gas burnt and tokens burnt. Accounts include their kind, access keys with their permissions, and their shard.

  • amount is the yoctoNEAR attached by the transaction's actions, shown in NEAR.
  • fee is the tokens burnt by the transaction and all its receipts, in yoctoNEAR.
  • sender is the signer. Gas is held in gas units and shown in Tgas.
  • A failed receipt does not always fail its transaction, so both are recorded. status follows the transaction's first receipt, as the protocol does.
  • status is pending until the receipts that decide it have run. Transactions in the last 300 blocks are fetched again on the next sync.

EVM chains

Ethereum, Arbitrum, OP Mainnet, Base, Polygon PoS and BNB Smart Chain share one adapter, with a profile per chain. Every lookup first checks the RPC endpoint's eth_chainId; an endpoint of another network stops with WrongNetwork and names the setting to fix.

--chain Testnet (default) Gas token Tokens
ethereum Sepolia ETH ERC-20
arbitrum Arbitrum Sepolia ETH ERC-20
optimism OP Sepolia ETH ERC-20
base Base Sepolia ETH ERC-20
polygon Amoy POL ERC-20
bnb BNB Smart Chain testnet BNB BEP-20

--network mainnet must be asked for explicitly; --network localnet reads a local node such as Anvil at http://localhost:8545. Set <CHAIN>_<NETWORK>_RPC_SERVER in .env to use your own endpoint. Fees include the L1 data fee on OP Mainnet and Base and the blob fee on blob transactions; the EVM page lists every field.

Commands

multichain-indexer --chain ethereum index account <address>
multichain-indexer --chain ethereum index token <contract>
multichain-indexer --chain base index contract <address>
multichain-indexer --chain ethereum sync <address>
multichain-indexer --chain ethereum metrics --days 30
multichain-indexer --chain ethereum export --format csv --output transactions.csv
Address      0xAA37651031A4b641962550415dB2C43E8d962232
Kind         externally owned account
Balance      0.000000000001 ETH
Nonce        20
As of block  12113523

2026-11-09 17:11  0xa2a58cf2e34c2ec06ba20beeb01120204124fc117e856569d8c5f9475fcd44ec  legacy  final  0.038050303691589778 ETH  0.00000021 ETH  21000  1 ERC-20
2026-03-01 08:06  0xbef676788756bdd8774837d63ef4b7cb2c350fdf8bc6b9a329400da1497d09bf  eip-1559  final  0 ETH  0.000000541183870018 ETH  498707  1 ERC-20
Token         0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14
Standard      ERC-20
Name          Wrapped Ether
Symbol        WETH
Decimals      18
Total supply  193104088539324295320660 base units
As of block   12113524
Synced 0xAA37651031A4b641962550415dB2C43E8d962232 on ethereum testnet: 20 transactions up to height 12113525, 65 requests in 13.9s
Synced 0xAA37651031A4b641962550415dB2C43E8d962232 on ethereum testnet: 0 transactions up to height 12113526, 5 requests in 2.9s

Account history

Standard JSON-RPC cannot list an address's transactions, so a history service lists them. The transactions, receipts and blocks themselves always come from the chain's own RPC, so fields such as l1Fee (OP Mainnet, Base), gasUsedForL1 (Arbitrum) and blob gas (EIP-4844) are read as the chain reports them.

Chain Mainnet Testnet
Ethereum Blockscout Blockscout (Sepolia)
Arbitrum Blockscout Blockscout (Arbitrum Sepolia)
OP Mainnet Blockscout Blockscout (OP Sepolia)
Polygon PoS Etherscan Etherscan (Amoy)
Base Alchemy Alchemy (Base Sepolia)
BNB Smart Chain NodeReal none: NodeReal serves mainnet only, so transactions are read by hash
any chain, --network localnet reads every block over the RPC (Anvil)

<CHAIN>_<NETWORK>_HISTORY_SOURCE switches the service (blockscout, etherscan, nodereal, alchemy or rpc-scan) without a code change. Account and contract lookups need no key; history needs the chosen service's free key:

Setting Where to get it Free plan, as its provider states it
BLOCKSCOUT_API_KEY dev.blockscout.com, no card needed 5 requests a second and 100,000 credits a day (a history page costs 20, so about 5,000 pages); requests fail once the day's credits are used. Base, Polygon and zkSync left the free plan on 1 October 2026.
ETHERSCAN_API_KEY etherscan.io 3 requests a second, 100,000 a day, at most 1,000 records a request since 1 July 2026. Selected chains only.
ALCHEMY_API_KEY dashboard.alchemy.com, no card asked on sign-up 30 million compute units a month and 300 a second (the dashboard shows 25 requests a second). alchemy_getAssetTransfers costs 120, so about 250,000 calls a month; this project sends two a second, and 30 calls at 2, 4 and 8 a second drew no refusal. Each call covers at most 1,000,000 blocks, sent and received transactions are separate calls, and internal transfers are not listed on Base.
NODEREAL_API_KEY dashboard.nodereal.io, no card asked on sign-up 10 million compute units a month and 150 a second per key. nr_getAssetTransfers costs 250, so about 40,000 calls a month; this project sends one every 2 seconds. Each call covers at most 1,000,000 blocks (the service refuses 2,000,000 or more), and sent and received transactions are separate calls, so a first sync of a long history takes many calls.

What each free plan answered on 11 November 2026, with one request per network:

Network Blockscout Etherscan
Ethereum, Sepolia yes yes
Arbitrum One, Arbitrum Sepolia yes yes
OP Mainnet yes no, paid plan
OP Sepolia yes yes
Base Mainnet no, HTTP 402 no, paid plan
Base Sepolia no, HTTP 402 yes, although Etherscan lists it as paid
Polygon PoS mainnet no, HTTP 402 yes
Amoy not listed yes
BNB Smart Chain, mainnet and testnet not listed no, paid plan

Free plans change: a source that answers today may need a paid plan later. Each provider's terms apply to your key, not this project's:

  • Etherscan (API terms): the free plan is for personal and research use only; anywhere you display or publish data obtained through it, show "Powered by Etherscan.io APIs" with a link to etherscan.io (not needed for purely private use); do not bulk-download, mirror or archive its data, pass it on to third parties through a proxy, or put your key in public code. index account prints that line under transactions Etherscan listed, and every such record carries native.history_source = "etherscan", also in CSV, JSON and Parquet exports.
  • Blockscout (terms): no API-specific clause on attribution or storing results was found. The licence is revocable, and access or limits can change without notice.
  • NodeReal (terms): no clause on attribution, caching or redistribution was found. The key sits in the endpoint URL; this project keeps it out of messages and logs, but treat any URL you copy from your dashboard as a secret.
  • Alchemy (terms, version 2.0 of 27 June 2025), for Base history: use is "solely for your internal business purposes" (2.1); you may not resell, mirror or let others use the service (2.2(v)), scrape it or use crawlers (2.2(viii), (xi)), or spread use across accounts to get past limits (2.2(x)); the free tier is "as is" and can end at any time (2.11); on termination, Alchemy's confidential information must be destroyed (11.6), which may include data you stored from it. No attribution or caching clause was found. Each user's own key, fetching history for that user into a local database, appears to fit these terms; read them yourself before relying on that.

A history service is a third party: it can be behind the chain, list a transaction the RPC does not have yet, or change its limits. A listed transaction the RPC does not have is left out and fetched on a later sync.

Which transactions count

<CHAIN>_<NETWORK>_HISTORY_SCOPE chooses them:

Scope Keeps Extra cost per history page
direct (default) transactions the address sent or received none
all also those that moved an ERC-20 (BEP-20) token to or from the address inside someone else's contract call Blockscout and Etherscan: a second call, tokentx, so twice the calls (Blockscout charges 20 credits each, 40 a page); NodeReal and Alchemy: none, the same calls ask for BEP-20 or ERC-20 transfers too (250 and 120 compute units each)

Every extra transaction also costs three RPC reads (transaction, receipt, block). The block scan used on localnet lists direct transactions only. NFT transfers inside other calls are not added. Sync into a new database after changing the scope: stored records stay as they are.

Post-quantum signatures

Algorand transactions signed by native Falcon-1024 accounts (pqsig, scheme f1) and NEAR keys and transactions using ML-DSA-65 carry a pq field in their native block, and metrics report their share. Nothing else is live on any planned chain yet.

multichain-indexer pq-status

Each row of its output has the chain's status, its source and the date it was checked. The post-quantum page has the full table, what is counted, and its limits.

How it is built

multichain_indexer/
  api.py            Indexer and AsyncIndexer, the public API
  cli.py            the command line, which only calls api.py
  core/             shared code that knows nothing about a specific chain
    base_indexer.py   the contract every adapter implements
    registry.py       chain name to adapter
    pipeline.py       fetch, store, summarise; incremental sync
    storage.py        SQLite behind a storage interface
    metrics.py        pandas metrics any chain can use
    export.py         CSV, JSON and Parquet
    http.py           timeouts, retries, Retry-After
    ratelimit.py      per-endpoint request pacing
    cache.py          optional cache for data that can never change
    config.py         settings from .env and the environment
    observability.py  structured logs with secrets masked
  adapters/algorand/  client, parser, metrics
  adapters/solana/    client, parser, metrics
  adapters/near/      client, parser, metrics, and pluggable history sources
  pq/                 post-quantum detection shared by the adapters, and each chain's status

A sync can be stopped at any point and picks up where it left off. It walks a fixed range of rounds, and each page's records and the cursor for the next page are saved in one database transaction, so the two can never disagree. Writes are upserts, so nothing is stored twice, and the checkpoint only moves once the whole range is stored. While a sync runs it shows a running count, because the total is not known in advance.

Security

  • This version reads public data only. It does not handle private keys and cannot sign or send anything.
  • Endpoint URLs and tokens come from .env or the environment. They are masked in logs and left out of error messages.
  • .env is parsed, not loaded, so its values are never copied into the process environment.
  • Plain http endpoints are refused, except on localhost.
  • Addresses and IDs are validated before any request is sent.

See SECURITY.md to report a vulnerability.

Development

uv sync
uv run pytest

Tests use saved testnet responses and need no network. uv run pytest -m live --no-cov runs the ones that talk to testnet. CONTRIBUTING.md has the rest.

Roadmap

Version Adds
0.1 Core and Algorand
0.2 Solana: SPL tokens, programs, compute units, priority fees
0.3 NEAR: named accounts, receipts, function calls, access keys
0.4 Post-quantum readiness: Falcon-1024 on Algorand, ML-DSA-65 on NEAR, a dated status for every chain
0.5 EVM chains: Ethereum, Arbitrum, Optimism, Base, Polygon PoS, BNB Smart Chain
0.6 Bitcoin: UTXOs, address types, fee rates, quantum-exposed outputs
0.7 Cross-chain metrics and reports, PostgreSQL, a read-only HTTP API, follow mode, plugins, Docker
0.8 A local dashboard over your own database, on localhost only
0.9 Wallet utilities: pre-flight checks, simulation, signing on test networks first
1.0 Stable release on PyPI, with a docs page and demo per chain

License

Apache-2.0

Metadata

Release files for multichain-analytics-indexer 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for multichain-analytics-indexer 0.5.0
File Size Uploaded Provenance Actions
multichain_analytics_indexer-0.5.0.tar.gz 716.4 kB With provenance Details for multichain_analytics_indexer-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for multichain-analytics-indexer 0.5.0
File Interpreter ABI Platform Actions
multichain_analytics_indexer-0.5.0-py3-none-any.whl Python 3 none any Details for multichain_analytics_indexer-0.5.0-py3-none-any.whl

Total release size: 842.7 kB

Release files / multichain_analytics_indexer-0.5.0.tar.gz

Download URL multichain_analytics_indexer-0.5.0.tar.gz
Size 716.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fd07ca0e5f2508523c0610bcd56beb580346093d3a37a4a352c19d9bbeab5472
BLAKE2b-256 checksum
How to use checksums
21b54e7f91b7d234cd2d30aba37e7ccb421ede4501e111b6846f14561c3914db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / multichain_analytics_indexer-0.5.0-py3-none-any.whl

Download URL multichain_analytics_indexer-0.5.0-py3-none-any.whl
Size 126.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
be850141a4d44bb4d67bc1222c496d57c03b2e26820ab43937749ab06e85e675
BLAKE2b-256 checksum
How to use checksums
b11720f087768baa0454d717f8031e4eea189776ccd9d37a6379531d3d079174
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for multichain-analytics-indexer 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for multichain_analytics_indexer-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page