GET /v0/state/table

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

Usage

Sample request:


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

fetch('https://mainnet.eos.dfuse.io/v0/state/table?account=eosio.token&scope=b1&table=accounts&block_num=25000000&json=true', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJLTVNFUzI1Ni...'
  }
}).then(console.log)

headers = { 'Authorization' : 'Bearer eyJhbGciOiJLTVNFUzI1Ni...' }
r = requests.get('https://mainnet.eos.dfuse.io/v0/state/table?account=eosio.token&scope=b1&table=accounts&block_num=25000000&json=true', headers=headers, verify=False)
j = json.loads(r.text)
print(json.dumps(j, indent=4))

req, err := http.NewRequest("GET", "https://mainnet.eos.dfuse.io/v0/state/table?account=eosio.token&scope=b1&table=accounts&block_num=25000000&json=true", nil)
if err != nil {
// handle err
}
req.Header.Set("Authorization", "Bearer eyJhbGciOiJLTVNFUzI1Ni...")

resp, err := http.DefaultClient.Do(req)
if err != nil {
// handle err
}
defer resp.Body.Close()

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

account
required
AccountName     Contract account targeted by the action.
scope
required
AccountName     Contract account targeted by the action.
table
required
TableName     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
Optional
Number     The block number for which you want to retrieve the consistent table snapshot.
json
Optional
Boolean     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
Optional
String     Defaults to name, see KeyType for valid values. How to represent the row keys in the returned table.
with_block_num
Optional
Boolean     Defaults to false. Will return one block_num with each row. Represents the block at which that row was last changed.
with_abi
Optional
Boolean     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

key
required
String     The encoded key (as requested with key_type) for the row
payer
required
AccountName     The name-encoded account that was billed RAM to store this row.
block
Optional
Number (uint32)     The block num when this row was last modified (as requested by with_block_num).
json
Optional
Object     Returned 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
Optional
String     Returned when json: false, absent otherwise | A string-encoded hexadecimal representation of the binary data in that row.
error
Optional
String     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.