NAV Navbar
shell

Introduction

Welcome to the dfuse API documentation — WebSocket and REST API for EOS

dfuse API documentation — WebSocket and REST API for EOS


Welcome to the dfuse API documentation — WebSocket and REST API for EOS

Build your project on EOS with dfuse — the most powerful Streaming and REST API, to provide the best experience to your users. Works on EOS Mainnet, CryptoKylin and Jungle 2.0 Networks. Get a free dfuse API key for EOS to start.


Alternative Resources

Endpoints

The dfuse API is available for multiple EOSIO networks. Should you need it on another network, contact us.

EOS Mainnet

Endpoints for the EOS Mainnet (chain ID: aca376f2...)
WebSocket wss://mainnet.eos.dfuse.io/v1/stream
REST https://mainnet.eos.dfuse.io/

CryptoKylin Network

Endpoints for the CryptoKylin Network (chain ID: 5fff1dae...)
WebSocket wss://kylin.eos.dfuse.io/v1/stream
REST https://kylin.eos.dfuse.io/

Jungle 2.0 Network

Endpoints for the Jungle 2.0 Network (chain ID: e70aaab8...)
WebSocket wss://jungle.eos.dfuse.io/v1/stream
REST https://jungle.eos.dfuse.io/

Authentication

First, get a Free API Key (a JWT) on https://www.dfuse.io

In all the following examples, replace YOURTOKENHERE with your personal API key.

With both WebSocket and REST API calls, you can authenticate with a token in the query string parameter or with an HTTP header

Query string

This example uses the https://github.com/hashrocket/ws command-line WebSocket program.

To authenticate with query string, use this code:

$ ws -o https://b2b.dfuse.io wss://mainnet.eos.dfuse.io/v1/stream?token=eyJ..YOURTOKENHERE...

You can pass the token query string parameter to authenticate REST or WebSocket requests.

Bearer token

Specify the Authorization: Bearer [token] header in the HTTP request. See more details.

Pass Bearer token like this:

$ eosc -H "Authorization: Bearer eyJ...YOURTOKENHERE..." -u https://mainnet.eos.dfuse.io [ ... ]

Origin required for WebSocket connections

An Origin HTTP request header (ex. Origin: https://yourcompany.com) is mandatory when initiating a WebSocket connection to our endpoints. A 403 error being returned when not present. Expect that Origin header requirement will start to be enforced as we transition from the initial Beta phase to General Availability in the near future. As the Origin header becomes enforced, it will need to match the origins you will register along with your API key identity. More details will come soon.

WebSocket-based API

The websockets-based API fuses batch processing and streaming capabilities to give you one single endpoint with strong guarantees.

Most operations can fetch a first state (with fetch: true), and stream subsequent changes (with listen: true).

Request message format

All requests are formed with these parameters, where type is the type of the request, and req_id is a token referred to by future commands (client or server).

Sample request message:

{
 "type": "[REQUEST_NAME]"`,
 "req_id": "some-string-of-your-choosing",
 "fetch": true,
 "listen": true,
 "start_block": -500,
 "with_progress": 5,
 "data": {...}
}

These parameters are available for most commands (unless otherwise noted):

Name Type Options Description
type string required The type of the message. See request types below.
data object required A free-form object, specific to the type of request. See request types below.
req_id string optional An ID to associate responses back with the request
start_block number (integer) optional Block at which you want to start processing. It can be an absolute block number, or a negative value, meaning how many blocks from the current head block on the chain. Ex: -2500 means 2500 blocks in the past, relative to the head block. See Never missing a beat
fetch boolean optional, defaults to false Whether to fetch an initial snapshot of the requested entity.
listen boolean optional, defaults to false Whether to start listening on changes to the requested entity.
with_progress number (integer) optional Frequency of the progress of blocks processing (within the scope of a req_id). See Never missing a beat

Never missing a beat

Sometimes, disconnections happen. Indeed, you will want to plan for disconnections.

Thankfully, the dfuse API has you covered, with the following WebSocket parameters:

Using with_progress

When you specify with_progress as part of the request message, you will start receiving messages of type progress when blocks arrive. The value you pass is interval of blocks you want to get that message, or the precision. A value of 5 means you will receive one progress message each 5 blocks. Set it to 1 to receive a message for each block.

For a given req_id stream, you are guaranteed to see the progress message after you have received any matching data within that block.

Also, you will receive one notification each 250 milliseconds at maximum. This means you will not get one progress message per block when doing massive historical reprocessing.

Using start_block

By specifying start_block, you can request that the stream of events starts in the past. You might need API keys that allow such reprocessing (until we have a self-serve portal, contact us if such is the case).

Possible values:

Standard keys can process 3600 blocks in the past by default.

Navigating forks

The dfuse API allows remote endpoints to navigate forks without fuss, with the guarantee that you will receive all the information you need to stay in sync with the head of the chain.

For example, the get_table_rows will emit step: "undo" and step: "redo" when a chain switches from one fork to another. If you apply changes to a local map of rows, you will always be in sync with the latest changes (see notes about undo flipping the database operations). Meaning of step:

Again, transaction_lifecycle events will be emitted when the transaction you are watching was in a block that was forked out, or forked back in.

Request message types

Here is a list of all request message types available:

get_action_traces

Retrieve a stream of actions, filtered by receiver and account

Example request

{
  "type": "get_action_traces",
  "listen": true,
  "req_id": "your-request-id",
  "data": {
    "accounts": "eosio.token",
    "action_name": "transfer",
    "with_inline_traces": true,
    "with_dtrxops": true,
    "with_ramops": true
  }
}

Request input data fields:

Name Type Options Description
accounts string required Pipe | separated list of accounts (contracts) to filter on.
receivers string optional, defaults to the same value as accounts Pipe | separated list of receiver to filter on. The receiver is the account on which code is being executed. More details here. If left blank, defaults to the same value as account.
action_names string optional Name of the action called within the account contract.
with_ramops boolean optional Stream RAM billing changes and reasons for costs of storage produced by each action.
with_inline_traces boolean optional Stream the inline actions produced by each action.
with_dtrxops boolean optional Stream the modifications to deferred transactions produced by each action.

Responses

get_transaction_lifecycle

Retrieve a "transaction_lifecycle" (when "fetch" is true) and follow its life-cycle (with "listen" is true)

When following a transaction, any new block referencing that transaction will trigger an updated version of "transaction_lifecycle" to be sent. When one of those blocks passes irreversibility, you will also receive an updated transaction_lifecycle object.

Request input data fields:

Example request

{"type": "get_transaction", "fetch":true, "listen": true, "data": {"id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24"}}
Name Type Options Description
id string required The transaction ID you want to keep track of

Responses

On both fetch: true and listen: true requests, dfuse will stream back TransactionLifecycle objects.

get_table_rows

Retrieve a stream of changes to the tables, the side effects of transactions/actions being executed

Guarantees

When asking fetch: true and listen: true, you will receive a consistent snapshot (response message type table_snapshot) of the whole table at block start_block (or head block if start_block is omitted), followed by table_delta response messages that have occured after the snapshot.

If you are looking to fetch a snapshot only, see the REST API for state snapshots below.

Handling of forks

Request input data fields:

Example request

{"type": "get_table_rows",
 "req_id": "your-request-id",
 "fetch": true,
 "listen": true,
 "data": {
   "code": "eosio.token",
   "scope": "eoscanadacom",
   "table": "accounts",
   "json": true
}}
Name Type Options Description
code AccountName required Contract account which wrote to tables.
scope Name required Table scope where table is stored.
table Name required Table name, shown in the contract ABI.
json boolean optional With json=true (or 1), table rows will be decoded to JSON, using the ABIs active on the queried block. This endpoint automatically adapts to upgrades to the ABIs on chain.

Responses

Handling of forks

When navigating forks in the chain, dfuse sends TableDeltaResponse updates with the step field set to undo and redo. When doing an undo, dfuse actually flips the operation (INS becomes REM, UPD sees its old and new fields swapped, and REM becomes INS), so you can simply process the incoming stream as if it was normal actions.

If you want to be aware of the chain reorganizations, verify the step field on the TableDeltaResponse object.

get_head_info

Retrieve a stream of informations about the chain as it moves forward

Request input data fields:

Example request

{
  "type": "get_head_info",
  "listen": true,
  "req_id": "your-request-id"
}

None.

Responses

When requesting listen: true, dfuse will stream HeadInfo objects.

unlisten

To interrupt a stream, you can unlisten with the original req_id like this:

Request input data fields:

Request example:

{"type": "unlisten", "data": {"req_id": "your-request-id"}}
Name Type Options Description
req_id string required The req_id passed to previous commands which included listen=true

Responses first level data fields:

Example unlistened payload:

{"type":"unlistened","data":{"success":true}}

If unlistened fails, you will receive a normal error message.

ping

Once connected to the websocket, every 10 seconds, you get a ping response from the server

{"type":"ping","data":"2018-01-01T00:00:10.526391919Z"}

Responses

These are the messages you can receive from the server.

listening

{
 "type":"listening",
 "req_id": "your-request-id",
 "data":{
  "next_block":26736683
 }
}

Confirmation that server will continue processing block with height starting at next_block and emit more messages on current stream.

Use unlisten request to stop streaming for req_id

progress

{
 "type":"progress",
 "req_id": "your-request-id",
 "data": {
    "block_num": 29351730,
    "block_id": "01bfdf32469f6f48ca2e5e5c755422c7da0bbc33f1e470c034daffd460a2a58d"
 }
}

Confirmation that server will continue processing block with height starting at next_block and emit more messages on current stream.

Use unlisten request to stop streaming for req_id

error

{"type": "error",
 "data": {
  "code": "tx_not_found",
  "message": "transaction_lifecycle 'abcdef123123123...' not found, or error fetching transaction",
  "details": {"tx_id": "abcdef123123123..."}
}}

If an error occurs during the request, you'll get an error response

REST API

The dfuse REST API includes the following endpoints:

To use the API, you must pass your dfuse API token in a HTTP Header, like the following:

curl -H "Authorization: Bearer yJhbGciOiJLTVNFUzI1NiIsI....." "https://endpoint..."

POST push_transaction

/v1/chain/push_transaction

Pushes a transaction to the blockchain, with the possibility to request additional guarantees:

The content of the request and response is identical to the regular "push_transaction" endpoint, except:

Status of support for cleos

cleos --header "X-Eos-Push-Guarantee: in-block" push transaction mytx.json
cleos --header "X-Eos-Push-Guarantee: handoffs:2" --header "Authorization: Bearer YOURTOKENHERE" push transaction mytx.json

You need cleos version 1.4.1 or higher to use the X-Eos-Push-Guarantee feature.

Older version of cleos have an issue addressed in this PR

eosc -H "Authorization: Bearer YOURTOKENHERE" -H "X-Eos-Push-Guarantee: irreversible" -u "https://mainnet.eos.dfuse.io" tx push mytx.json
eosc -H "Authorization: Bearer YOURTOKENHERE" -H "X-Eos-Push-Guarantee: handoffs:3" -u "https://mainnet.eos.dfuse.io" transfer sourceaccount destination 5

You can always use eosc to use the feature:

Deferred transactions

In the case of a transaction set with a non-zero delay_sec, the guarantee is set on the "scheduling" step of that transaction, not its execution (which could be far off in the future.)

The returned traces are also the traces of that "scheduling" step, from the block, and not the speculative execution of the edge node.

GET /v0/search/transactions

NOTE: dfuse Search is in BETA

Search an EOSIO blockchain for transactions based on free-form criterias, using the simple dfuse Search query language.

NOTE: right now, SQE will provide search only in irreversible actions. It will be extended to longest-chain search, and real-time search later.

Sample request:

curl --get \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "start_block=0" \
     --data-urlencode "block_count=10000" \
     --data-urlencode "limit=10" \
     --data-urlencode "sort=desc" \
     --data-urlencode "q=receiver:eosio.token action:transfer data.to:someaccount1" \
     "https://mainnet.eos.dfuse.io/v0/search/transactions"

Pagination

The dfuse Search supports stable pagination through the use of the cursor parameter. If your request yields results and there are more to come, the response will contain a non-empty cursor field (which looks like opaque base64-encoded data).

To fetch the next batch, pass the cursor in the next request, while keeping all other parameters identical to the first query. You can tweak the limit as you go, and the cursor will allow you to continue where you left off, without missing anything between the two queries: something that is impossible to do with only an offset parameters, in a moving chain.

When doing searches in the moving part of the chain (the head), it is possible that some results previously returned are not forked out (because some of its blocks are ignored by block producers for some reasons). If you pass the cursor properly, the pagination system will verify that it has not given you any such results.

If there are the slightest chance that you had received results that didn't make it to the chain, the forked_head_warning parameter will be set to true in the response. It is then appropriate to inform your user that it is possible that some results are now stale, and to refresh their page or something similar.

To avoid such situation, use with_reversible=false in your query (the default), to search only irreversible blocks and transactions: in that case, there are no chances that you get results that would suddenly disappear.

Input parameters

Name Type Options Description
q string required Search query string. See Search language specs for details.
start_block number (uint32) optional Block number to start search (inclusive). Defaults to 0, which means Last Irreversible Block (tip of the chain).
sort string optional Defaults to ascending search. Use DESC to sort descending.
block_count number (uint32) optional Number of blocks to search from start_block. Depending on sort order, the block_count will count upwards or downwards.
limit number (uint64) optional Cap the number of returned results to limit. Defaults to 100.
cursor string optional If cursor is passed back (from a previous response)
with_reversible boolean optional If with_reversible is set to true actions included in blocks that are not yet irreversible will be included.

By default, a query that does not specify start_block nor sort, the results will be ascending (block-wise and transaction-wise)

Response

Returns a SearchTransactionsResponse.

GET /v0/state/abi

Fetches the ABI for a given contract account, at any block height.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/abi?account=eosio&json=true"

Requesting past blocks

The block_num parameter determines for which block you want the given ABI. This can be anywhere in the chain's history.

If the requested block_num is irreversible, you will get an immutable ABI. If the ABI has changed while still in a reversible chain, you will get this new ABI, but it is not guaranteed to be the view that will pass irreversibility. Inspect the returned block_num parameter of the response to understand from which longest chain the returned ABI is from.

The returned ABI is the one that was active at the block_num requested.

Input parameters

Name Type Options Description
account AccountName required Contract account targeted by the action.
block_num number optional, defaults to head block num The block number for which you want to retrieve the ABI. The returned ABI will be the one that was active at this given block_num.
json boolean optional, defaults to false Returns the ABI in JSON form if set to true. When set to false, the packed ABI is returned in hexadecimal string form.

Response

Here is a sample response, for a request at block_num: 8000:

{
  "block_num": 8000,
  "account": "eosio.token",
  "abi": {
    "version": "eosio::abi/1.0",
    ...
  }
}
Name Type Options Description
block_num string required Block number closest to block_num at which the ABI was put on chain. For example, if ABI was last changed at block 1000 and you used a block_num of 20000 in the request, the response block_num will be 1000.
account AccountName required Contract account this ABI is active for.
abi object required A hexadecimal string (or JSON if json=true) representation of the ABI that is stored within the account. It is the ABI in effect at the requested block_num.

GET /v0/state/abi/bin_to_json

Decode the ABI for a given contract account, at any block height.

Sample request:

curl -X POST -H "Authorization: Bearer $TOKEN" \
    -d '{"account":"eosio.token","table":"accounts","block_num":2500000,"hex_rows":["aa2c0b010000000004454f5300000000"]}' \
    "https://mainnet.eos.dfuse.io/v0/state/abi/bin_to_json"

Requesting past blocks

The block_num parameter determines for which block you want to decode rows against. This can be anywhere in the chain's history.

If the requested block_num is irreversible, decoding will be performed against an immutable ABI. If the ABI has changed while still in a reversible chain, decoding will be performed against this new ABI, but it is not guaranteed to be the view that will pass irreversibility. Inspect the returned block_num parameter of the response to understand from which longest chain the returned ABI is from.

Input body

The input body must be a valid JSON object. Here are the fields accepted in this JSON object.

Name Type Options Description
account AccountName required Contract account targeted by the action.
table TableName required The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
block_num number optional, defaults to head block num The block number for which you want to retrieve the ABI. The returned ABI will be the one that was active at this given block_num.
hex_rows array<string> required An array of hexadecimal rows to decode. Each row must be a valid hexadecimal string representation of the row to decode against the ABI.

Response

Here is a sample response, for a request at block_num: 8000:

{
  "block_num": 181,
  "account": "eosio.token",
  "table": "accounts",
  "rows": [
    {
      "balance": "1750.9546 EOS"
    },
    ...
  ]
}
Name Type Options Description
block_num string required Block number closest to block_num at which the ABI was put on chain. For example, if ABI was last changed at block 1000 and you used a block_num of 20000 in the request, the response block_num will be 1000.
account AccountName required Contract account this ABI is active for.
table TableName required Contract table the rows were decoded against.
rows array<object> required An array of decoded rows. Each element in the array is the decoded JSON representation of the encoded data against the active ABI at the requested block_num. Order of hex_rows request parameter is preserved.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/permission_links?account=eoscanadacom&block_num=10000000"

Fetches snapshots of any account's linked authorizations on the blockchain, at any block height.

The block_num parameter determines for which block you want a linked authorizations snapshot. This can be anywhere in the chain's history.

If the requested block_num is irreversible, you will get an immutable snapshot. If the block_num is still in a reversible chain, you will get a full consistent snapshot, but it is not guaranteed to be the view that will pass irreversibility. Inspect the returned up_to_block_id parameter to understand from which longest chain the returned value is a snapshot of.

Name Type Options Description
account AccountName required Account to query linked permissions from.
block_num number (uint32) optional, defaults head block num The block number for which you want to retrieve the consistent linked permissions snapshot.

Here is a sample response, for a request at block_num: 8:

{
  "up_to_block_id": "0000001000000000000000000000000000000000000000000000000000000000",
  "up_to_block_id": 8,
  "last_irreversible_block_id": "0000000400000000000000000000000000000000000000000000000000000000",
  "last_irreversible_block_num": 4,
  "linked_permissions": [
    {
      "contract": "eosio",
      "action": "claimrewards",
      "permission_name": "claimer"
    }
  ]
}
Name Type Options Description
up_to_block_id string optional Block ID at which the snapshot was taken when querying the reversible chain segment. This will not be present if querying blocks older than the last irreversible block.
up_to_block_num number (uint32) optional Block number extracted from up_to_block_id if present, provided as a convenience so you don't need to extract it yourself.
last_irreversible_block_id string optional Last irreversible block considered for this request. The returned snapshot is still for the requested block_num, even though the irreversible block shown here is more recent.
last_irreversible_block_num number (uint32) optional Block number extracted from last_irreversible_block_num, provided as a convenience so you don't need to extract it yourself.
linked_permissions array<LinkedPermission> required An array of linked permissions for the account, sorted by the contract field and on action when there is a tie at the contract level.

Name Type Options Description
contract AccountName required Contract's account on which the permission is applied.
action ActionName required Action on which the permission is applied.
permission_name PermissionName required Permission name that is required to perform the contract/action pair above.

GET /v0/state/table

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/table?account=eosio.token&scope=b1&table=accounts&block_num=25000000&json=true"

Fetches the state of any table, at any block height.

Requesting past blocks

The block_num parameter determines for which block you want a table snapshot. This can be anywhere in the chain's history.

If the requested block_num is irreversible, you will get an immutable snapshot. If the block_num is still in a reversible chain, you will get a full consistent snapshot, but it is not guaranteed to be the view that will pass irreversibility. Inspect the returned up_to_block_id parameter to understand from which longest chain the returned value is a snapshot of.

ABI handling

The dfuse API tracks ABI changes and will decode each row with the ABI in effect at the block_num requested.

Rows are decoded only if json: true is passed. Otherwise, hexadecimal of its binary data is returned instead.

If you requested a json-decoded form but it was impossible to decode a row (ex: the ABI was not well formed at that block_num), the hex representation would be returned along with an error field containing the decoding error.

Input parameters

Name Type Options Description
account AccountName required Contract account targeted by the action.
scope AccountName required The name-encoded scope of the table you are requesting. For example, user balances for tokens live in their account name's scope. This is contract dependent, so inspect the ABI for the contract you are interested in.
table TableName required The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
block_num number optional, defaults to head block num The block number for which you want to retrieve the consistent table snapshot.
json boolean optional, defaults to false Decode each row from its binary form into JSON. If json: false, then hexadecimal representation of its binary data is returned instead.
key_type string optional, defaults to name, see KeyType for valid values How to represent the row keys in the returned table.
with_block_num boolean optional, defaults to false Will return one block_num with each row. Represents the block at which that row was last changed.
with_abi boolean optional, defaults to false Will return the ABI in effect at block block_num.

Key Type

The key type can be one of the following values:

Response

Returns a StateResponse

Table Row

Name Type Options Description
key string required The encoded key (as requested with key_type) for the row
payer AccountName required The name-encoded account that was billed RAM to store this row.
block number (uint32) optional The block num when this row was last modified (as requested by with_block_num).
json Object optional, present when json: true and ABI decoding succeeded, absent otherwise A JSON representation of the binary data, decoded through the active ABI at that block height.
hex string optional, present when json: false, absent otherwise A string-encoded hexadecimal representation of the binary data in that row.
error string optional An error string in case the binary data failed to be decoded through the ABI.

Each row will have one of hex or json present.

GET /v0/state/tables/accounts

Fetches a table from a group of contract accounts, at any block height.

Most parameters are similar to the /v0/state/table request, except for the accounts parameter, which accepts a list of account separated by the pipe character (|).

The output format is slightly different too.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/tables/accounts?accounts=eosio.token|eosadddddddd|tokenbyeocat|ethsidechain|epraofficial|alibabapoole|hirevibeshvt|oo1122334455|irespotokens|publytoken11|parslseed123|trybenetwork|zkstokensr4u&scope=b1&table=accounts&block_num=25000000&json=true"

Requesting past blocks & ABI handling

This request exhibits the same patterns as the simpler /v0/state/table query.

Input parameters

Name Type Options Description
accounts string required An AccountName list, separated by the pipe character |, a maximum of 1500 elements can be present in the list.
scope Name required The name-encoded scope of the table you are requesting. For example, user balances for tokens live in their account name's scope. This is contract dependent, so inspect the ABI for the contract you are interested in.
table TableName required The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
block_num number optional, defaults to head block num The block number for which you want to retrieve the consistent table snapshot.
json boolean optional, defaults to false Decode each row from its binary form into JSON. If json: false, then hexadecimal representation of its binary data is returned instead.
key_type string optional, defaults to name How to represent the row keys in the returned table.
with_block_num boolean optional, defaults to false Will return one block_num with each row. Represents the block at which that row was last changed.
with_abi boolean optional, defaults to false Return the ABI in effect at block block_num.

Key Type

The key type can be one of the following values:

Response

Returns a MultiStateResponse, same as the multi-scopes endpoint.

GET /v0/state/tables/scopes

Fetches a table for a given contract account for a group of scopes, at any block height.

Most parameters are similar to the /v0/state/table request, except for the scopes parameter, which accepts a list of name-encoded scopes separated by the pipe character (|).

The output format is slightly different too.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/tables/scopes?account=eosio&scopes=eosio.token|eosadddddddd|tokenbyeocat|ethsidechain|epraofficial|alibabapoole|hirevibeshvt|oo1122334455|irespotokens|publytoken11|parslseed123|trybenetwork|zkstokensr4u&table=delband&block_num=25000000&json=true"

Requesting past blocks & ABI handling

This request exhibits the same patterns as the simpler /v0/state/table query.

Input parameters

Name Type Options Description
account AccountName required Contract account targeted by the action.
scopes string required A Name list, separated by the pipe character |, a maximum of 1500 elements can be present in the list.
table TableName required The name-encoded table name you want to retrieve. For example, user balances for tokens live in the accounts table. Refer to the contract's ABI for a list of available tables. This is contract dependent.
block_num number optional, defaults to head block num The block number for which you want to retrieve the consistent table snapshot.
json boolean optional, defaults to false Decode each row from its binary form into JSON. If json: false, then hexadecimal representation of its binary data is returned instead.
key_type string optional, defaults to name How to represent the row keys in the returned table.
with_block_num boolean optional, defaults to false Will return one block_num with each row. Represents the block at which that row was last changed.
with_abi boolean optional, defaults to false Return the ABI in effect at block block_num.

Key Type

The key type can be one of the following values:

Response

Returns a MultiStateResponse, same as the multi-accounts endpoint.

Search query language specs

dfuse Search uses a simplified query language to reach unparalleled and predictable performances.

It is similar to GitHub's query language for issues and pull requests: it has a default AND operator between each query term. Search adds a simple, one-level OR layer enclosed in parentheses.

You can enclose parameters using double-quotes after the :, or use a single keyword. For example: auth:eoscanadacom or auth:"eoscanadacom".

Boolean support: only true and false have special meaning when not using quotes: input:true queries for a boolean value, while input:"true" searches for a string value.

Example queries

Available query fields

These are the prefixes or fields available for query:

Types

The types section defines all object structures and their meaning.

Name

An Name is a string that represents a uint64 value, name-encoded using the base32 algorithm. It can only include characters a through z and/or numbers from 1 to 5, and the dot . character. It has a maximum length of 12 or 13 characters (depending on the contents).

AccountName

An AccountName is a Name-encoded string that represents an account on the chain.

ActionName

An ActionName is a Name-encoded string that represents a contract's action.

PermissionName

A PermissionName is a Name-encoded string that represents a valid permission on the chain.

TableName

A TableName is a Name-encoded string that represents a contract's table on the chain.

TableSnapshotResponse

Example table_snapshot response payload:

{"type": "table_snapshot",
 "req_id": "your-request-id",
 "data": {
  "rows": [
   {
    ...
   }]
}}
Name Type Options Description
type string required The table_snapshot string
data TableRows required Rows for the corresponding get_table_rows request. The TableRows object will not contain account nor scope in this case.

TableRows

Name Type Options Description
account AccountName optional, required* Contract account this table is a representation of.
scope Name optional, required* Scope in contract account this table is a representation of.
rows array<DBRow> required An array of rows in the table.

The account and scope fields will not be present when the request context makes it obvious what they should be (ex: in the context of a get_table_rows). They will however always be present when querying multi accounts /v0/state/tables/accounts or multi accounts /v0/state/tables/scopes endpoints.

TableDeltaResponse

Example table_delta response payload:

{"type": "table_delta",
 "req_id": "your-request-id",
 "data": {
  "block_num": 123,
  "step": "new",
  "dbop": {
    "op": "ins",
    "old": {},
    "new": {}
  }
}}
Name Type Options Description
type string required The transaction_lifecycle string
data TableDelta required The change operation from a table, navigating forks with the step element.

TableDelta

Example table_delta payload:

{
  "block_num": 123,
  "step": "new",
  "dbop": {
    "op": "upd",
    "old": {},
    "new": {}
  }
}
Name Type Options Description
block_num number (uint32) required Block that produced such a change
step string required, one of new, undo, redo Step in the forks navigation
dbop DBOp required Database operation

StateResponse

Here is a sample response, for a request at block_num: 8:

{
  "up_to_block_id": "0000001000000000000000000000000000000000000000000000000000000000",
  "up_to_block_id": 8,
  "last_irreversible_block_id": "0000000400000000000000000000000000000000000000000000000000000000",
  "last_irreversible_block_num": 4,
  "abi": {
    ...
  },
  "rows": [
    {
      "key": "account123",
      "payer": "account123",
      "json": {
        "owner": "account123"
      },
      "block": 1
    },
    ... or ...
    {
      "key": "account123",
      "payer": "account123",
      "hex": "0011223344556677",
      "block": 2
    },
    ...
  ]
}
Name Type Options Description
up_to_block_id string optional Block ID at which the snapshot was taken when querying the reversible chain segment. This will not be present if querying blocks older than the last irreversible block.
up_to_block_num number (uint32) optional Block number extracted from up_to_block_id if present, provided as a convenience so you don't need to extract it yourself.
last_irreversible_block_id string optional Last irreversible block considered for this request. The returned snapshot is still for the requested block_num, even though the irreversible block shown here is more recent.
last_irreversible_block_num number (uint32) optional Block number extracted from last_irreversible_block_num, provided as a convenience so you don't need to extract it yourself.
abi object optional A JSON representation of the ABI that is stored within the account. It is the ABI in effect at the requested block_num.
rows array<DBRow> required An array of rows in the table, sorted by their uint64 key.

The main difference between a StateResponse and a MultiStateResponse is the rows field above.

MultiStateResponse

Here is a sample response, for a request at block_num: 8:

{
  "up_to_block_id": "0000001000000000000000000000000000000000000000000000000000000000",
  "up_to_block_id": 8,
  "last_irreversible_block_id": "0000000400000000000000000000000000000000000000000000000000000000",
  "last_irreversible_block_num": 4,
  ...
  "tables": [
    {
      "account": "oo1122334455",
      "scope": "eoscanadacom",
      "rows": [
        {
          "key": "1397706825",
          "payer": "iambillgates",
          "json": {
            "balance": "2000.0000 IPOS"
          }
        }
      ]
    }
  ]
}
Name Type Options Description
up_to_block_id string optional Block ID at which the snapshot was taken when querying the reversible chain segment. This will not be present if querying blocks older than the last irreversible block.
up_to_block_num number (uint32) optional Block number extracted from up_to_block_id if present, provided as a convenience so you don't need to extract it yourself.
last_irreversible_block_id string optional Last irreversible block considered for this request. The returned snapshot is still for the requested block_num, even though the irreversible block shown here is more recent.
last_irreversible_block_num number (uint32) optional Block number extracted from last_irreversible_block_num, provided as a convenience so you don't need to extract it yourself.
abi object optional A JSON representation of the ABI that is stored within the account. It is the ABI in effect at the requested block_num.
tables array<TableRows> required An array of tables, one for each queried account, unsorted.

ActionTrace

Example action_trace payload

{
  "type": "action_trace",
  "data": {
    "block_num": 25870889,
    "block_id": "018ac229323f3538cfde5c34f9cfcb1b2d80a4062a822c869d9eb9fcff2235db",
    "block_time": "2018-11-08T13:23:39.5Z",
    "trx_id": "35030b5bfd05f4f5b5bcae68505bf9f2c227a84c6b406dabebe0d8cd0384cd70",
    "idx": 0,
    "depth": 0,
    "trace": {
      "receipt": {
        "receiver": "eosio.msig",
        ...
      },
      "act": {
        "account": "eosio.msig",
        "name": "exec",
        "authorization": [
          {
            "actor": "eoscanadaaaf",
            "permission": "active"
          }
        ],
        "data": {
          "proposer": "eoscanadaaaf",
          "proposal_name": "goincthirthy",
          "executer": "eoscanadaaaf"
        },
        "hex_data": "b08c31c94c833055e05bbeae65341d65b08c31c94c833055"
      },
      "context_free": false,
      "elapsed": 644,
      "console": "",
      "trx_id": "35030b5bfd05f4f5b5bcae68505bf9f2c227a84c6b406dabebe0d8cd0384cd70",
      "block_num": 25870889,
      "block_time": "2018-11-08T13:23:39.500",
      "producer_block_id": "018ac229323f3538cfde5c34f9cfcb1b2d80a4062a822c869d9eb9fcff2235db",
      "account_ram_deltas": [
        {
          "account": "eoscanadaaaf",
          "delta": -323
        }
      ],
      "except": null,
      "inline_traces": []
    },
    "ramops": [
      {
        "op": "deferred_trx_add",
        "action_idx": 0,
        "payer": "eoscanadaaaf",
        "delta": 354,
        "usage": 4027
      },
        ...
    ],
    "dtrxops": [
      {
        "op": "CREATE",
        "action_idx": 0,
        "sender": "eosio.msig",
        "sender_id": "0xe05bbeae65341d65b08c31c94c833055",
        "payer": "eoscanadaaaf",
        "published_at": "2018-11-08T13:23:39.500",
        "delay_until": "2018-11-08T13:23:39.500",
        "expiration_at": "2018-11-08T13:33:39.500",
        "trx_id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24",
        "trx": {
         ...
        }
      }
    ]
  }
}
Name Type Options Description
block_id string required Block at which we are seeing this action being executed, and for which we are reporting traces.
block_num number (uint32) required Block num corresponding to the block_id
block_time DateTime required Time at which block_id was produced.
trx_id string required ID of transaction that produced these traces
idx number (uint16) required Zero-based index of this action within the transaction. Actions being nestable, this index represents a depth-first search indexing: if action A (index 0) produced an inline action B, then action B is index 1.
depth number (uint16) required Depth of the action relative to the input actions (top-level actions that were defined in the originating transaction, and not inlined as side effects of execution of top-level actions). Actions with depth = 0 are called input actions. Anything above 0 means this is an inline action.
trace TransactionTrace required An execution trace object. This is a standard nodeos trace object. See the reference C++ code here.
ramops array<RAMOp> optional A list of operations on RAM usage, including operation, payer, delta, resulting usage.
dtrxops array<DTrxOps> optional A list of operations on deferred transactions (create, cancel...).

DBOp

A DBOp represents a database operation. They appear in the table_delta and table_snapshot WS responses. They are also found in the responses from the REST /v0/state/table.

Name Type Options Description
op string required Operation. One of REM (removal), UPD (update) or INS (insertion)
action_idx number (uint16) required Position of the action within the transaction, going depth-first in inline_actions. 0-based index.
account AccountName required Contract account in which this database operation occurred.
scope AccountName not repeated within a Table,
the table specifies the scope		 Scope within the contract account, in which the database operation occurred.
key Name optional Represents the primary key of the row in the table.
old DBRow optional, depending on op Contents of the row before a REM or UPD operation.
new DBRow optional, depending on op Contents of the row after an INS or UPD operation.

DBRow

A DBRow represents the contents of a row in a DBOp.

Only one of hex or json will be set. If you requested JSON but ABI-decoding failed, you will receive the encoded binary data in hex alongside an error.

Name Type Options Description
payer AccountName required The account which is billed RAM for the time this row stays in the blockchain state.
hex hex-encoded byte array optional Hex-encoded string representing the binary data of the row
json Object optional Free-form JSON document representing the ABI-decoded row, with the ABI active at the time the operation occurred.
error string optional An error message specifying why the ABI decoding failed, when it did.

RAMOp

A RAM operation is a modification to the RAM consumed by an account. RAM operations on dfuse are scoped down to the action.

Name Type Options Description
op string required Operation. See enum below.
action_idx number (uint16) required Position of the action within the transaction, going depth-first in inline_actions. 0-based index.
payer AccountName required Payer that is credited or debited some RAM usage
delta number (int64) required Number of bytes freed (negative) or consumed (positive) by payer.
usage number (uint64) required Number of bytes available to payer after this operation affects his RAM balance.

Here is a list of operations with the reasons for the consumption:

DTrxOp

See this source code for reference

ExtDTrxOp

See this source code for reference

SearchTransactionsResponse

Example payload:

{
  "cursor": "dno3ojdbEpHZV73TfVnvbfWzIpU9BlpvXwo=",
  "transactions": [
    {
      "lifecycle": {
        "transaction_status": "executed",
        "id": "7c5d768973152e0465a2a3eba88689d012ffd4b16cfdd41291e6d7830530d1cb",
        ...
      },
      "action_idx": [
        0
      ]
    }
  ]
}
Name Type Options Description
cursor string optional Cursor to pass back to continue your query. Only present when hitting the limit value. Will be null when reaching the end of the block span searched.
transactions array<SearchTransactionsRow> required List of SearchTransactionsRow objects.
forked_head_warning boolean optional Signals that results previously fetched are at risk of being wrong because of network forks conditions. Will only show when with_reversible was set to true. See pagination for more details.

SearchTransactionsRow

Example payload:

{
  "lifecycle": {
    "transaction_status": "executed",
    "id": "7c5d768973152e0465a2a3eba88689d012ffd4b16cfdd41291e6d7830530d1cb",
    ...
  },
  "action_idx": [
    0
  ]
}
Name Type Options Description
lifecycle TransactionLifecycle required Full transaction where some of its actions matched.
action_idx array required Indexes of the actions (indexed by depth-first search through inline_traces, base 0) that matched the search query.

TransactionLifecycleResponse

Example transaction_lifecycle response payload:

{
  "type": "transaction_lifecycle",
  "data": {
    "lifecycle": {
      "transaction_status":"executed",
      "id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24",
      "transaction": { ... "actions": [ ... ] ... },
      "execution_trace": { ... },
      ...
    }
  }
}

Here are the fields under data:

Name Type Options Description
type string required The transaction_lifecycle string
data.lifecycle TransactionLifecycle required The lifecycle object being tracked.

TransactionLifecycle

Example TransactionLifecycle payload:

{
  "transaction_status":"executed",
  "id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24",
  "transaction": { ... "actions": [ ... ] ... },
  "execution_trace": { ... },
  "execution_block_header": { ... },
  "dtrxops": [
    {
      "op": "CREATE",
      ...
      "trx_id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24",
      "trx": { ... }
    }
  ],
  "ramops": [ ... ],
  "pub_keys": [
    "EOS86qtjWfMcVJjyLy4TGTybyA8xsFagJtXgwFJC1KR5o7M1ch5ms"
  ],
  "created_by": {
    "src_trx_id": "35030b5bfd05f4f5b5bcae68505bf9f2c227a84c6b406dabebe0d8cd0384cd70",
    "block_num": 25870889,
    "block_id": "018ac229323f3538cfde5c34f9cfcb1b2d80a4062a822c869d9eb9fcff2235db",
    "op": "CREATE",
    "action_idx": 0,
    "sender": "eosio.msig",
    ...
  },
  "canceled_by": null,
  "execution_irreversible": true,
  "creation_irreversible": true,
  "cancelation_irreversible": false
}

Here are the fields under data:

Name Type Options Description
id string required the transaction ID
transaction_status string required, one of pending, delayed, canceled, expired, executed, soft_fail, hard_fail Computed status for the transaction
transaction Transaction required Standard nodeos transaction object
execution_trace TransactionTrace optional Traces of execution. In the case of a deferred transaction, you might not see execution traces
execution_block_header BlockHeader optional Standard block_header object for the block where the transaction got executed
dtrxops array<DTrxOp> optional A list of operations on deferred transactions (create, cancel...).
ramops array<RAMOp> optional A list of operations on RAM usage, including operation, payer, delta, resulting usage.
pub_keys array<string> optional List of public keys used to sign the transaction.
created_by ExtDTrxop optional When querying a deferred transaction, reference to the transaction that created it.
canceled_by ExtDTrxop optional Similar to created_by, the reference to another transaction that has canceled this one.
execution_irreversible boolean optional Indicates execution passed irreversibility.
creation_irreversible boolean optional Indicates transaction creation passed irreversibility. Valid only for deferred transactions
cancelation_irreversible boolean optional Indicates cancelation passed irreversibility. Valid only for deferred transactions.

Also see this source code for reference

TransactionTrace

See this source code for reference.

HeadInfo

Example head_info payload:

{
  "type": "head_info",
  "data": {
    "last_irreversible_block_num": 22074884,
    "last_irreversible_block_id": "0150d604868df2ded03bb8e4452cefd0b9c84ae2da31bef6af62b2653c8bb5af",
    "head_block_num": 22075218,
    "head_block_id": "0150d7526b680955eaf4c9d94e17ff3f03d25a1dccb714601173c96b80921362",
    "head_block_time": "2018-11-22T21:00:35.5Z",
    "head_block_producer": "eosswedenorg"
  }
}

Here are the fields under data:

Name Type Options Description
head_block_num number (uint32) required Head block number
head_block_id string required Head block ID
head_block_time DateTime required Head block production time
last_irreversible_block_id string required Block ID of the last irreversible block (at corresponding head block)
last_irreversible_block_num number (uint32) required Block number corresponding to last_irreversible_block_id

Errors

The dfuse API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Your request Origin does not match.
404 Not Found -- The specified kitten could not be found.
418 I'm a teapot.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Release Notes

2019-02-18

2019-01-22

Our error message structure for both the REST API and WebSocket API is now fully standardized across all our endpoints.

The format is as follow:

  {
    "code": "a_unique_error_code_for_this_specific_error",
    "trace_id": "unique_id_identifying_your_request",
    "message": "A descriptive error message about the problem.",
    "details": {
      "key": "contextual key/values pairs specific to each error"
    }
  }

Each error returned to you has a unique code field which descriptively identifies the error. The error code is stable in time and can be programmatically relied upon in your code to process the error.

The trace_id uniquely identifies your request, will change upon each request, being unique across all traces. This can be provided to our support team when investigating problems.

The message is a human-readable english string about why the error happen and what was wrong exactly. It may change over time and should not be used to determine what the error was. Use the code field for that purpose.

The details is a key/value pair object and is optional, so it might or might not be present. It contains error specific details about what went wrong for a given error code. It's unique per code, and can be used programmatically to extract information about the error.

2018-12-18

REST API

2018-12-13

REST API

2018-12-12

REST API

2018-12-10

REST API

2018-11-28

WebSocket

2018-11-22

Breaking changes

REST API

WebSocket

2018-11-09

Breaking changes (within reason, during beta period)

New features

2018-10-15

shell