logo
Powered by Redocly

Engine State API (Beta) (v1.2.4)

Download OpenAPI specification:Download

License: The Radix License, Version 1.0

This API is currently in Beta

This specification may experience breaking changes as part of Babylon Node releases. Such changes will be clearly mentioned in the babylon-node release notes. We advise against using this API for business-critical integrations before the version indicated above becomes stable, which is expected in Q4 of 2024.

This API provides a complete view of the current ledger state, operating at a relatively low level (i.e. returning Entities' data and type information in a generic way, without interpreting specifics of different native or custom components).

It mirrors how the Radix Engine views the ledger state in its "System" layer, and thus can be useful for Scrypto developers, who need to inspect how the Engine models and stores their application's state, or how an interface / authentication scheme of another component looks like.

Extra

Endpoints offering additional information based on data sources outside of the Radix Engine's runtime storage.

Search Entities

Lists addresses of all entities meeting the requested search criteria, in an iterator-like paged fashion.

Request
Request Body schema: application/json
required
object (EntitySearchFilter)
max_page_size
integer <int32> (MaxPageSize) [ 1 .. 100 ]

A maximum number of items to be included in the paged listing response.

continuation_token
string (ContinuationToken)

An opaque string conveying the information on where the next page of results starts. It is returned in every paged listing response (except for the last page), and it can be passed in every paged listing request (in order to begin listing from where the previous response ended).

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

A page of entity addresses.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/extra/entity-search
Request samples
application/json
{
  • "filter": {
    },
  • "max_page_size": 1,
  • "continuation_token": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "page": [
    ],
  • "continuation_token": "string"
}

Entities

Endpoints dealing with all Entities.

Get Entity Info

Resolves basic information about an entity: its type, attached modules, fields/collections and blueprint.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Meta-information about the requested entity's state.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/entity/info
Request samples
application/json
{
  • "entity_address": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "info": {
    }
}

Objects

Endpoints dealing with Objects.

Get Object Field

Reads the current value of an object's field, given an entity address, a module (Main by default) and either a field index or its human-readable name (if applicable).

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

attached_module_id
string (AttachedModuleId)

Attached Module ID; should only be specified when reading a field of some attached module. Should be skipped to read the Object's own field.

Enum: "Metadata" "Royalty" "RoleAssignment"
field_name
string

Name of the field to read. Either this or field_index is required. Note: getting a field by name is only a convenience feature, meant for manual, ad-hoc requests (i.e. allowing a human to use the human-readable DerivedName when available). In general, a field's primary identifier is its index, and any production-grade integration should use it.

field_index
integer <int32> [ 0 .. 255 ]

Index of the field to read. Either this or field_name is required.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current object field value

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/field
Request samples
application/json
{
  • "entity_address": "string",
  • "attached_module_id": "Metadata",
  • "field_name": "string",
  • "field_index": 255,
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "content": {
    }
}

List Object Collection

Lists keys of all entries from a particular object's collection, in an iterator-like paged fashion

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

attached_module_id
string (AttachedModuleId)

Attached Module ID; should only be specified when reading a collection of some attached module. Should be skipped to read the Object's own collection.

Enum: "Metadata" "Royalty" "RoleAssignment"
collection_name
string

Name of the collection to read. Either this or collection_index is required. Note: getting a collection by name is only a convenience feature, meant for manual, ad-hoc requests (i.e. allowing a human to use the human-readable DerivedName when available). In general, a collection's primary identifier is its index, and any production-grade integration should use it.

collection_index
integer <int32> [ 0 .. 255 ]

Index of the collection to read. Either this or collection_name is required.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

max_page_size
integer <int32> (MaxPageSize) [ 1 .. 100 ]

A maximum number of items to be included in the paged listing response.

continuation_token
string (ContinuationToken)

An opaque string conveying the information on where the next page of results starts. It is returned in every paged listing response (except for the last page), and it can be passed in every paged listing request (in order to begin listing from where the previous response ended).

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

A page of entry keys.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/collection/iterator
Request samples
application/json
{
  • "entity_address": "string",
  • "attached_module_id": "Metadata",
  • "collection_name": "string",
  • "collection_index": 255,
  • "sbor_format_options": {
    },
  • "max_page_size": 1,
  • "continuation_token": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "page": [
    ],
  • "continuation_token": "string"
}

Get Object Collection Entry

Reads the current value of a specific entry from an Object's Collection.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

attached_module_id
string (AttachedModuleId)

Attached Module ID; should only be specified when reading a collection of some attached module. Should be skipped to read the Object's own collection.

Enum: "Metadata" "Royalty" "RoleAssignment"
collection_name
string

Name of the collection to read. Either this or collection_index is required. Note: getting a collection by name is only a convenience feature, meant for manual, ad-hoc requests (i.e. allowing a human to use the human-readable DerivedName when available). In general, a collection's primary identifier is its index, and any production-grade integration should use it.

collection_index
integer <int32> [ 0 .. 255 ]

Index of the collection to read. Either this or collection_name is required.

required
object (CollectionEntryKey)

The key to look up the entry by. Exactly one of the available SBOR formats must be present on the SborData within the requested key.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current value of the entry

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/collection/entry
Request samples
application/json
{
  • "entity_address": "string",
  • "attached_module_id": "Metadata",
  • "collection_name": "string",
  • "collection_index": 255,
  • "key": {
    },
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "content": {
    }
}

Attached Modules

Endpoints dealing with Attached Modules of Objects.

List Object Metadata

Lists keys of all metadata entries defined for a particular Object, in an iterator-like paged fashion

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

max_page_size
integer <int32> (MaxPageSize) [ 1 .. 100 ]

A maximum number of items to be included in the paged listing response.

continuation_token
string (ContinuationToken)

An opaque string conveying the information on where the next page of results starts. It is returned in every paged listing response (except for the last page), and it can be passed in every paged listing request (in order to begin listing from where the previous response ended).

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

A page of metadata keys.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/attached-modules/metadata/iterator
Request samples
application/json
{
  • "entity_address": "string",
  • "max_page_size": 1,
  • "continuation_token": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "page": [
    ],
  • "continuation_token": "string"
}

Get Metadata Entry

Reads the current value of a specific Object's metadata by key.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

key
required
string

The metadata key (i.e. always a string) to look up the entry by.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current value of the entry

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/attached-modules/metadata/entry
Request samples
application/json
{
  • "entity_address": "string",
  • "key": "string",
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "content": {
    }
}

Get Role Assignment

Reads the current assignment of particular Object's Access Rules to Roles defined by the Blueprint.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current assignment

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/attached-modules/role-assignment
Request samples
application/json
{
  • "entity_address": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "owner": {
    },
  • "main_module_roles": [
    ],
  • "attached_modules": [
    ]
}

Get Royalty Configuration

Reads the currently configured Package and Component Royalty amounts of particular Object's methods.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current assignment

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/object/attached-modules/royalty
Request samples
application/json
{
  • "entity_address": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "method_royalties": [
    ]
}

Key-Value Stores

Endpoints dealing with Key-Value Stores.

List Key-Value Store

Lists keys of all entries from a particular Key-Value Store, in an iterator-like paged fashion

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

max_page_size
integer <int32> (MaxPageSize) [ 1 .. 100 ]

A maximum number of items to be included in the paged listing response.

continuation_token
string (ContinuationToken)

An opaque string conveying the information on where the next page of results starts. It is returned in every paged listing response (except for the last page), and it can be passed in every paged listing request (in order to begin listing from where the previous response ended).

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

A page of map keys.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/kv-store/iterator
Request samples
application/json
{
  • "entity_address": "string",
  • "sbor_format_options": {
    },
  • "max_page_size": 1,
  • "continuation_token": "string",
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "page": [
    ],
  • "continuation_token": "string"
}

Get Key-Value Store Entry

Reads the current value of a specific entry from a Key-Value Store.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

required
object (SborData)

The key to look up the entry by. Exactly one of the available SBOR formats must be used.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Current value of the entry

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/kv-store/entry
Request samples
application/json
{
  • "entity_address": "string",
  • "key": {
    },
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "content": {
    }
}

Blueprints / Schemas

Endpoints dealing with Blueprints and Schemas.

Get Blueprint Info

Returns all externally-relevant information about a particular blueprint.

Request
Request Body schema: application/json
required
package_address
required
string (PackageAddress)

A Bech32m-encoded, human readable rendering of a Package address.

blueprint_name
required
string
blueprint_version
string

A string of format Major.Minor.Patch (all parts being u32). Defaults to 1.0.0.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Information about the requested blueprint.

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/blueprint/info
Request samples
application/json
{
  • "package_address": "string",
  • "blueprint_name": "string",
  • "blueprint_version": "string",
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "info": {
    }
}

Get Schema

Reads the contents of a specific schema associated with an entity.

Request
Request Body schema: application/json
required
entity_address
required
string (EntityAddress)

A Bech32m-encoded, human readable rendering of an arbitrary Entity's address.

schema_hash
required
string (SchemaHash) = 64 characters

A hex-encoded Schema hash, capturing the identity of an SBOR schema.

object (SborFormatOptions)

Requested SBOR representation to use for every SborData within the response.

object (LedgerStateSelector)

An optional specification of a historical ledger state at which to execute the request. The "historical state" feature (see the db.historical_substate_values.enable flag) must be enabled on the Node, and the requested point in history must be recent enough (in accordance with the Node's configured state_hash_tree.state_version_history_length).

Responses
200

Schema contents

400

Client error

409

Request conflicting with the Node's configuration

500

Server error

post/entity/schema/entry
Request samples
application/json
{
  • "entity_address": "string",
  • "schema_hash": "stringstringstringstringstringstringstringstringstringstringstri",
  • "sbor_format_options": {
    },
  • "at_ledger_state": {
    }
}
Response samples
application/json
{
  • "at_ledger_state": {
    },
  • "content": {
    }
}