NAV Navbar
API documentation
shell

Introduction

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.


Resources

Getting started

with JavaScript

JavaScript Example Code

<script src="https://unpkg.com/@dfuse/client@0.2.0-rc.19/browser/bundle.js"></script>
<script>
    const dfuseClient = dfuse.createDfuseClient({apiKey: "YOUR API KEY HERE", network: "mainnet"});
    dfuseClient.streamActionTraces({accounts: "eosio.token", action_names: "transfer"}, (message) => {
        if (message.type === dfuse.InboundMessageType.ACTION_TRACE) {
            const {from, to, quantity, memo} = message.data.trace.act.data
            console.log(`Transfer [${from} -> ${to}, ${quantity}] (${memo})`)
        }
    }).catch((error) => {
        console.log("An error occurred.", error)
    })
</script>

This simple programme demonstrates how easy it is to stream action traces over websocket with our client-js library.

Useful links

with Go

Go Example Code

import (
	"context"
	"fmt"
	"log"
	pbgraphql "main/graphql"
	"os"

	"github.com/dfuse-io/eosws-go"
	"golang.org/x/oauth2"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/credentials/oauth"
	"io"
)

func main() {
	token, _, err := eosws.Auth(os.Args[1])
	if err != nil {
		log.Fatalf("cannot get auth token: %s", err)
	}

	credential := oauth.NewOauthAccess(&oauth2.Token{AccessToken: token, TokenType: "Bearer"})
	connection, err := grpc.Dial("mainnet.eos.dfuse.io:443", grpc.WithPerRPCCredentials(credential), grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")))
	graphqlClient := pbgraphql.NewGraphQLClient(connection)

	q := `subscription  {
		  searchTransactionsForward(query: "status:executed") {
			trace { matchingActions {receiver account name json }}}}`

	executionClient, err := graphqlClient.Execute(context.Background(), &pbgraphql.Request{Query: q})
	if err != nil {
		log.Fatalf("execution error: %s", err)
	}

	for {
		response, err := executionClient.Recv()
		if err != nil {
			if err != io.EOF {
				log.Fatalf("reception error: %s", err)
			}
			fmt.Println("No more result available")
			break
		}
		fmt.Println("Received response:", response.Data)
	}
}

This simple programme demonstrates how easy it is to query our graphQL API over gRPC.

Before you begin

Get the source code

Generates the graphql.pb.go

Getting project dependencies

Run it!

Useful links

More Examples

Action Rates in (JavaScript)

This example uses GraphQL Subscription & Apollo Client to display action rate per minutes graph and grid

Source code

Push Notification Example in (Go)

A fully functional example sending push notifications base on a graphql query results.

Source code

dfuse Client Library - Node.js Example in (JavaScript)

This project showcases how to use dfuse Client Library to easily stream all transfers happening in Mainnet in a streaming fashion.

Source code

Endpoints

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

EOS Mainnet

Chain ID: aca376f2...
WebSocket wss://mainnet.eos.dfuse.io/v1/stream
REST https://mainnet.eos.dfuse.io/
GraphQL https://mainnet.eos.dfuse.io/graphql – See GraphiQL or Playground

CryptoKylin Network

Chain ID: 5fff1dae...
WebSocket wss://kylin.eos.dfuse.io/v1/stream
REST https://kylin.eos.dfuse.io/
GraphQL https://kylin.eos.dfuse.io/graphql – See GraphiQL or Playground

Jungle 2.0 Network

Chain ID: e70aaab8...
WebSocket wss://jungle.eos.dfuse.io/v1/stream
REST https://jungle.eos.dfuse.io/
GraphQL https://jungle.eos.dfuse.io/graphql – See GraphiQL or Playground

Authentication

There are two sorts of keys in the dfuse ecosystem:

Issuing short-lived JWT

If you haven’t already, head out to our self-service API management portal, sign up and create a long-term API key.

Generate a short-lived JTW from your API key:

$ curl https://auth.dfuse.io/v1/auth/issue \
       -s --data-binary '{"api_key":"web_abcdef12345678900000000000"}'

Do not forget to replace the API key by your own.

Once you have this API key, call the https://auth.dfuse.io/v1/auth/issue endpoint to get a fresh Authentication Token (JWT).

By default, each JWT is valid for a period of 24 hours. Make sure you cache those values to avoid hitting rate limiting on JWT issuance.

Lifecycle of short-lived JWTs

The best way to handle each JWT’s lifecycle is, before doing calls to dfuse:

Sample response from /v1/auth/issue

{
  "token":"eyJhbGciOiJLTVNFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTYxMzI4MjAsImp0aSI6IjQwNWVmOTUxLTAwZTYtNGJmNC1hZWMxLTU0NTU1ZWMzMTUwMiIsImlhdCI6MTU1NjA0NjQyMCwiaXNzIjoiZGZ1c2UuaW8iLCJzdWIiOiJ1aWQ6MHdlbnU2NmUwNzU4OWRhODY4MWNlIiwiYWtpIjoiM2NhYWEzYzA3M2FlZjVkMmYxOGUwNjJmZDkzYzg3YzMzYWIxYzA1YzEzNjI3NjU2OTgzN2Y5NDc5NzZlMjM0YSIsInRpZXIiOiJmcmVlLXYxIiwic3RibGsiOi0zNjAwLCJ2IjoxfQ.000HeTujIuS_LRvvPN6ZRCmtoZqZyV6P1enNBviwK8v7Tf7BLHJIrEpQoEREKSIMdZWPrMQl_OE55yJP0MxUDA",
  "expires_at":1556132820
}

Each time you get a fresh JWT, you get the expiration and the token itself.

Once a connection is established using a JWT, it will not be shutdown, even though the JWT expires during the session.

Key Types & Rate Limiting

There are 3 api key types: mobile, web and server. The type is the first part of the key.

Each key time has different rate limiting characteristics, to prevent abuse - similar to Google Maps’ (and other) APIs. Pick your API key type according to your usage pattern.

You can safely publish web and mobile keys inside your mobile app or web application.

REST authentication

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

Pass Bearer token in the Authorization header

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

Replace [token] by a valid JWT, retrieved using /v1/auth/issue

WebSocket authentication

With browser-based WebSocket connections, it is not possible to specify additional headers. In this situation, pass your JWT as the token query string parameter.

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.

The Origin header

When the Origin header is present in a WebSocket connection, it it must match the origin provided in your API header key.

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.

GraphQL authentication

Using the apollo-client websocket protocol, the INIT message should contain an Authorization key, with the same format as the REST authentication (bearer token).

When doing POST calls to the /graphql endpoint, specify the Authorization header, exactly like any other REST calls.

GraphQL over gRPC authentication

Using the language of your choice, use the OAuth2 authentication method with gRPC. Set the OAuth2 Access Token to be your JWT, and if required, specify Bearer as the method, then proceed normally. This will set the authorization gRPC header, similiar to the HTTP header of the same name.

GraphQL

[NEW] dfuse provides a GraphQL endpoint giving access to a stream of transaction traces, as well as paginated responses (queries and subscriptions, in GraphQL parlance).

The streaming endpoints provide support to navigate forks, using the cursor and undo fields.

WARN: never forget to retrieve the undo field when doing a forward search, as streaming results will re-send the matching transactions with undo=true upon micro-forks resolution.

The GraphQL endpoint is available on the following networks, using two interfaces: the Apollo Playground, and the well-known GraphiQL interface. See Endpoints for links.

In the Playground and GraphiQL UIs, the keys are auto-provisioned for low-volume experimentation.

Transports

The dfuse GraphQL endpoints support the following transports:

GraphQL over REST

You can run GraphQL queries by querying the /graphql path of dfuse endpoints. See Endpoints for the list of endpoints and networks.

Do a paginated GraphQL query, and retrieve the last 10 executed transactions from EOS mainnet. Don’t forget to replace $DFUSE_TOKEN by a valid JWT.

curl https://mainnet.eos.dfuse.io/graphql \
     -XPOST \
     -d '{"query": "{ searchTransactionsForward(limit: 10, query: \"status:executed\") { cursor results { undo trace { id matchingActions { receiver account name json } } } } }"}' \
     -H "Authorization: Bearer $DFUSE_TOKEN"

Get the block number, timestamp and ID at a given point in time, on the Crypto Kylin network.

curl https://kylin.eos.dfuse.io/graphql \
     -XPOST \
     -d '{"query": "{ blockIDByTime(time: \"2019-01-01T00:00:00Z\") { time num id } }"}' \
     -H "Authorization: Bearer $DFUSE_TOKEN"

Apollo Subscription Transport

sample usage with apollo-client

dfuse GraphQL implements subscriptions using the Apollo Websocket Transport protocol, version 0.9.16.

In the browser, you can use the apollo-client npm library to connect and read responses. It uses WebSocket for Subscriptions and can also use it for Queries.

See the Apollo Client Introduction for more details.

GraphQL over gRPC

Using grpcurl

First, install grpcurl, a simple curl-like program to communicate via gRPC.

List available gRPC methods with:

grpcurl mainnet.eos.dfuse.io:443 list

Stream live search query responses:

echo '{"query": "subscription { searchTransactionsForward(limit: 10, query: \"status:executed\") { cursor undo trace { id matchingActions { receiver account name json } } } }"}' \
  | grpcurl -H "Authorization: Bearer $DFUSE_TOKEN" -d @ \
      mainnet.eos.dfuse.io:443 dfuse.eosio.v1.GraphQL/Execute

The GraphQL response is wrapped as a string in the gRPC data field.

For a nice output, install jq and pipe the previous command into:

jq '.data | fromjson | .data.searchTransactionsForward.trace'
# or
jq -r .data

Using grpcui

First, install grpcui.

Then run:

grpcui -port 6000 mainnet.eos.dfuse.io:443

Then open http://localhost:6000 and explore the interface.

Add the authorization header in the interface, in the format: Bearer TOKEN where TOKEN is a valid JWT.

Note: grpcui doesn’t handle streaming responses properly; it jams until the subscription is terminated. To view streaming search results, use grpcurl instead (see above).

Searching through GraphQL

The dfuse Search engine exposed through the GraphQL endpoint has a fiew pecularities that are worthy to note here:

  1. The cursor exposed therein is chain-wide, and is returned with EACH result, so you can pick up where you left atomically at each transaction, and not worry that a block has been partially applied.
  2. It navigates forks in a slightly different way than the WebSocket get_table_rows. See below.
  3. You can do a backward search to get recent transactions up to a limit, and then use the first cursor from those results to do a forward search on the same query, and listen to real-time events happening in real-time, all the while navigating forks. Again, make sure you track undo in forward searches.

tldr: ALWAYS fetch and check the undo flag when doing forward searches, and take appropriate action.

The get_table_rows navigates forks by sending INVERTED database operations for a given database change when it is rolled back. As documented, simply applying the database operations to your results will ensure a consistent view of the blockchain tables.

HOWEVER, in the GraphQL search, the results returned are individual Transactions (or a subset of their data). Therefore, the database operations will NOT be inverted. It is your responsibility to revert their effect if you are interested in the database operations, in accordance with the undo value in the result.

Sample queries

The GraphQL schemas are available through the GraphiQL or the Playground, available at the different Endpoints. The Schema is fully documented and should answer most of your questions regarding the data it serves.

To get you started, here are a few sample queries.

The following query:

subscription {
  searchTransactionsForward(
    query:"receiver:eosio.token account:eosio.token action:transfer",
    lowBlockNum:0,
    limit:20,
  ) {
    undo
    cursor
    trace {
      id
      matchingActions {
        receiver
        account
        name
        json
        creatorAction {
          receiver
          account
          name
          json
        }
      }
    }
  }
}

Sample from today’s output:

{
  "searchTransactionsForward": {
    "undo": false,
    "cursor": "BKg1cvtNtiumthn4ayUAcfe7IZI9AlpmUgnvKhJFhYinoSHG2pv1AmQmYRjXlKj120frHl6ri4zPQn8p9pJRvNbixrhm6HRpEC8km4nn_bW5fvrxMA4fJbw3C-CJNN-JXj2DZgivc-A=",
    "trace": {
      "id": "7f7b51d42d9a58f461b7a88415a7cf84cc1e346fc27c022267e01dcf4c437de8",
      "matchingActions": [
        {
          "receiver": "eosio.token",
          "account": "eosio.token",
          "name": "transfer",
          "json": {
            "from": "trustdicewin",
            "to": "antoinewu123",
            "quantity": "0.0005 EOS",
            "memo": "antoinewu123-Faucet from the ...Platform! ..."
          },
          "creatorAction": {
            "receiver": "trustdicewin",
            "account": "trustdicewin",
            "name": "coinbox",
            "json": {
              "memo": "antoinewu123-antoinewu123-EOS-14fb7........."
            }
          }
        }
      ]
    }
  }
}

The next query:

{
  start:blockIDByTime(time: "2019-01-01T00:00:00Z") {
    time
    num
    id
  }
  end:blockIDByTime(time: "2019-02-01T00:00:00Z") {
    time
    num
    id
  }
}

Outputs:

{
  "data": {
    "start": {
      "time": "2019-01-01T00:00:00Z",
      "num": 35058781,
      "id": "0216f45d4cf4dd026436e270a38d4a6f4b8ff6b66c51169959c7d15cc546c454"
    },
    "end": {
      "time": "2019-02-01T00:00:00Z",
      "num": 40401308,
      "id": "0268799ce334f320485b80dd632db5168c6d894a289b82dc721e029a3a50038c"
    }
  }
}

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,
 "irreversible_only": true,
 "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. 0 means the beginning of the chain. See Never missing a beat
irreversible_only boolean optional, defaults to false Limits output to events that happened in irreversible blocks. Only supported on get_action_traces
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 blindly apply changes to a local map of rows, you will always be in sync with the latest changes, because step: undo flips operations (a REM becomes an INS, and the previous/next values for INS are inverted).

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",
  "irreversible_only": true,
  "data": {
    "accounts": "eosio.token",
    "action_name": "transfer",
    "with_inline_traces": true,
    "with_dtrxops": true,
    "with_ramops": true
  }
}

Information about receiver, account and action_name

Actions on the EOS blockchain are identified by a triplet receiver/account/action_name * The code on the receiver is called with the method account/action_name * An action is considered a “notification” when the receiver is different from the account field. That receiver may or may not contain instructions to run for that account/action_name pair. More details here

Request input data fields:

Name Type Options Description
accounts string required Pipe | separated list of accounts to match.
action_names string optional Pipe | separated list of actions to match.
receivers string optional, defaults to the same value as accounts Pipe | separated list of receivers to match.
with_ramops boolean optional Stream RAM billing changes and reasons for costs of storage produced by each action (See RAMOp).
with_tableops boolean optional Stream table operations produced by each action (See TableOp).
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 (See DTrxOp).

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 JWT in a HTTP Header, like the following:

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

POST /v1/auth/issue

NOTE: This method is called on a DIFFERENT domain: https://auth.dfuse.io/v1/auth/issue

First, obtain a long-term API key (go to https://app.dfuse.io).

Sample request:

curl -XPOST \
     -H "Content-Type: application/json" \
     --data '{"api_key":"web_ebf6733085d83117b0ad7f9999bd169c"}' \
     "https://auth.dfuse.io/v1/auth/issue"

JSON payload input parameters

Name Type Options Description
api_key string required Long-term API key

Response

Returns a AuthTokenResponse.

GET /v0/block_id/by_time

Sample request:

curl -H "Authorization: Bearer $TOKEN" "https://mainnet.eos.dfuse.io/v0/block_id/by_time?time=2019-03-04T10:36:14.5Z&comparator=gte"

Sample response (for time=2019-03-04T10:36:14.6Z&comparator=gte)

{
  "block": {
    "id": "02bb43ae0d74a228f021f598b552ffb1f8d2de2c29a8ea16a897d643e1d62d62",
    "num": 45826990,
    "time": "2019-03-04T10:36:15Z"
  }
}

Fetches the block ID, time and block number for the given timestamp.

Input parameters

Name Type Description
time DateTime Reference timestamp (ISO8601 extended format, ex: 2019-03-04T10:36:14.5Z)
comparator String Comparison operator for the block time. Should be one of gt, gte, lt, lte or eq.

Response

Returns a block JSON object, containing the following fields:

Name Type Description
id string Block ID
num number (uint32) Block Number
time DateTime Timestamp of the matching block (according to its production schedule, so always aligned with 500ms time slots)

GET /v0/transactions/:id

Fetching the transaction lifecycle associated with the provided path parameter :id.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/transactions/1d5f57e9392d045ef4d1d19e6976803f06741e11089855b94efcdb42a1a41253"

This method returns transaction information regardless of the actual lifecycle state be it deferred, executed, failed or cancelled. This means that deferred transactions are handled by this method, via a transaction with a delay_sec argument pushed to the chain or created by a smart contract.

Refers to the TransactionLifecycle to have a better overview of lifecycle related properties that are available in the response.

Path parameters

Name Type Options Description
:id string required Contract account targeted by the action.

Response

Here is a sample response, for transaction id 1d5f57e9392d045ef4d1d19e6976803f06741e11089855b94efcdb42a1a41253 on EOS Mainnet:

{
  "transaction_status": "executed",
  "id": "1d5f57e9392d045ef4d1d19e6976803f06741e11089855b94efcdb42a1a41253",
  "transaction": {
    "expiration": "2019-04-16T14:36:11",
    ...,
    "actions": [
      {
        "account": "eosio.token",
        "name": "transafer",
        ...,
      }
    ],
  },
  "execution_trace": {
    "id": "1d5f57e9392d045ef4d1d19e6976803f06741e11089855b94efcdb42a1a41253",
    ...,
    "receipt": {
      "status": "executed",
      "cpu_usage_us": 1191,
      "net_usage_words": 12
    },
    "elapsed": 85570,
    "net_usage": 96,
    "scheduled": false,
    "action_traces": [
      {
        "receipt": {
          "receiver": "eosio.token",
          ...,
        },
        ...,
        "inline_traces": [
          ...,
        ]
      }
    ]
  }
}

Returns a TransactionLifecycle.

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" --header "Authorization: Bearer YOURTOKENHERE" 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

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). See below for the special meaning of value 0.
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 its maximum value: 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.

When start_block is unspecified (value: 0), it takes a special meaning depending on the context: * When the sort order is ascending, a start_block of 0 means the beginning of the chain. * When the sort order is descending, a start_block of 0 means either the HEAD of the chain (if with_reversible is true) or the LIB (Last Irreversible Block) of the chain (if with-reversible is false)

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.

POST /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.
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.
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.

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/key_accounts

Fetches the accounts controlled by the given public key, at any block height.

NOTE: this endpoint is a drop-in replacement for the /v1/history/get_key_accounts API endpoint from standard nodeos. Simply tweak the URL, and add the Bearer token.

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/key_accounts?public_key=EOS7YNS1swh6QWANkzGgFrjiX8E3u8WK5CK9GMAb6EzKVNZMYhCH3"

Requesting past blocks

The block_num parameter determines for which block height you want a list of accounts associated to the given public key. This can be anywhere in the chain’s history.

If the requested block_num is irreversible, you will get an immutable list of accounts. Otherwise, there are chances that the returned value moves as the chain reorganizes.

Input parameters

Name Type Options Description
public_key PublicKey required The public key to fetch controlled accounts for.
block_num number optional, defaults to head block num The block number for which you want to retrieve the list of accounts.

Response

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

{
  "block_num": 10000000,
  "accounts": [
    "eoscanadacom"
  ]
}
Name Type Options Description
block_num number required Block number used to serve your request. Will be the head block_num if it was not provided or 0 was passed as block_num, otherwise, will be the block_num you’ve passed in the request.
accounts array<AccountName> required An array of account names that the public key is associated with, sorted alphabetically.

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_num": 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 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/table_scopes

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

Sample request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://mainnet.eos.dfuse.io/v0/state/table_scopes?account=eosforumdapp&table=proposal"

NOTE: Not to be confused with /v0/state/tables/scopes which retrieves the actual tables. Paired with this endpoint, you can get a consistent view of all tables in a contract.

Requesting past blocks

The block_num parameter determines for which block you want the list of scopes for the given contract account’s table. This can be anywhere in the chain’s history.

If the requested block_num is irreversible, you will get an immutable list of accounts. Otherwise, there are chances that the returned value moves as the chain reorganizes.

Input parameters

Name Type Options Description
account AccountName required Contract account holding the requested table.
table TableName required The name-encoded table name you want to retrieve scopes from. 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 scopes snapshot.

Response

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

{
  "block_num": 9000000,
  "scopes": [
    "aus1genereos",
    "eoscanadacom"
  ]
}
Name Type Options Description
block_num number required Block number used to serve your request. Will be the head block_num if it was not provided or 0 was passed as block_num, otherwise, will be the block_num you’ve passed in the request.
scopes array<Name> required An array of scopes for the given table, sorted alphabetically.

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 all rows for a table in a given contract 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"

NOTE: Not to be confused with /v0/state/table_scopes which retrieves the only the scope names. Paired with this endpoint, you can get a consistent view of all tables in a contract.

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:

Errors

HTTP Codes

The dfuse API uses the following HTTP 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 or while authenticated, you do not have access to specified resource.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You are using an HTTP verb that is not allowed for this resource.
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.

The HTTP response will always contain a body with a specific error format that is defined in the section below. If the body does not contain anything or is not in the format described below, please report this as a bug to our team.

Error Format

Each error message structure for both the REST API and WebSocket API is fully standardized across all our API calls.

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 happened and what went wrong. 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.

Name Type Options Description
code string required Unique code field which descriptively identifies the error.
trace_id string required Unique identifier of the request.
message string required Human-readable english string about why the error happen and what was wrong, never translated.
details map<string, any> optional Key/value pair object contains specific details about what went wrong for a given error code.

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.

PublicKey

A public key is the publicly known portion of the private key/public key pair that a user can generate.

AuthTokenResponse

Example payload:

{
  "token": "eyJhbGciOiJLTVNFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTA2OTIxNzIsImp0aSI6IjQ0Y2UzMDVlLWMyN2QtNGIzZS1iN2ExLWVlM2NlNGUyMDE1MyIsImlhdCI6MTU1MDYwNTc3MiwiaXNzIjoiZGZ1c2UuaW8iLCJzdWIiOiJ1aWQ6bWRmdXNlMmY0YzU3OTFiOWE3MzE1IiwidGllciI6ImVvc3EtdjEiLCJvcmlnaW4iOiJlb3NxLmFwcCIsInN0YmxrIjotMzYwMCwidiI6MX0.k1Y66nqBS7S6aSt-zyt24lPFiNfWiLPbICc89kxoDvTdyDnLuUK7JxuGru9_PbPf89QBipdldRZ_ajTwlbT-KQ",
  "expires_at": 1550692172
}
Name Type Description
token string The JWT to be used with all API calls, including WebSocket.
expires_at timestamp An UNIX timestamp (UTC) indicating when the JWT will expire.

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_num": 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_num": 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…).

CreationTree

A CreationTree represents the creation-ordered tree of notifications (require_recipient calls), inline actions (send_inline calls) and context free inline actions (send_context_free_inline calls) as defined in the smart contract. The CreationTree is per transaction and might not be present in the returned response. In this case, it means the creation tree is exactly the same as the execution one.

Restrictions The opposite is not true however, it is possible to get a CreationTree and it will still be the same as the execution tree. We trim off the CreationTree as a best effort, it still possible to get a CreationTree mapping 1-to-1 with the execution tree. We suggest computing the tree and checking if there are any differences on the client side if you need to be 100% sure they are different in the presence of the field.

The actual creation order can be different than the execution order, this is because the EOSIO platforms first collect the creation of actions and then execute them, some within a totally new context like send_inline or within the current execution context require_recipient. Moreover, the order in which the execution order is performed is fixed, notifications are executed first (as well as the notifications created as a side-effect of the on-going execution of the notification) then context free inline actions and last the inline actions.

Assuming that you have in your smart contract the following sequence of operations:

send_context_free_inline(...)
require_recipient(...)
send_inline(...)

The creation order is send_context_free_inline, require_recipient, send_inline but the actual execution order and the corresponding execution traces will be in order require_recipient, send_context_free_inline and send_inline instead, quite different!

The CreationTree represents this full ordered hierarchy of actions creation. The tree is encoded as a flat-list each array element being a triplet (encoded in an array): [nodeId, parentId, actionIndex]. Each triplet in the list represents a tree node. The first element of the triplet is a unique id for the node among all nodes in the tree. The second is the parent’s node id, a value of -1 means it’s a root node. The third is the action index within the transaction to map this creation node to, going depth-first in inline_actions, 0-based indexed.

Here an example of creation tree’s flat list, an execution tree and its corresponding creation tree.

CreationTree flat-list received as response from us

[
    [0, -1, 0],
    [1, 0, 1],
    [2, 1, 3],
    [3, 1, 9],
    [4, 0, 2],
    [5, 0, 4],
    [6, 0, 5],
    [7, 0, 7],
    [8, 6, 8],
    [9, 6, 6],
]

Execution traces within the transaction

Execution Tree              (actionIndex 0)
    ├── notify1             (actionIndex 1)
    ├── notify2             (actionIndex 2)
    ├── notify3             (actionIndex 3)
    ├── cf_inline1          (actionIndex 4)
    ├── inline1             (actionIndex 5)
    │   ├── notify4         (actionIndex 6)
    │   ├── cf_inline2      (actionIndex 7)
    │   └── inline3         (actionIndex 8)
    └── inline2             (actionIndex 9)

Represented creation tree, constructed using `CreationTree` flat-list and execution traces

Creation Tree               (0, -1, actionIndex 0)
    ├── notify1             (1, 0, actionIndex 1)
    │   ├── notify3         (2, 1, actionIndex 3)
    │   └── inline2         (3, 1, actionIndex 9)
    ├── notify2             (4, 0, actionIndex 2)
    ├── cf_inline1          (5, 0, actionIndex 4)
    └── inline1             (6, 0, actionIndex 5)
        ├── cf_inline2      (7, 6, actionIndex 7)
        ├── inline3         (8, 6, actionIndex 8)
        └── notify4         (9, 6, actionIndex 6)

Creation Tree Node

Index Symbolic Name Type Description
0 nodeId int Unique id for the node among all nodes in the tree.
1 parentId int Parent’s node id, a value of -1 means it’s a root node.
2 actionIndex int Action index within the transaction to map this creation node to, going depth-first in inline_actions, 0-based indexed.

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 Name 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.

DTrxOp

See this source code for reference

ExtDTrxOp

See this source code for reference

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:

TableOp

A TableOp represents a table operation, creation or removal of a contract’s table. The table is represents as triplet <account>/<table>/<scope>. No two tables can exist at the same time with the same triplet.

Name Type Options Description
op string required Operation, one of REM (removal) 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 table operation occurred.
table TableName required Contract account’s table affected by this table operation.
scope Name required Table’s scope affected by this table operation.
payer AccountName required Represents the payer of this table, i.e. the table represented by the account/table/scope triplet.

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": { ... },
  "creation_tree": [
    ...
  ],
  "dtrxops": [
    {
      "op": "CREATE",
      ...
      "trx_id": "da1abcf7e205cf410c35ba3d474fd8d854a7513d439f7f1188d186493253ed24",
      "trx": { ... }
    }
  ],
  "ramops": [ ... ],
  "tableops": [ ... ],
  "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
creation_tree CreationTree optional Represents the creation order of actions within this transaction.
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.
tableops array<TableOp> optional A list of table operations, including operation, contract account, table, scope and payer.
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

Release Notes

2019-04-24

2019-04-23

2019-04-17

2019-04-10

2019-03-21

2019-03-05

2019-01-29

2019-02-18

2019-01-22

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