TRAIT DataGate API
  1. State
TRAIT DataGate API
  • Intro
  • History
    • Blocks
      POST
    • Transactions
      POST
    • Events
      POST
  • State
    • Info of on-chain entities
      POST
    • Raw single values of blockchain storage
      POST
    • Raw collections of blockchain storage
      POST
  • Tokens
    • Balances of tokens
      POST
    • Transfers of tokens
      POST
  • Submit new transaction
    • Validate transfer of token TRAIT
      POST
    • Validate transfer of fungible tokens
      POST
    • Validate transfer of nft tokens
      POST
    • Validate clearing transaction of an AppAgent
      POST
    • Build info for new transaction
      POST
    • Submit transaction
      POST
    • Get transaction status
      POST
  1. State

Raw collections of blockchain storage

POST
https://api.trait.tech/state/storage_map
State
The endpoint provides raw values of blockchain state used by internal logic of the blockchain.
This endpopint allows, among other things, to get the state of any token / AppAgent / address.

Request

Body Params application/json
Request
optional
Any of
Request params for the endpoint /state/storage_map.
Example:
{"block":"blockchain_head","storage":{"module_name":"Nfts","storage_name":"Collection","data":{"key_0":{"$in":[56,17]}}}}
block
Block
optional
ID of the block for which the blockchain state will be provided.
storage
object 
StorageMapFilter
required
Filter by the content of storage map.

Module and storage names

The fields module_name and storage_name allows to get records from a particular storage map
collection of data of blockchain runtime.
For example, the filter below retrieves all records from the storage "Nfts.Item",
which contains the data about all fungible tokens in the system:
{ "module_name": "Nfts", "storage_name": "Item" }
To find out the names of the module and the storage,
please refer to the source code of the blockchain runtime or ask the support service.
Both module name and storage name are case-insensitive.

Content of the records

The field data allows to filter by the content of the records.
The example below provides data about the NFT token - collection ID "1567", item ID "381":
{
    "module_name": "Nfts",
    "storage_name": "Item",
    "data": {
        "key_0": 1567,
        "key_1": 381
    }
}
Keys of storage maps do not have proper names so you can refer them as key_0, key_1, etc.
To refer the value of storage records please use storage_value.
To refer any subfield of the key / value - please use the dot notation.
To find out the keys of storage collections or storucture of the stored data,
please refer to the source code of the blockchain runtime or ask the support service.
The example below provides all NFT items from the collection 1567 that are owned by the provided address:
{
    "module_name": "Nfts",
    "storage_name": "Item",
    "data": {
        "key_0": 1567,
        "storage_value.owner": "ttqxHzRJmmjFBcE7Lb5Xs4GNMq2gFSt28JyvTEqjhqzE9EGP4"
    }
}

Operators

The following operators are supported for creating filters:
Comparison operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.
Logical operators: $and, $not, $nor, $or.
The filter below sets several filter conditions for the collection key.
It fetches NFT tokens from the collection 1567 that have item ID between 30 and 110:
{
    "module_name": "Nfts",
    "storage_name": "Item",
    "data": {
        "key_0": 1567,
        "key_1": { "$gt": 30, "$lt": 110 }
    }
}
The filter below explicitly uses the operator "$or" to set the filter on owner address:
{
    "module_name": "Nfts",
    "storage_name": "Item",
    "data": {
        "key_0": 1567,
        "$or": [
            { "storage_value.owner": "ttqxHzRJmmjFBcE7Lb5Xs4GNMq2gFSt28JyvTEqjhqzE9EGP4" },
            { "storage_value.owner": "ttmkrX4meDh1dZzSLGcx2YqeUvCZHHzJYx8XBhjCjFXZUhQt4" }
        ]
    }
}
The behaviour of the comparison and logical operators are the same as ones in the MongoDB.

Address properties

The fields that contain the address support filtering by address properties.
The example below fetches all NFT tokens from collection "1567" that belong to the given AppAgent:
{
    "module_name": "Nfts",
    "storage_name": "Item",
    "data": {
        "key_0": 1567,
        "storage_value.owner": { "app_agent_id": 1567 }
    }
}
Please find more info for filtering of blockchain addresses in the documentation for FilterBlockchainAddress.
presentation
object 
StateStorageMapPresentation
optional
Configuration of output for the endpoint /state/storage_map.
Example
{
    "block": "blockchain_head",
    "storage": {
        "module_name": "Nfts",
        "storage_name": "Collection",
        "data": {
            "key_0": {
                "$in": [
                    56,
                    17
                ]
            }
        }
    }
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.trait.tech/state/storage_map' \
--header 'Content-Type: application/json' \
--data-raw '{
    "block": "blockchain_head",
    "storage": {
        "module_name": "Nfts",
        "storage_name": "Collection",
        "data": {
            "key_0": {
                "$in": [
                    56,
                    17
                ]
            }
        }
    }
}'

Responses

🟢200OK
application/json
Successful Response
Body
Response schema for the endpoint `/state/storage_map`.
metadata
object (ResponseMetadataPaged) 
required
Metadata for the generated response.
request_context
object (ResponseBlockId) 
required
For the endpoints with historical data: the last block, the data from which is included in the response. For the endpoints with blockchain state data: the block whose state is provided in the response. Request context remains the same for all data pages in the series for the initial request.
blockchain_head
object (ResponseBlockId) 
required
The latest blockchain block currently available.
pagination
object (ResponsePaginationData) 
required
Pagination info for the generated response.
data
array[object (StorageMapRecord) {8}] 
Data
required
List of storage records
module_name
string 
Module Name
required
Name of the module of blockchain business logic.
>= 1 characters<= 50 characters
Match pattern:
^[a-zA-Z0-9_]{1,50}$
storage_name
string 
Storage Name
required
Name of the blockchain state storage.
>= 1 characters<= 50 characters
key_0
Key 0
required
Key #0 assiciated with the storage record
key_1
Key 1
optional
Key #1 assiciated with the storage record
key_2
Key 2
optional
Key #2 assiciated with the storage record
key_3
Key 3
optional
Key #3 assiciated with the storage record
storage_value
Storage Value
required
Value stored in the blockchain storage
raw_storage_key
string 
Raw Storage Key
required
The storage key of a value in the blockchain state. The key is used to store/access a value in the blockchain state.
>= 18 characters
Match pattern:
^0x[0-9abcdefABCDEF]{16,}$
Example
{
    "metadata": {
        "request_context": {
            "block_hash": "0xab8006019066f080402ab43da043127b930ef0ffb3349a333222d67c0f542338",
            "block_index": 29702,
            "block_timestamp": 1727581488000
        },
        "blockchain_head": {
            "block_hash": "0xab8006019066f080402ab43da043127b930ef0ffb3349a333222d67c0f542338",
            "block_index": 29702,
            "block_timestamp": 1727581488000
        },
        "pagination": {
            "current_page": 0,
            "next_page_id": "109924cd-b827-4eb1-8901-1f45d2d753e9"
        }
    },
    "data": [
        {
            "module_name": "Nfts",
            "storage_name": "Collection",
            "key_0": 56,
            "key_1": null,
            "key_2": null,
            "key_3": null,
            "storage_value": {
                "owner": {
                    "address": "ttmE1FmLbQzwxDZ3s4GZviJ6iy6d5JeTVSketvtWhZBoMTrbV",
                    "account_id": "0x0304000001fc39587505d395e59c19b3e6f31f066c03ab26f9b2633f8600a2c7",
                    "address_type": "app_agent",
                    "app_agent_id": 1027,
                    "ta_id": null,
                    "address_name": null
                },
                "owner_deposit": 1011130100000000,
                "items": 10,
                "item_metadatas": 10,
                "item_configs": 10,
                "attributes": 0
            },
            "raw_storage_key": "0xe8d49389c2e23e152fdd6364daadd2cc375c4d25bef51e2f32fee9fc557b18200380353fe0c824bfe4038d9b490d395538000000"
        },
        {
            "module_name": "Nfts",
            "storage_name": "Collection",
            "key_0": 17,
            "key_1": null,
            "key_2": null,
            "key_3": null,
            "storage_value": {
                "owner": {
                    "address": "ttrnYjkipbBQVVvpcx349CsAvbQvF35JrXHosmbAULSZa7Uyv",
                    "account_id": "0xf903000001d19712b1c73aa01de7b7764c220ed3d23403f9ef8052e5d2fcc16e",
                    "address_type": "app_agent",
                    "app_agent_id": 1017,
                    "ta_id": null,
                    "address_name": null
                },
                "owner_deposit": 1011130100000000,
                "items": 10,
                "item_metadatas": 10,
                "item_configs": 10,
                "attributes": 0
            },
            "raw_storage_key": "0xe8d49389c2e23e152fdd6364daadd2cc375c4d25bef51e2f32fee9fc557b1820e37562bb4844e827a9b9fc94ab966edb11000000"
        }
    ]
}
🟠422Parameter Error
Modified at 2024-11-21 18:59:09
Previous
Raw single values of blockchain storage
Next
Balances of tokens
Built with