Introduction

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

• Telegram channel: dfuse API.
• GitHub: dfuse repositories.
• Technical discussions on EOS.IO StackExchange with the tag dfuse, and feel free to report your bugs.

---

Getting started

JavaScript

JavaScript/TypeScript Example Code

import { createDfuseClient } from "@dfuse/client";
import { WebSocketLink } from "apollo-link-ws";
import ApolloClient from "apollo-client/ApolloClient";
import { InMemoryCache } from "apollo-cache-inmemory";
import { gql } from "apollo-boost";
import nodeFetch from "node-fetch";
import * as ws from "ws";

(global as any).WebSocket = ws;
(global as any).fetch = nodeFetch;

if (process.env.DFUSE_API_KEY == null) {
  console.log("Missing DFUSE_API_KEY environment variable")
  process.exit(1)
}

const dfuseClient = createDfuseClient({
  apiKey: process.env.DFUSE_API_KEY!,
  network: "mainnet",
});

const apolloClient = new ApolloClient({
  cache: new InMemoryCache(),
  link: new WebSocketLink({
    uri: dfuseClient.endpoints.graphqlStreamUrl,
    options: {
      connectionParams: async () => {
        const apiToken = await dfuseClient.getTokenInfo()

        return {
          Authorization: `Bearer ${apiToken.token}`
        };
      }
    },
    webSocketImpl: ws,
  }),
});

apolloClient.subscribe({
  query: gql`
    subscription {
      searchTransactionsForward(query: "status:executed") {
        trace { matchingActions {receiver account name json }}
      }
    }
  `
}).subscribe({
  start: (subscription) => { console.log("Started", subscription) },
  next: (value) => {
    const trace = value.data.searchTransactionsForward.trace;
    trace.matchingActions.forEach((action: any) => {
      console.log(`Action ${action.receiver}/${action.account}:${action.name}`)
    });
  },
  error: (error) => { console.log("Error", error) },
  complete: () => { console.log("Completed") },
});

This simple program demonstrates how easy it is to query our GraphQL API. It:

• Uses our client-js library to handle API token management
• Instantiates an ApolloClient
• Executes a simple GraphQL streaming search subscription
• Prints out each message received

Running the example

First of all, visit https://app.dfuse.io to get YOUR_API_KEY.

• git clone https://github.com/dfuse-io/example-graphql-apollo.git
• cd example-graphql-apollo
• yarn install
• DFUSE_API_KEY=YOUR_API_KEY_HERE yarn start

Useful links

• GitHub: @dfuse/client
• Docs: dfuse Search query language
• On mainnet: GraphiQL A graphic graphql editor and API documentation browser.
• GitHub: Stream action rates example This example demonstrates how to use the dfuse GraphQL APIs in a React application to livestream the average rates from the top actions. A live demo is available here

---

Python

Python Example Code

import http.client
import json
import ssl
import sys

import grpc

from graphql import graphql_pb2_grpc
from graphql.graphql_pb2 import Request

ssl._create_default_https_context = ssl._create_unverified_context


def token_for_api_key(apiKey):
    connection = http.client.HTTPSConnection("auth.dfuse.io")
    connection.request('POST', '/v1/auth/issue', json.dumps({"api_key": apiKey}))
    response = connection.getresponse()

    if response.status != 200:
        raise Exception(f" Status: {response.status} reason: {response.reason}")

    token = json.load(response)['token']
    connection.close()

    return token


def create_dfuse_client():
    credentials = grpc.access_token_call_credentials(token_for_api_key(sys.argv[1]))
    channel = grpc.secure_channel('mainnet.eos.dfuse.io:443',
                                  credentials=grpc.composite_channel_credentials(grpc.ssl_channel_credentials(),
                                                                                 credentials))
    return graphql_pb2_grpc.GraphQLStub(channel)


query = '''
subscription {
  searchTransactionsForward(query: "status:executed", limit: 10) {
    trace {
      id
      matchingActions{
        account
        receiver
        name 
        json
      }
    }
  }
}
'''

dfuse_graphql = create_dfuse_client()
stream = dfuse_graphql.Execute(Request(query=query))

for rawResult in stream:
    result = json.loads(rawResult.data)
    print(result['searchTransactionsForward']['trace']['matchingActions'])

This simple program demonstrates how easy it is to query our GraphQL API over gRPC in Python. It:

• Request a token from our authentication API
• Creates a gRPC connection with credentials
• Instantiates a GraphQL client
• Executes a simple GraphQL query
• Prints the response

Running the example

First of all, visit https://app.dfuse.io to get YOUR_API_KEY.

• git clone https://github.com/dfuse-io/example-graphql-python.git
• cd example-graphql-python
• python3 example.py YOUR_API_KEY_HERE

Useful links

• Docs: dfuse Search query language
• On mainnet: GraphiQL A graphic graphql editor and API documentation browser.

---

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 {
				fmt.Println("No more result available")
				break
			}

			log.Fatalf("reception error: %s", err)
		}

		fmt.Println("Received response:", response.Data)
	}
}

This simple program demonstrates how easy it is to query our GraphQL API over gRPC. It:

• Uses our go client to retrieve a JWT
• Creates a gRPC connection with credentials
• Instantiates a GraphQL client
• Executes a simple GraphQL query
• Prints the response

Before you begin

• Visit golang gRPC prerequisites
• Then make sure that protoc is accessible from your $PATH

Get the source code

• git clone https://github.com/dfuse-io/example-graphql-grpc.git
• git clone https://github.com/dfuse-io/graphql-over-grpc.git

Generate graphql.pb.go

• protoc -I graphql-over-grpc graphql/graphql.proto --go_out=plugins=grpc:./example-graphql-grpc

Get project dependencies

• cd example-graphql-grpc
• go mod init main
• go mod tidy

Run it!

• Visit https://app.dfuse.io to get YOUR_API_KEY
• go run main.go YOUR_API_KEY_HERE

Useful links

• Docs: dfuse Search query language
• On mainnet: GraphiQL A graphic graphql editor and API documentation browser.
• GitHub: Push Notification Example A fully functional example sending push notifications base on a graphql query results.
• GitHub: Protobuf service definition for GraphQL

---

Other languages

gRPC is available for a multitude of languages.

You can easily call the GraphQL endpoint with those languages after issuing a fresh JWT from our authentication endpoint.

See the Protobuf service definition, and the GraphQL docs to get the action going.

---

More examples

JavaScript: Action Rates

This example uses GraphQL Subscriptions & Apollo Client to display action rates per minutes, with a graph and a grid.

Source code & Live demo

Go: push notifications

A fully functional example sending push notifications to a mobile app, based on GraphQL query results.

Source code

JavaScript: node.js example

This project showcases the use of the dfuse Client Library to easily stream all transfers happening on the EOS Mainnet.

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:

• A long-lived API key, which looks like server_abcdef123123123000000000000000000, used to get short-lived JWT.

• A short-lived JWT, used to do any call on the dfuse Platform, which looks like: eyJhbGciOiJLTVNFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTYxMzI4MjAsImp0aSI6IjQwNWVmOTUxLTAwZTYtNGJmNC1hZWMxLTU0NTU1ZWMzMTUwMiIsImlhdCI6MTU1NjA0NjQyMCwiaXNzIjoiZGZ1c2UuaW8iLCJzdWIiOiJ1aWQ6MHdlbnU2NmUwNzU4OWRhODY4MWNlIiwiYWtpIjoiM2NhYWEzYzA3M2FlZjVkMmYxOGUwNjJmZDkzYzg3YzMzYWIxYzA1YzEzNjI3NjU2OTgzN2Y5NDc5NzZlMjM0YSIsInRpZXIiOiJmcmVlLXYxIiwic3RibGsiOi0zNjAwLCJ2IjoxfQ.000HeTujIuS_LRvvPN6ZRCmtoZqZyV6P1enNBviwK8v7Tf7BLHJIrEpQoEREKSIMdZWPrMQl_OE55yJP0MxUDA

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
}

• Get JWT + Expiration time from cache (localStorage, disk, etc..)
• If token is expired, is near expiration or is absent from cache, fetch a new token through /v1/auth/issue, and cache the response.
• Call dfuse with a JWT token.

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.

• server: rate limits JWT issuance aggressively; low number of IPs; accepts large number of calls per IP.
• mobile: adapts rate limits JWT issuance to normal growth of new users, eventually manageable by yourself; large number of IPs; rate limits the number of calls per IP.
• web: adapts rate limits JWT issuance to normal growth, eventually manageable by yourself; enforces Origin; each JWT is limited to a tiny amount of IPs; heavily rate limits the number of calls per IP.

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:

• POST REST calls to /graphql, for GraphQL Queries only.

• The Apollo Subscriptions Transport protocol, based on WebSocket

• GraphQL over gRPC (for server-to-server streaming communications):

  • Method: dfuse.eosio.v1.GraphQL/Execute

  • The endpoints provide reflection to get the .proto schemas.

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

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.

Navigating forks with the GraphQL search queries and subscriptions

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.

API Reference

This section contains subscriptions and queries that can be performed against our GraphQL interface.

The best way to explore the GraphQL schemas, available subscriptions & queries as well as all arguments is to use the GraphiQL or the Playground web pages we provide for dfuse GraphQL API available at the different Endpoints.

The GraphQL schema is fully documented and should answer most of your questions regarding the data it serves. Under GraphiQL or Playground, simply place your cursor somewhere and press Ctrl+<Space> to see completion for current location.

Subscriptions

Name	Description	Sample Query
searchTransactionsForward	Search the blockchain forward for transaction execution traces based on query. Warning always consider the undo field in forward searches, which signal that the matching element was in fact REMOVED from the chain because of blocks reorganization.	GraphiQL Sample
searchTransactionsBackward	Search the blockchain backward for transaction execution traces based on query. Note The undo field is not used in backwards search.	GraphiQL Sample

Queries

Name	Description	Sample Query
searchTransactionsForward	Search the blockchain forward for transaction execution traces based on query. When the returned cursor is empty, it means you have reached the end of the specified block range. Warning Always consider the undo field in forward searches, which signal that the matching element was in fact REMOVED from the chain because of blocks reorganization. See also the streaming version under Subscription.	GraphiQL Sample
searchTransactionsBackward	Search the blockchain backward for transaction execution traces based on query. When the returned cursor is empty, it means you have reached the end of the specified block range. See also the streaming version under Subscription	GraphiQL Sample
blockIDByTime	Return the block ID found around the given time, based on the comparator provided.	GraphiQL Sample

Sample Queries

To get you started, here are a few sample queries and how to read them.

The following query (try it on GraphiQL):

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
        }
      }
    }
  }
}

• Issues a GraphQL subscription call (streaming results); that’s the subscription prefix.
• Starts at the head of the chain (new real-time blocks); that’s lowBlockNum: 0, which defaults to the HEAD of the chain.
• Streams the 20 next transactions to successfully execute, which include EOS transfers; that’s the query (see Release notes for the note about implicit status:executed)
• Once we got 20 transactions, close the subscription; that’s the limit.
• Retrieve the matching actions; that’s the matchingActions subquery. Note there could be many in a single transaction
• For each matching action, we also retrieve the action that caused this transfer, if any. If a token transfer was initiated by another smart contract, creatorAction will be non-null, and will point to the action which caused the creation (see the GraphQL schema for full details).

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 (try it on GraphiQL):

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

• Issues a GraphQL query that retrieves two queries at once
• Each querying the block ID and number less or equal to the date specified in time.
• It remaps the result to start and end respectively.

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:

• with_progress: allowing you to keep tabs on what you have seen up to the second
• start_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 block 25000100 if the head block was 25000150

• 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 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:

• new this the first time we see this DB operation, in a brand new block.
• undo happens during fork resolution, it means the DB operation is no longer part of the longest chain. Similar to a ROLLBACK in DB semantics.
• redo happens during fork resolution, it means the DB operation is now in the longest chain (and was previously seen in this connection). Similar to simply reapplying the change after it was rolled back.

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
• get_transaction_lifecycle
• get_table_rows
• get_head_info
• unlisten
• ping

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

• fetch: true is not supported for get_action_traces
• listen: true requests will stream ActionTrace objects.
• irreversible_only: true ensure that you only get actions from irreversible blocks. If you call it with start_block: (current head block), you will have to wait until that block becomes irreversible before you see any data streaming back.

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
• progress
• error

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:

• POST https://auth.dfuse.io/v1/auth/issue: Exchange a long-term API key for a short-lived (24 hours) API Authentication Token (JWT).

• (Beta) GET /v0/block_id/by_time: Get the block ID produced at a given time

• (Beta) GET /v0/transactions/:id: Fetching the transaction lifecycle associated with the provided path parameter :id.

• (Beta) GET /v0/state/abi: Fetch the ABI for a given contract account, at any block height.

• (Beta) POST /v0/state/abi/bin_to_json: Decode binary rows (in hexadecimal string) for a given table against the ABI of a given contract account, at any block height.

• (Beta) GET /v0/state/permission_links: Fetching snapshots of any account’s linked authorizations on the blockchain, at any block height.

• (Beta) GET /v0/state/table: Fetching snapshots of any table on the blockchain, at any block height.

• (Beta) GET /v0/state/table/accounts: Fetching snapshots of any table on the blockchain, at any block height, for a list of accounts (contracts).

• (Beta) GET /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).

• (Beta) GET /v0/search/transactions: Structure Query Engine (SQE), for searching the whole blockchain history and get fast and precise results.

• (Beta) POST /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.

• Other /v1/chain/...: Reverse-proxy of all standard chain requests to a well-connected node.

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

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

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

• with HTTP Header: X-Eos-Push-Guarantee: in-block, the call is blocking until the transaction makes it into a valid block

• with 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 (with handoffs:2 and handoffs: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 and block_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" --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 binary rows (in hexadecimal string) for a given table against the ABI of 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,
  "account_names": [
    "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.
account_names	array<AccountName>	required	An array of account names that the public key is associated with, sorted alphabetically.

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_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:

• name (default) for EOS name-encoded base32 representation of the row key
• hex 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/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:

• name (default) for EOS name-encoded base32 representation of the row key
• hex 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 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:

• name (default) for EOS name-encoded base32 representation of the row key
• hex 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.

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.

SEARCH

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 executed
• account: matches the account called on the action. Not to be mixed up with receiver. 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 payload
• auth: 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 transaction
  • auth: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 transaction, here, only executed. NOTE: if status is not specified, an implicit status:executed is added to the query.
• scheduled:true will match deferred transactions
• notif:true will match only notifications, excluding input action or other inline actions.
• input:true will match only the top-level actions (those present in the original transactions, and not as a side effect of contract execution).
• event.sub.fields: dfuse Events indexing matching specific fields, see dfuse Events for details.
• data.sub.fields: a good number of action-specific fields can be matched for equality. Ex: data.from and data.to (present in transfer operations).
  • lists are flattened, and terms matched when the query is present in the list.
  • nested documents fields are separated by ., so data.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 matches setabi actions with an ABI data hashing to a given SHA256 fingerprint
  • data.code:SHA256 matches setcode 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 action
  • ram.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.

dfuse Events

dfuse Events are a powerful way to give smart contract developers a way to ask dfuse Search to index their transactions, with arbitrary key/value pairs.

From within you smart contract, by simply sending an inline action to dfuseiohooks:event, you can instruct dfuse Search to index some fields with arbitrary data (within limits).

Once on chain, the search term event.field:value will allow you to retrieve those actions, anywhere on the dfuse Platform.

Getting started

Say a smart contract manages virtual pets. Each pet has a unique ID and a kind (dog, cat, mouse, rabbit).

Say you have an action train(pet_id) that trains and increases whatever features of your pet.

If you want to list all trainings for dogs, you’re short of luck: the action does not contain the kind of pet being trained here.

By adding an inline action to dfuseiohooks:event in your smart contract, and exfiltrating the missing bit of data, such as pet_kind=dog in the data field, you will immediately be able to search for event.pet_kind:dog action:train receiver:yourcontract anywhere on the dfuse Platform.

The gist of the EOSIO contract implementation is:

const std::string& pet_kind = get_pet_kind(pet_id);

eosio::action(
    std::vector<permission_level>(),
    "dfuseiohooks"_n,
    "event"_n,
    std::make_tuple(
      // Parameter `auth_key`
      std::string(""),
      // Parameter `data`
      std::string("pet_id=" + pet_id + "&pet_kind=" + pet_kind)
    )
).send_context_free();

Example contract

See an example implementation from a sample smart contract.

Specifications

Destination: The inline action must be sent to contract dfuseiohooks with the action name event. The action signature is: event(string auth_key, string data).

Cost: be cheap, and use an inline context-free action to have minimal impact on transaction costs. Also, there will never be code deployed on dfuseiohooks, so it executes extremely fast.

Authorization: Specify no authorization (std::vector<permission_level>()) when issuing a context-free action.

Indexing: Only ONE such event per action will be indexed. If limits aren’t breached, the parameters in data will be indexed as event.field in dfuse Search, attached to the action that created the inline to dfuseiohooks:event. This allows you to search for receiver:yourcontract event.field:value or other combinations.

Action parameters

Name	Type	Options	Description
auth_key	string	required	The empty string (limited access) or a valid dfuse Events Key if you have one. See Indexing Limits for details.
data	string	required	A string containing the key/value pair list to index, as an RFC 3986 URL encoded string (i.e. key1=value1&key2=value2).

Indexing Limits

An empty auth_key parameter imposes those limits to the indexing:

• A key/value pair under data is indexed only if:
  • the key has 16 characters or less
  • the value has 64 characters or less
  • there are no more than 3 keys (for unauthenticated calls)

If you need more than 3 key/values or want more than 64 bytes of value data, contact us to get a dfuse Events Key for your contract. NOTE: If your auth_key is invalid or used within the wrong contract account, normal restrictions apply.

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:

• create_table: creation of a table
• deferred_trx_add: storing deferred transaction
• deferred_trx_cancel: canceling deferred transaction
• deferred_trx_pushed: creating deferred transaction
• deferred_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 of action_idx when op is deferred_trx_removed.
• deleteauth: deleting authority
• linkauth: linking authority
• newaccount: creating new account
• primary_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 table
• secondary_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 account
• setcode: updating contract for account
• unlinkauth: unlinking authority
• updateauth_create: creating new permission
• updateauth_update: updating permission

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-07-09

• Deprecation of non-executed transactions in Search:
  • According to our analysis, this change touches close to 0% of our userbase.
  • The status:executed constraint is still going to be implicit; querying the status field is therefore deprecated.
  • Leaving status:executed in the query will still be supported for a while, to not break existing queries, but will have no effect.
  • Querying status:soft_fail will now fail.
  • Using status: in an OR clause will now fail.
  • Deferred transaction failures are not indexed anymore, and not searchable through the different search endpoints, following the principle of least surprise for most of our users.
  • Searches for receiver:account will now see eosio:onerror actions on that account. Those onerror actions, when soft_failed, are actually successfully executed, and can therefore mutate state and do other things, so thay are included, but the deferred transaction that failed (and which state’s mutations were not applied), is not going to be indexed anymore.
  • Ram consumption reported by ram.consumed:account and ram.released:account will not cover the status:expired and status:hard_failed transactions. Note that status:expired was already previously absent, so an imbalance was possible if computing the full amount of RAM for a given account.

2019-05-07

• Beta dfuse Events is now live.

2019-04-24

• Added in PREVIEW mode: GET /v0/transaction/:id to fetch the transaction lifecycle associated with the :id path parameter.

2019-04-23

• Breaking change : /v1/chain/push_transation with in-block guarantee now requires authentication.

2019-04-17

• Beta Brand new GraphQL interface to EOSIO chain data. See documentation and announcement.

• New streaming search capabilities (through GraphQL):

  • You can now stream dfuse Search query results in real-time.

  • It allows you to navigate forks with greater ease than before.

  • Provides a chain-wide cursor, that allows you to continue listing transactions from where you left off, with message-per-message granularity (instead of block granularity, as previously).

  • The cursor allows you to search backwards (to get recent transactions), and then flip the direction and listen to real-time events, guaranteeing there’s no gaps.

  • See announcement

2019-04-10

• Breaking change (low risk): Search requests that do not specify status: in the query will automatically search only for status:executed transactions. Some people were surprised to receive failed transactions. This protects you from making wrong decisions because of an oversight.

2019-03-21

• Added irreversible_only flag to get_action_traces websocket request.

2019-03-05

• Added in PREVIEW mode: GET /v0/state/key_accounts to fetch the list of accounts controlled by the given public key, at any block height.

• Added in PREVIEW mode: GET /v0/state/table_scopes to fetch the list of scopes of a given table on a contract’s account, at any block height.

• Added console outputs to action traces throughout the dfuse platform.

• Added creation_tree, visible on eosq.app. See announcement Best way to consume this is through the GraphQL interface.

2019-01-29

• Clarified the use of cursor, and describe the behavior of forked_head_warning.

• Improved the documentation of the query language.

2019-02-18

• POST /v1/chain/push_transaction now supports new push-guarantees: handoff:1, handoffs:2 and handoffs:3, allowing more flexible rules to guarantee transaction delivery based on your application’s requirements. See announcement

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 to TableDeltaResponse, and TableDelta is now the inner data field of that response.

• Renamed TableSnapshot to TableSnapshotResponse, and TableRows is now the inner data field of that response.

• Renamed TransactionLifecycle to TransactionLifecycleResponse, and TransactionLifecycle is now the inner data 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 on accounts 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 and action_names in the get_action_traces WS request.

  • The account, receiver and action_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

2018-11-22

Breaking changes

• Breaking change get_table_rows listen response fields undo: true and redo: true are replaced by step: "undo" and step: "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 for in-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.
• get_actions was renamed to: get_action_traces
• get_action_traces:
  • with_deferred was renamed to with_dtrxops
• get_table_rows:
  • data.table_name parameter renamed to data.table (for consistency with the REST API)
  • data.verbose option removed
  • the struture of the rows has changed in the table_delta message.
  • dbop is now a nested object
  • dbop.key is now a name-encoded value
  • dbop.old and dbop.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: the fetch: true argument now returns a snapshot of the table at the block requested. Adding listen: true streams changes as they arrive.

• get_table_rows: when switching longest chain, you will now receive undo and redo 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 a block_time

2018-10-15

• get_actions request: renamed parameter with_ram_costs to with_ramops (get_actions is now get_action_traces).