Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

StreamingFast Firehose for EOSIO

reference License


  • single integration for accessing history and real-time, low-latency stream of live block data
  • simplify your code that handle the irregularities of blockchains (our customers said 90% less code is needed when using this system)
  • get rid of your complex message queues deployments
    • have your Kafka consumers talk directly to the Firehose, less latency, and simpler
    • replace RabbitMQ, and have consumers filter their topics directly from the Firehose
    • extremely precise and fork-aware checkpointing for consumers


See documentation:

In bash:


export DFUSE_TOKEN=$(curl -s --data-binary '{"api_key":"'$DFUSE_KEY'", "lifetime": 86400000}' | jq -r .token);

In Python:

Download the service protobuf

curl -O
curl -O
curl -O
curl -O

Try it from the CLI

Stream of irreversble blocks from the past:

    grpcurl -H "Authorization: Bearer $DFUSE_TOKEN" \
       -d '{"start_block_num": 138000000, "stop_block_num": 139000000, "fork_steps": ["STEP_IRREVERSIBLE"], "include_filter_expr": ""}' \
       -import-path . \
       -proto bstream.proto \
       -proto codec.proto \
       $SERVICE_ENDPOINT:443 \
       dfuse.bstream.v1.BlockStreamV2.Blocks | jq .

Use include_filter_expr to choose exactly what you need.

If the connection is interrupted, your process crashes or whatever, continue where you left off by passing the last block_num you received back into start_block_num (+1)

    grpcurl -H "Authorization: Bearer $DFUSE_TOKEN" \
       -d '{"start_block_num": 138500000, "stop_block_num": 139000000, "fork_steps": ["STEP_IRREVERSIBLE"], "include_filter_expr": ""}' \
       -import-path . \
       -proto bstream.proto \
       -proto codec.proto \
       $SERVICE_ENDPOINT:443 \
       dfuse.bstream.v1.BlockStreamV2.Blocks | jq .

Query language

The language used in the include_filter_expr and exclude_filter_expr is a Common Expression Language expression, as defined here:

Queries match on individual actions, and transactions are returned if one action matches the filter query. You can then check the filtering_matched field on the ActionTrace protobuf object to make sure they are relevant to your query.

Fields that are available for filtering:

  • auth: a list of strings, authorizers for a given action
  • receiver: string, the contract being executed
  • action: string, the name of the action being executed
  • input: bool, whether this is a top-level action
  • notif: bool, whether this is a notification
  • data['field']: any, matches some data from the action parameters

Sample queries

Match transactions that notified or executed on a list of contracts:

account in ['newdexpublic','','','','','','','','','','','','','','swap.defi']

Match transactions that werw authorized (signed) by certain accounts:

auth.exists (x, x in ['newdexpublic','','','','','','','','','','','','','','swap.defi'])

Ignore some of the mining activity on chain:

!(trx_action_count > 200 && top5_trx_actors.exists(x, x in ['eosiopowcoin','eidosonecoin','mine4charity']))

Here, in combination:

!(trx_action_count > 200 && top5_trx_actors.exists(x, x in ['eosiopowcoin','eidosonecoin','mine4charity'])) && (account in ['newdexpublic','','','','','','','','','','','','','','swap.defi'] || receiver in ['newdexpublic','','','','','','','','','','','','','','swap.defi'] || auth.exists (x, x in ['newdexpublic','','','','','','','','','','','','','','swap.defi']))


Issues and PR in this repo related strictly to Firehose for EOSIO.

Report any protocol-specific issues in their respective repositories

Please first refer to the general StreamingFast contribution guide, if you wish to contribute to this code base.


Apache 2.0


Playground to play with EOSIO Firehose service (with stats







No releases published


No packages published