Raw collections of blockchain storage

Request

Body Params application/json

Request

optional

Any of

StateStorageMapRequest

NextPageRequest

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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

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