Introduction
Welcome to the 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
- dfuse Telegram channel.
- dfuse repositories on GitHub.
- Technical discussions on EOS.IO StackExchange with the tag dfuse, and feel free to report your bugs.
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:
with_progress
: allowing you to keep tabs on what you have seen up to the secondstart_block
: allowing you to restart from where you left off
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:
A negative value will start you in the past, relative to the current head block of the chain. Ex:
-50
would start at block25000100
if the head block was25000150
A value of
0
means to start streaming at the head block, feeding real-time data through the socket.A positive value will start at the given block. Ex:
10000
will start feeding (almost) the whole chain history into your socket. Contact us for keys with that feature enabled.
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
:
new
this the first time we see this DB operation.undo
this happen during forks and means that the DB operation is no longer part of the longest chain.redo
this happen during forks and means that the DB operation is now on the longest chain and has not seen for the first time.
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
fetch: true
is not supported forget_action_traces
listen: true
requests will stream ActionTrace objects.
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
fetch: true
requests will stream TableSnapshotResponse objects.listen: true
requests will stream TableDeltaResponse objects.
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:
(Beta)
/v0/state/abi
: Fetching snapshots of any table on the blockchain, at any block height.(Beta)
/v0/state/abi/bin_to_json
: Decode the ABI for a given contract account, at any block height.(Beta)
/v0/state/permission_links
: Fetching snapshots of any account's linked authorizations on the blockchain, at any block height.(Beta)
/v0/state/table
: Fetching snapshots of any table on the blockchain, at any block height.(Beta)
/v0/state/table/accounts
: Fetching snapshots of any table on the blockchain, at any block height, for a list of accounts (contracts).(Beta)
/v0/state/table/scopes
: Fetching snapshots of any table on the blockchain, at any block height, for a list of scopes for a given account (contract)./v1/chain/...
: Reverse-proxy of all standard chain requests to a well-connected node. Except the following which have instrumented behavior:- (Beta)
/v1/chain/push_transaction
: Drop-in replacement for submitting a transaction to the network, but can optionally block the request until the transaction is either in a block or in an irreversible block.
- (Beta)
(Preview)
/v0/search/transactions
: Structure Query Engine (SQE), for searching the whole blockchain history and get fast and precise results.
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:
with HTTP Header:
X-Eos-Push-Guarantee: in-block
, the call is blocking until the transaction makes it into a valid blockwith HTTP Header:
X-Eos-Push-Guarantee: handoff:1
, the call is blocking until the transaction makes it into a block that is still in the longest chain after block production got handed off to a different BP 1, 2 or 3 times (withhandoffs:2
andhandoffs:3
)with HTTP Header:
X-Eos-Push-Guarantee: irreversible
, the call is blocking until the block in which the transaction was inserted becomes irreversible.
The content of the request and response is identical to the regular "push_transaction" endpoint, except:
The response will contain those extra fields:
block_id
andblock_num
to inform you of the actual block containing the transaction.The traces returned (under
processed
) are from the actual execution of the block, instead of being speculative traces of the edge node (like it is normally).
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. |
GET /v0/state/permission_links
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.
Requesting past blocks
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.
Input parameters
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. |
Response
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. |
LinkedPermission
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:
name
(default) for EOS name-encoded base32 representation of the row keyhex
for hexadecimal encoding, ex:abcdef1234567890
hex_be
for big endian hexadecimal encoding, ex:9078563412efcdab
uint64
for string encoded uint64. Beware: uint64 can be very large numbers and some programming languages need special care to decode them without truncating their value. This is why they are returned as strings.
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:
name
(default) for EOS name-encoded base32 representation of the row keyhex
for hexadecimal encoding, ex:abcdef1234567890
hex_be
for big endian hexadecimal encoding, ex:9078563412efcdab
uint64
for string encoded uint64. Beware: uint64 can be very large numbers and some programming languages need special care to decode them without truncating their value. This is why they are returned as strings.
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:
name
(default) for EOS name-encoded base32 representation of the row keyhex
for hexadecimal encoding, ex:abcdef1234567890
hex_be
for big endian hexadecimal encoding, ex:9078563412efcdab
uint64
for string encoded uint64. Beware: uint64 can be very large numbers and some programming languages need special care to decode them without truncating their value. This is why they are returned as strings.
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
account:eosio.token receiver:eosio.token (data.from:eoscanadacom OR data.to:eoscanadacom)
(auth:eoscanadacom OR receiver:eoscanadacom)
account:eosio.token action:transfer
(ram.consumed:eoscanadacom OR ram.released:eoscanadacom)
receiver:eosio.token db.key:"accounts/eoscanadacom/........ehbo5"
receiver:eosio.token db.table:stats
Available query fields
These are the prefixes or fields available for query:
action:
is the name of the action executedaccount:
matches theaccount
called on the action. Not to be mixed up withreceiver
. This will match notifications sent from a contract to another account.receiver:
means the account with code that has executed the action. This is unambiguous.act_digest:
the 16 first hex characters of the hash of the binary action payloadauth:
means the action was signed with the authority of a given account. The field has two formats:auth:account
an account, irrespective of the permission which signed the transactionauth:account@perm
an account and specific permission that signed the transaction, in which this action was declared.
status:executed
will match the status of the transactionscheduled:true
will match deferred transactionsnotif:true
will match only notifications, excluding input action or other inline actions.input:true
will match only the action that was received directly by the first smart contractdata.sub.fields:
a good number of action-specific fields can be matched for equality. Ex:data.from
anddata.to
(present intransfer
operations).- lists are flattened, and terms matched when the query is present in the list.
- nested documents fields are separated by
.
, sodata.user.id:hello
will match the action data:{"data": {"user": {"id": "hello"}}}
- Here is a non-exhaustive list of
data.*
attributes currently indexed:data.from
,data.to
,data.account
,data.actor
,data.creator
,data.executer
,data.name
,data.owner
,data.permission
,data.producer
,data.proposal_name
,data.producer_key
,data.proposal_hash
,data.proposer
,data.producers.*
(nested),data.voter_name
and many more....
- Hashed data attributes:
data.abi:SHA256
matchessetabi
actions with an ABI data hashing to a given SHA256 fingerprintdata.code:SHA256
matchessetcode
actions with an ABI data hashing to a given SHA256 fingerprint
- RAM operations incurred by action:
ram.consumed:
is set to accounts that have consumed some RAM during an actionram.released:
is set to accounts that have released some RAM during an action
- Database operations applied by action. All values are name-encoded (including the primary key)
db.key:
supports two values:[table_name]/[scope]/[primary-key]
[primary-key]
db.table:
supports two values:[table_name]/[scope]
[table_name]
db.scope:[scope]
- All the fields therein are name-encoded (even if somethings it can be the empty string), and are separated by the
/
character.
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:
create_table
: creation of a tabledeferred_trx_add
: storing deferred transactiondeferred_trx_cancel
: canceling deferred transactiondeferred_trx_pushed
: creating deferred transactiondeferred_trx_removed
: executing deferred transaction. NOTE: that this one is the only one that is really scoped to the transaction, and not the action. You can ignore the value ofaction_idx
whenop
isdeferred_trx_removed
.deleteauth
: deleting authoritylinkauth
: linking authoritynewaccount
: creating new accountprimary_index_add
: storing row (primary)primary_index_remove
: removing row (primary)primary_index_update
: updating row (primary)primary_index_update_add_new_payer
: storing payer (primary)primary_index_update_remove_old_payer
: removing payer (primary)remove_table
: removing a tablesecondary_index_add
: storing row (secondary)secondary_index_remove
: removing row (secondary)secondary_index_update_add_new_payer
: storing payer (secondary)secondary_index_update_remove_old_payer
: removing payer (secondary)setabi
: updating ABI for accountsetcode
: updating contract for accountunlinkauth
: unlinking authorityupdateauth_create
: creating new permissionupdateauth_update
: updating permission
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
POST /v1/chain/push_transaction
now supports new push-guarantees:handoff:1
,handoffs:2
andhandoffs:3
, allowing more flexible rules to guarantee transaction delivery based on your application's requirements.
2019-01-22
- Fully standardized error messages format returned to consumer.
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
Released PREVIEW of dfuse Structured Query Engine or (SQE).
GET /v0/search/transactions
to query the whole blockchain in a swift
Renamed
TableDelta
toTableDeltaResponse
, andTableDelta
is now the innerdata
field of that response.Renamed
TableSnapshot
toTableSnapshotResponse
, andTableRows
is now the innerdata
field of that response.Renamed
TransactionLifecycle
toTransactionLifecycleResponse
, andTransactionLifecycle
is now the innerdata
field of that response.
2018-12-13
REST API
Added in PREVIEW mode:
GET /v0/state/abi
to fetch the ABI of a given account (contract) at any given block height.Added in PREVIEW mode:
POST /v0/state/abi/bin_to_json
to decode hexadecimal raw data of multiple rows against the ABI of a given account (contract) at any given block height.
2018-12-12
REST API
Added in PREVIEW mode:
GET /v0/state/tables/scopes
to fetch a given table/scope pair for multiple contracts in a single command (up to 1500).Bumped
GET /v0/state/tables/accounts
limit onaccounts
to 1500.
2018-12-10
REST API
- Added in PREVIEW mode:
GET /v0/state/permission_links
to fetch authorization linked to a particular account at any given point in time.
2018-11-28
WebSocket
DEPRECATED: The
eosws.mainnet.eoscanada.com
domain, which some users used at the very beginning of dfuse will be shutdown in 7 days. Use the new endpoints listed above.Added support to filter multiple
accounts
,receivers
andaction_names
in theget_action_traces
WS request.- The
account
,receiver
andaction_name
parameters are still supported by DEPRECATED, and will be removed in a future release. - Please use that instead of doing multiple parallel
get_action_traces
- The
2018-11-22
Breaking changes
- Breaking change
get_table_rows
listen response fieldsundo: true
andredo: true
are replaced bystep: "undo"
andstep: "redo"
REST API
Added in PREVIEW mode:
GET /v0/state/tables/accounts
to fetch a given table/scope pair for multiple contracts in a single command (up to 500)POST /v1/chain/push_transaction
supports anonymous access forin-block
guarantees.
WebSocket
get_transaction_lifecycle
now correctly sends an update upon irreversibility. It also contains a "transaction_status" parameter.Fixed
get_table_rows
encoding errors on some rows (that were in fact deleted)Added
get_head_info
to get current state of chain (last block, current producer, etc.)
2018-11-09
Breaking changes (within reason, during beta period)
get_transaction
was renamed to:get_transaction_lifecycle
get_transaction_lifecycle
:- now returns
transaction_lifecycle
, a message format that has changed quite heavily to include information about deferred creation, deferred execution, irreversibility of the different blocks, etc. See docs for details.
- now returns
get_actions
was renamed to:get_action_traces
get_action_traces
:with_deferred
was renamed towith_dtrxops
get_table_rows
:data.table_name
parameter renamed todata.table
(for consistency with the REST API)data.verbose
option removed- the struture of the
rows
has changed in thetable_delta
message. dbop
is now a nested objectdbop.key
is now a name-encoded valuedbop.old
anddbop.new
represent the old and new values, payers.zz
New features
- Added REST endpoint
/v0/state/table
added. See docs for details. - Added REST endpoint
/v1/chain
as passthrough to a reliable node - Added guarantees to REST endpoint
/v1/chain/push_transaction
. See docs for details. get_transaction_lifecycle
: now supports "fetch" AND "listen" modes, the listen mode will send updated objects when new block affects the trx.get_table_rows
: thefetch: true
argument now returns a snapshot of the table at the block requested. Addinglisten: true
streams changes as they arrive.get_table_rows
: when switching longest chain, you will now receiveundo
andredo
operations allowing you to stay completely in sync with the longest chain (provided you apply those deltas to a client-side full table state)action_trace
message now includes ablock_time
2018-10-15
get_actions
request: renamed parameterwith_ram_costs
towith_ramops
(get_actions
is nowget_action_traces
).