Please see the latest release notes.

All responses may have additional fields added at any release, so clients are advised to use JSON parsers which ignore unknown fields on JSON objects.

When the Radix protocol is updated, new functionality may be added, and so discriminated unions returned by the API may need to be updated to have new variants added, corresponding to the updated data. Clients may need to update in advance to be able to handle these new variants when a protocol update comes out.

On the very rare occasions we need to make breaking changes to the API, these will be warned in advance with deprecation notices on previous versions. These deprecation notices will include a safe migration path. Deprecation notes or breaking changes will be flagged clearly in release notes for new versions of the Gateway.

The Gateway DB schema is not subject to any compatibility guarantees, and may be changed at any release. DB changes will be flagged in the release notes so clients doing custom DB integrations can prepare.

The Gateway API is split into 5 sub APIs:

• Status (/status/*) - For status and configuration details for the Gateway / Network.
• Transaction (/transaction/*) - For transaction construction, preview, submission, and monitoring the status of an individual transaction.
• Stream (/transaction/*) - For reading committed transactions.
• State (/state/*) - For reading the current or past ledger state of the network.
• Statistics (/statistics/*) - For calculating particular statistics against the current or past ledger state of the network.
• Extensions (/Extensions/*) - For endpoints that do not fit into other categories, for example, they may not support historic state.

Interacting with this API effectively may require knowledge about the Radix Babylon Transaction Model and the State Model.

We share some very high-level details below, but please see the official documentation for more details on this.

User transactions are formed of a core "intent", which is then signed by 0+ signatories, before being notarized. The output is called a notarized payload. It is this notarized transaction payload which is submitted to the network.

For most users, this construction process will generally happen in their Radix Wallet. If you wish to construct transactions programmatically or offline, you will need to integrate the Radix Engine Toolkit into your application for construction and finalization.

Once submitted, a transaction payload can end up being either rejected or committed. Transactions get rejected if they fail to pass certain criteria at the given time. A transaction payload can be marked as a:

• Permanent Rejection if it is never possible for it to be committed (eg it's statically invalid, or only valid up until epoch 100 and it's now epoch 101)
• Temporary Rejection if it still may be possible that the transaction payload could be committed

A given intent typically is only part of one submitted notarized payload, but it's possible for a notary to notarize and submit multiple payloads for the same intent. The Radix Engine ensures that any intent can only be committed once.

A committed transaction is either committed with an outcome of "Success" or "Failure":

• Committed Failure will result in fees being paid up until the failure point, but all other changes will be discarded.
• Committed Success will result in all changes being committed.

Only committed transactions appear on ledger.

The gateway will attempt to submit your transaction to nodes on the network. If it gets temporarily rejected, the error message will be recorded against the transaction, but the Gateway will retry submission for a limited time. During this time, the status will be reported as pending.

The Radix Engine consists of "global entities". A global entity has a Bech32m Address, with a human-readable-prefix (and prefix byte) matching the entity type.

As an example, entities include concepts like Components, Packages, Vaults, Resource Managers and Key-Value Stores.

Each entity owns substates which store data, and these substates can own other entities. For example, an Account Component has a struct substate which owns a Key-Value Store. This Key-Value store has an entry for each resoure the Account owns, and each Key-Value Store Entry owns a corresponding Vault.

For each global entity, the Gateway aggregates its owned resources by looking at the contents of Vaults in the subtree of entities under that global entity.

The API is designed in a JSON-RPC-like style, using HTTP as a transport layer, which means that:

• Requests always use the HTTP POST method.
• There is no HTTP cache involved.
• Client-originated errors result in HTTP 4xx error responses.
• Server-originated errors result in HTTP 5xx error responses:
  • The error object contains an HTTP-like code
  • The error object also contains a structured/typed properties, with a type discriminator, allowing for structured error interpretation in client software.

Many collections have dynamic length, so these are exposed through a pagination model. The Gateway API uses cursor-based pagination model where the existence of the cursor indicates that next chunk (page) of the underlying collection is available, and can be used in a subsequent request to query for it.

collection {
  int64? total_count,
  string? next_cursor,
  T[] items
}

• total_count (optional) if present indicates the overall size of the underlying collection,
• next_cursor (optional) if present indicates that the next chunk (page) exists and can be fetched using collection-specific endpoint and cursor value,
• items a chunk (page) of underlying collection items.

To provide consistent reads when querying for the next pages, it's required to provide the at_ledger_state parameter. It will enforce that data returned for all pages is generated using the same ledger state.

Each response from a state endpoint returns data from a single "snapshot" of the ledger. By default, the latest available ledger version is used. All state responses include a ledger_state property in their root object, which captures which ledger version was used by the gateway to generate the response.

Because the state of entities constantly changes, the ledger_state object makes it clear which state was used to generate the response. The ledger_state object includes the state_version (ie the unique ID of that state version, which can also be used to uniquely identify the last transaction which brought the ledger to that state version), the timestamp (which may be shared by neighbouring transactions, but does not decrease) and the epoch and round in that epoch when the transaction was committed (again, the pair (epoch, round) may be shared by neighbouring transactions).

All endpoints with an at_ledger_state parameter allow you to request a particular snapshot is used for generating the response. In this way, you can browse historical state at a given point in time.

You can specify one of:

• state_version
• timestamp - which will query against the nearest state version before that timestamp
• epoch - which will query against the result of the first transaction in that epoch
• A pair of epoch and round - which will query against the result of the first transaction in that epoch and round

For example, the following request will return the current state (at the current tip of the ledger) for the entity with address: resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd (ie XRD).

/state/entity/details

{
  "addresses": [
    "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
  ]
}

Whereas the following request will return the state of XRD as it was at state version 1000, near the start of the Babylon ledger:

/state/entity/details

{
  "addresses": [
    "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
  ],
  "at_ledger_state": {
    "state_version": 1000
  }
}

As described in Browsing historical data it is possible to specify the exact ledger state by providing the at_ledger_state parameter.

It can be used to browse historical data but it also allows consistent reads when making multiple requests (either when paginating or when collecting data from multiple endpoints).

Imagine a situation when your key value store contains 128 keys. To fetch all the keys and it is data you would need to make at least 4 requests (2 to paginate through all keys and 2 to fetch all the data). Using the same at_ledger_state parameter value it is guaranteed that you are fetching all the data from exactly the same ledger state.

Example requests:

First page of keys:

/state/key-value-store/keys

{
  "key_value_store_address": "internal_keyvaluestore_rdx1kprq4hx5892fuezay6tyajyu0gr2jeu8j7alauxen46xu8ufzvecph"
}

Response:

{
  "ledger_state": {
    "network": "mainnet",
    "state_version": 50576725,
    "proposer_round_timestamp": "2024-02-20T16:46:22.343Z",
    "epoch": 74324,
    "round": 84
  },
  "total_count": 128,
  "next_cursor": "eyJvIjoxMDB9",
  "items": [...]
}

Second page of keys:

/state/key-value-store/keys

{
  "key_value_store_address": "internal_keyvaluestore_rdx1kprq4hx5892fuezay6tyajyu0gr2jeu8j7alauxen46xu8ufzvecph",
  "cursor": "eyJvIjoxMDB9",
  "at_ledger_state": {
    "state_version": 50576725
  }
}

Response:

{
  "ledger_state": {
    "network": "mainnet",
    "state_version": 50576725,
    "proposer_round_timestamp": "2024-02-20T16:46:22.343Z",
    "epoch": 74324,
    "round": 84
  },
  "total_count": 128,
  "items": []
}

Get data for one of the keys:

/state/key-value-store/data

{
  "key_value_store_address": "internal_keyvaluestore_rdx1kprq4hx5892fuezay6tyajyu0gr2jeu8j7alauxen46xu8ufzvecph",
  "keys": [
    {
      "key_hex": "5c80c0c72cd2cbca7263e84e9ec83a6c9cee2121d466bf3cc8640d4d06909af6"
    }
  ],
  "at_ledger_state": {
    "state_version": 50576725
  }
}

Response:

{
  "ledger_state": {
    "network": "mainnet",
    "state_version": 50577454,
    "proposer_round_timestamp": "2024-02-20T16:49:22.861Z",
    "epoch": 74324,
    "round": 795
  },
  "key_value_store_address": "internal_keyvaluestore_rdx1kprq4hx5892fuezay6tyajyu0gr2jeu8j7alauxen46xu8ufzvecph",
  "entries": [
    {
      "key": {
          ...
        }
      },
      "value": {
        ...
      },
      "last_updated_at_state_version": 1351581,
      "is_locked": false
    }
  ]
}

All the above requests were executed against exactly the same ledger snapshot (state version 50577454).

To reduce bandwith and wasted work, some properties in certain endpoints are optional.

Most opt-ins default to false if not provided, and you can ask for the supplementary data by explicitly setting the corresponding opt-in property to true.

Some opt-ins for backwards-compatibility default to true. In these cases, explicitly providing a value of false will opt out of the data and save bandwidth.

Endpoints that currently support opt-ins include the following. Check out the request schemas under the endpoints themselves for more detail on how to request opt-ins:

/transaction/committed-details
/stream/transactions
/state/entity/details
/state/entity/page/fungibles/
/state/entity/page/non-fungibles/
/state/entity/page/non-fungible-vaults/

For example, the following request will return a simple, short response with opt-ins disabled:

/transaction/committed-details

{
  "intent_hash": "txid_rdx1t44y7lrqtrmn0pq4gxgsmn035lh5glws273h0lsff37jnzj2ylls3aeumn"
}

// Response
{
  "ledger_state": {
    "network": "mainnet",
    "state_version": 5151578,
    "proposer_round_timestamp": "2023-10-11T07:21:03.167Z",
    "epoch": 36452,
    "round": 1060
  },
  "transaction": {
    "transaction_status": "CommittedSuccess",
    "state_version": 5150877,
    "epoch": 36452,
    "round": 362,
    "round_timestamp": "2023-10-11T07:18:30.417Z",
    "payload_hash": "notarizedtransaction_rdx1hjlstgpadgpyeulp5yahrcz56ymkmsukmrjv42nwzvygfl9nyfhsxccm42",
    "intent_hash": "txid_rdx1t44y7lrqtrmn0pq4gxgsmn035lh5glws273h0lsff37jnzj2ylls3aeumn",
    "fee_paid": "0.25417642453",
    "confirmed_at": "2023-10-11T07:18:30.417Z",
    "receipt": {
      "status": "CommittedSuccess",
      "output": [
        {
          "hex": "5c2100",
          "programmatic_json": null
        },
        {
          "hex": "5c90f8ef824eb480c16bbceebcc36d0e263b9ebf287cdcab710332344104f11c",
          "programmatic_json": null
        },
        {
          "hex": "5c2100",
          "programmatic_json": null
        },
        {
          "hex": "5c2100",
          "programmatic_json": null
        }
      ]
    }
  }
}

Or, if we're interested in the raw transaction payload, we can enable it in the response by requesting the "raw_hex" opt-in, which will result in the raw_hex property being returned:

/transaction/committed-details
{
  "intent_hash": "txid_rdx1t44y7lrqtrmn0pq4gxgsmn035lh5glws273h0lsff37jnzj2ylls3aeumn",
  "opt_ins": {
    "raw_hex": true
  }
}

// Response
{
  "ledger_state": {
    "network": "mainnet",
    "state_version": 5152002,
    "proposer_round_timestamp": "2023-10-11T07:22:45.886Z",
    "epoch": 36453,
    "round": 152
  },
  "transaction": {
    "transaction_status": "CommittedSuccess",
    "state_version": 5150877,
    "epoch": 36452,
    "round": 362,
    "round_timestamp": "2023-10-11T07:18:30.417Z",
    "payload_hash": "notarizedtransaction_rdx1hjlstgpadgpyeulp5yahrcz56ymkmsukmrjv42nwzvygfl9nyfhsxccm42",
    "intent_hash": "txid_rdx1t44y7lrqtrmn0pq4gxgsmn035lh5glws273h0lsff37jnzj2ylls3aeumn",
    "fee_paid": "0.25417642453",
    "confirmed_at": "2023-10-11T07:18:30.417Z",
    "raw_hex": "4d22030221022104210707010a648e0000000000000a6e8e000000000000090b86dca62201012007208df9fdf4b8325fffdf300b0c68492ebc0fbe9f17c7fc811c68e6cb16a6eaf5f9010008000020220441038000d1f20f6eaff22df7090ddc21cf738ba70cd700c6e6854ea349ebec4530e80c086c6f636b5f666565210185e08f4fb23e2e21050000000000000000000000000000000041038000d1f20f6eaff22df7090ddc21cf738ba70cd700c6e6854ea349ebec4530e80c087769746864726177210280005da66318c6318c61f5a61b4c6318c6318cf794aa8d295f14e6318c6318c68500003468c609860bac140000000000000000000000000000000280005da66318c6318c61f5a61b4c6318c6318cf794aa8d295f14e6318c6318c68500003468c609860bac14000000000000000000000000000041038000d1f742847eb59027497d466b7404f6b6e3c3f0458c5a7da3eb54858c49ed0c147472795f6465706f7369745f6f725f61626f72742102810000000022000020200022000020220100012101200741017c16c54cf8ba3e3d3487172424b40502404812a7a9ceeda5aa544baa1c2d0f0c1e6cfbb3dd6af5b6aa047231d918e5288e1139d397064326ac4f63283da6686f2201012101200740e82f9e9a002a64cb3dbb2154e7912ef25720c92e0b86a7b0d090ff4c9d9992ef435b5c6d08e577f50423f8a9b831b3fbb9faecf16399a386b8412d2a53f3450f",
    "receipt": {
      "status": "CommittedSuccess",
      "output": [
        {
          "hex": "5c2100",
          "programmatic_json": null
        },
        {
          "hex": "5c90f8ef824eb480c16bbceebcc36d0e263b9ebf287cdcab710332344104f11c",
          "programmatic_json": null
        },
        {
          "hex": "5c2100",
          "programmatic_json": null
        },
        {
          "hex": "5c2100",
          "programmatic_json": null
        }
      ]
    }
  }
}

The Gateway API has different entry points which can be used to fetch entity data.

The /state/entity/details is the main endpoint - it takes a list of entity addresses, and returns various details for those entities, which differs per entity type. A detailed specification of the response model for each entity is given in the response schema for the endpoint later in this doc. The endpoint also also supports a number of opt-ins detailed below. Many of these opt-ins return a "first page" of related data for each entity. Further pages can be requested from the /page/ endpoints.

The entity details endpoint is supplemented by various paged endpoints, which return collections:

• /state/entity/page/metadata → returns entity metadata, and can be used as entry point for further pagination with the cursor returned from /state/entity/details

• /state/entity/page/schemas → returns entity schemas, and can be used as an entry point for further pagination from a cursor returned from /state/entity/details

• /state/entity/page/fungibles/ → can be used as an entry point to fetch fungible resources under a given global entity or for further pagination with the cursor returned from /state/entity/details

• /state/entity/page/fungible-vaults/ → can be used as an entry point to fetch fungible vaults of a given resource under a given global entity or for further pagination with a cursor returned from /state/entity/details

• /state/entity/page/non-fungibles/ → can be used as an entry point to fetch non-fungible resources under a given global entity or for further pagination with a cursor returned from /state/entity/details

• /state/entity/page/non-fungible-vaults/ → can be used as an entry point to fetch non-fungible vaults of a given resource under a given global entity or for further pagination with a cursor returned from /state/entity/details

• /state/entity/page/non-fungible-vault/ids → can be used as an entry point to fetch non fungible-ids in a given vault or for further pagination from a cursor returned from /state/entity/details

• /state/package/page/blueprints → can be used as an entry point to fetch blueprints of a given package entity or for further pagination with a cursor returned from /state/entity/details

• /state/package/page/codes → can be used as an entry point to fetch codes of a given package entity or for further pagination with a cursor returned from /state/entity/details

Metadata

/state/entity/details endpoint returns only the first page of metadata. If the queried entity contains more than one page of metadata items, a next_cursor will be returned, which can be used as cursor in the /state/entity/page/metadata endpoint to fetch further pages.

You can also explicitly specify a list of metadata keys which you wish to be included on any returned objects. You can do that by filling the explicit_metadata opt-in with the metadata keys you wish to load.

For example, the following request will return the regular metadata property in the response, but will also contain an explicit_metadata section containing name and description for each returned entity (if they are defined for that entity).

/state/entity/details

{
  "addresses": [
    "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
  ],
  "opt_ins": {
    "explicit_metadata": [
      "name",
      "description"
    ]
  }
}

// Response
// ...
"explicit_metadata": {
  "total_count": 2,
  "items": [
    {
      "key": "name",
      "value": {
        "raw_hex": "5c2200010c055261646978",
        "programmatic_json": {
          "kind": "Enum",
          "variant_id": "0",
          "fields": [
            {
              "kind": "String",
              "value": "Radix"
            }
          ]
        },
        "typed": {
          "value": "Radix",
          "type": "String"
        }
      },
      "is_locked": true,
      "last_updated_at_state_version": 2
    },
    {
      "key": "description",
      "value": {
        "raw_hex": "5c2200010c9e01546865205261646978205075626c6963204e6574776f726b2773206e617469766520746f6b656e2c207573656420746f2070617920746865206e6574776f726b2773207265717569726564207472616e73616374696f6e206665657320616e6420746f2073656375726520746865206e6574776f726b207468726f756768207374616b696e6720746f206974732076616c696461746f72206e6f6465732e",
        "programmatic_json": {
          "kind": "Enum",
          "variant_id": "0",
          "fields": [
            {
              "kind": "String",
              "value": "The Radix Public Network's native token, used to pay the network's required transaction fees and to secure the network through staking to its validator nodes."
            }
          ]
        },
        "typed": {
          "value": "The Radix Public Network's native token, used to pay the network's required transaction fees and to secure the network through staking to its validator nodes.",
          "type": "String"
        }
      },
      "is_locked": true,
      "last_updated_at_state_version": 2
    }
  ]
},
// ...

Resource aggregation

Both fungible and non-fungible resources can be aggregated globally or per vault. This is controlled by the aggregation_level request field.

• Global - If the entity contains multiple vaults of the same resource, or nested components which contains vaults of the same resource, the total balance across all these vaults will be returned. This mode is useful for TVL style calculations.

• Vault - Each vault is returned separately. This mode is useful for non-fungibles, because you get the vault ids which you can use to paginated ids from a vault.

Fungible resources opt-in

This opt-in returns only the first page of fungible resources under the entity. If the queried entity contains more resources, a next_cursor will be returned, which can be used with the /state/entity/page/fungibles/ endpoint for requesting further pages.

If you requested vault aggregation, only the first page of vaults are returned for each resource. If a next_cursor is returned, further vaults for that resource can be fetched using that cursor with the /state/entity/page/fungible-vaults/ endpoint.

Non-fungible resources opt-in

This opt-in returns only the first page of non-fungible resources under the entity. If the queried entity contains more resources, a next_cursor will be returned, which can be used with the /state/entity/page/non-fungibles/ endpoint for requesting further pages.

If you requested vault aggregation, only the first page of vaults are returned for each resource . If a next_cursor is returned, further vaults for that resource can be fetched using that cursor with the /state/entity/page/non-fungible-vaults/ endpoint.

If the non_fungible_include_nfids opt-in is set to true AND vault aggregation was requested, the response will also contain the first page of non-fungible ids in each returned vault. If the vault contains more than one page of ids, a next_cursor is returned, which can be used with the /state/entity/page/non-fungible-vault/ids endpoint to load further non-fungible ids in the vault.

The transaction stream endpoint can be used to read a filtered stream of transaction results.

State version

You can narrow the range of transactions by specifying ledger state boundaries with the at_ledger_state and from_ledger_state filters.

at_ledger_state lets you specify at which state version you want to query. It's same for almost all endpoints where you can basically travel in time on ledger. Let's say it's currently state version 347 062 but for any reason you'd like to check how ledger looked like at state version 100 If not specified it'll always query against current tip of the ledger.

For example, the following request will return the transaction stream as it was for state version 100 (by default all user transactions before state version 100, from latest to oldest)

/stream/transactions
{
  "at_ledger_state": {"state_version": 100 }
}

By contrast, from_ledger_state lets you specify a lower boundary of state versions. This can be used to "page forward" through the transaction stream (although by default only user transactions will be returned, and they will be in descending order):

/stream/transactions

{
  "from_ledger_state": {"state_version": 50 },
}

You can combine these two, for example the following request will return all user transactions with state version s between 100 and 300 inclusive (in desceding order).

/stream/transactions

{
  "from_ledger_state": {"state_version": 100 },
  "at_ledger_state": {"state_version": 300 }
}

Supported filters

The transaction stream endpoint allows additional filters. A transaction has to satisfy all filters in order to be returned.

The currently supported filters are:

• kind_filter - One of User, EpochChange, All. You can use that filter to query for certain kinds of transactions. Defaults to User.

• manifest_accounts_withdrawn_from_filter - Allows specifying an array of account addresses. If specified, the response will contain only transactions with a manifest containing withdrawals from the given accounts.

• manifest_accounts_deposited_into_filter - Similar to withdrawn, but will return only transactions with a manifest containing deposits to the given accounts.

• manifest_resources_filter - Allows specifying array of resource addresses. If specified, the response will contain only transactions containing the given resources in the manifest (regardless of their usage).

• manifest_badges_presented_filter - Allows specifying array of badge resource addresses. If specified, the response will contain only transactions where the given badges were presented.

• accounts_with_manifest_owner_method_calls - Allows specifying an array of account addresses. If specified, the response will contain only transactions that, for all specified accounts, contain manifest method calls to that account which require the owner role. See the account docs for more information.

• accounts_without_manifest_owner_method_calls - Allows specifying an array of account addresses. If specified, the response will contain only transactions that, for all specified accounts, do NOT contain manifest method calls to that account which require owner role. See the account docs for more information.

• manifest_class_filter - Allows filtering to transactions which match the given manifest classification. If specified, the response will contain only transactions which have a class that matches the filter. If match_only_most_specific set to true, only transactions where the queried class is most specific will be returned. See the docs on manifest classification for more information.

• affected_global_entities_filter - Allows specifying an array of global addresses. If specified, the response will contain transactions that affected all of the given global entities. A global entity is marked as "affected" by a transaction if any of its state (or its descendents' state) was modified as a result of the transaction. For performance reasons consensus manager and transaction tracker are excluded from that filter.

• event_global_emitters_filter - Allows specifying an array of global addresses. If specified, the response will contain transactions in which all entities emitted events. If an event was published by an internal entity, it is going to be indexed as it is a global ancestor. For performance reasons events published by consensus manager and native XRD resource are excluded from that filter.

• events_filter - Filters the transaction stream to transactions which emitted at least one event matching each filter (each filter can be satisfied by a different event). Currently only deposit and withdrawal events emitted by an internal vault entity are tracked. For the purpose of filtering, the emitter address is replaced by the global ancestor of the emitter, for example, the top-level account / component which contains the vault which emitted the event.

Each filter is a complex object where you can specify:

• event (required) - the event tag. Currently only the following tags are supported:
  • {"event": "Withdrawal"} - Filters to "Withdraw" events from fungible and non-fungible vaults
  • {"event": "Deposit"} - Filters to "Deposit" events from fungible and non-fungible vaults
• emitter_address (optional) - The "global emitter". Adding a global address here filters to matching events which have an emitter entity which is a descendent of the given global address, e.g. using {"emitter_address" : "account_rdx16y76fepuvxqpv6gp6qswqymwhj5ng6sduugj4z6yysccvdg95g0dtr" } filters to events emitted by vaults inside that account.
• resource_address (optional) - Adding a resource address here filters to matching events which concern the given resource, e.g. {"resource_address" : "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"} matches only events which involve XRD.

As an example, the following query selects all transactions where the first account withdrew XRD and the second account deposited XRD:

{
  "events_filter": [
    {
      "event": "Withdrawal",
      "emitter_address": "account_rdx16y76fepuvxqpv6gp6qswqymwhj5ng6sduugj4z6yysccvdg95g0dtr",
      "resource_address": "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
    },
    {
      "event": "Deposit",
      "emitter_address": "account_rdx12x5vk07qcez6xj0zt8ve0x2g20mrssk0vrest3vf0qljd76r6zfvsx",
      "resource_address": "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
    }
  ]
}

Request Validation

The overall number of the applied filters can be limited. In a case of collection-based filters every item counts as a separate filter. By default up to 10 filters can be specified. The sample query below uses 5 filters in total: 1 kind_filter, 3 manifest_resources_filters and 1 events_filter.

{
  "kind_filter": "All",
  "manifest_resources_filter": [
    "resource_rdx1t5l4s99hpc6vvskktu2uy9egk86tszjnnez62zfu9t7z7tsqqtvpvp",
    "resource_rdx1t4w8ds79tkdjpq26z9v4w0tnv78jaxmy5vvrumdh3qeqzwqkgj6lvs",
    "resource_rdx1t5ha0254q4j5t0rxnev9f9vdt8jx6ud6caavrhcvvehg28ny90ku3x",
  ],
  "events_filter": [
    {
      "event": "Deposit",
      "emitter_address": "account_rdx12x5vk07qcez6xj0zt8ve0x2g20mrssk0vrest3vf0qljd76r6zfvsx",
      "resource_address": "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
    }
  ]
}

Pagination

If the limit_per_page request hint parameter is lower than the overall number of transactions to be returned or the internal limiter kick in, a next_cursor will be returned. It can be used in subsequent requests as the cursor parameter to fetch further pages.

For example, the following request will return a cursor:

/stream/transactions

{
  "kind_filter": "All",
  "from_ledger_state": { "state_version": 100 },
  "at_ledger_state": { "state_version": 300 },
  "limit_per_page": 1
}

// Returns
{
  // ...
  "next_cursor": "eyJ2IjoyOTl9",
  // ...
}

Which can be used in the next query to fetch further pages:

/stream/transactions

{
  "kind_filter": "All",
  "from_ledger_state": { "state_version": 100 },
  "at_ledger_state": { "state_version": 300 },
  "limit_per_page": 1,
  "cursor": "eyJ2IjoyOTl9"
}

Ordering

By default, transactions are returned in descending order (highest state version / most recent first).

You can change this to ascending order by setting the order parameter to Asc

/stream/transactions

{
  // ...
  "order": "Asc"
  // ...
}

Keep in mind that if order is ascending you'll start fetching transactions from the oldest first and with each page you'll fetch newer transactions.

Reading events to find out what happened in a given dApp

Currently the gateway supports filtering by withdrawal and deposit events only. We wish to support other filters in future.

For the time being, if your dApp component always updates state along with emitting events, you can use the affected filter to filter to all transactions which affected your component, and extract relevant events from those transactions.

For example, to find all transactions which affected component_rdx1cq4ugccz6pg89w83ujanqlycw566kd9c9vxxuc9r45p7vues2649t4, (and therefore all events which it emitted), you can use the following request:

/stream/transactions

{
  "kind_filter": "All",
  "affected_global_entities_filter": ["component_rdx1cq4ugccz6pg89w83ujanqlycw566kd9c9vxxuc9r45p7vues2649t4"],
  "opt_ins": { "receipt_events": true }
}

This will return the first page of all transactions, including their emitted events (which was enabled by using the receipt_events opt-in). These emitted events can be filtered by the client to just events which were emitted by the given component (component_rdx1cq4ugccz6pg89w83ujanqlycw566kd9c9vxxuc9r45p7vues2649t4 in this case).

// Response
{
  "transaction_status": "CommittedSuccess",
  "state_version": 14614370,
  "epoch": 44797,
  "round": 655,
  "round_timestamp": "2023-11-09T13:29:32.27Z",
  "payload_hash": "notarizedtransaction_rdx1dmjjaww667cq388hpx4jv895yj42l7ezynqycdr97ht9s4mkhzssejpcxz",
  "intent_hash": "txid_rdx1l0y5gw45aup7r8ex863s2ahhfwz9vdfv8jktqhcypegcf3vlk6zqhnmj9a",
  "fee_paid": "0.57054833978",
  "confirmed_at": "2023-11-09T13:29:32.27Z",
  "receipt": {
    "status": "CommittedSuccess",
    "events": [
      {
        "name": "LockFeeEvent",
        "emitter": {
          "type": "Method",
          "entity": {
            "is_global": false,
            "entity_type": "InternalFungibleVault",
            "entity_address": "internal_vault_rdx1tzst8p8vvagnyyev8eu209h6fhmdvk334vhx0vhk4em02p89hlaluu"
          },
          "object_module_id": "Main"
        },
        "data": {
          "fields": [
            {
              "value": "0.713902721272999997",
              "kind": "Decimal",
              "field_name": "amount"
            }
          ],
          "kind": "Tuple",
          "type_name": "LockFeeEvent"
        }
      },
      {
        "name": "WithdrawEvent",
        "emitter": {
          "type": "Method",
          "entity": {
            "is_global": false,
            "entity_type": "InternalFungibleVault",
            "entity_address": "internal_vault_rdx1tpl4g48ul8tz8agtll35m7f936f2vuj4f8up9wlcgu6lj566vmashl"
          },
          "object_module_id": "Main"
        },
        "data": {
          "fields": [
            {
              "value": "20",
              "kind": "Decimal",
              "field_name": "amount"
            }
          ],
          "kind": "Tuple",
          "type_name": "WithdrawEvent"
        }
      },
      // ...
    ]
  }
},
// ...

Blueprints define a list of different roles which control access to their features. Global components of a given blueprint provide assignments of access rules to those roles.

You can get the roles and role assignments for a blueprint from the /state/entity/details endpoint.

For example, let's take a look at the XRD resource:

/state/entity/details

{
  "addresses": [
    "resource_rdx1tknxxxxxxxxxradxrdxxxxxxxxx009923554798xxxxxxxxxradxrd"
  ],
}

The response will contain two main parts. The definition of the owner role, and a list of all role assignments for that component:

"role_assignments": {
  "owner": {
    // ...
  },
  "entries": [
    // ...
  ]
}

Each role assignment conceptually includes:

• An assigned rule which defines what are the requirements to access that role.
• Its updater which defines which role is allowed to update the assignment.

The Owner role

The owner role assignment includes the rule which specifies the requirements you have to meet to act as the owner of the entity. In the below example you need to have access to a proof of a certain non-fungible id.

The updater of an owner role assingment is either None or specifies the owner can update itself.

  "owner": {
    "rule": {
      "type": "Protected",
      "access_rule": {
        "type": "ProofRule",
        "proof_rule": {
          "type": "Require",
          "requirement": {
            "type": "NonFungible",
            "non_fungible": {
              "local_id": {
                "id_type": "Integer",
                "sbor_hex": "5cc0010000000000000000",
                "simple_rep": "#0#"
              },
              "resource_address": "resource_rdx1nfxxxxxxxxxxsystxnxxxxxxxxx002683325037xxxxxxxxxsystxn"
            }
          }
        }
      }
    },
    "updater": "None"
  },

Role assignment entries

Each role assignment contains three fields:

• role_key - a composite key consisting of the entity module which defines the role and the name of the role inside the module.
• assignment - the assigned rule. It could be either Explicit as in the below example and contain an inline rule, or Owner which means the owner role is used.
• updater_roles - a fixed list of role_keys which act as updaters for the role, defined on the blueprint. Access to any of these updater roles permits someone to update the assignment for this role.

An example assignment entry is the following. This response indicates that the given resource can be burned by an actor who has access to a proof of a specific global caller badge:

"role_key": {
  "module": "Main",
  "name": "burner"
},
"assignment": {
  "resolution": "Explicit",
  "explicit_rule": {
    "type": "Protected",
    "access_rule": {
      "type": "ProofRule",
      "proof_rule": {
        "type": "Require",
        "requirement": {
          "type": "NonFungible",
          "non_fungible": {
            "local_id": {
              "id_type": "Bytes",
              "sbor_hex": "5cc0022068c44e9d432e71c51e2a2ac285897b372328d8b31374ff29131bc6b25b6bd070",
              "simple_rep": "[68c44e9d432e71c51e2a2ac285897b372328d8b31374ff29131bc6b25b6bd070]"
            },
            "resource_address": "resource_rdx1nfxxxxxxxxxxglcllrxxxxxxxxx002350006550xxxxxxxxxglcllr"
          }
        }
      }
    }
  }
},
"updater_roles": [
  {
    "module": "Main",
    "name": "burner_updater"
  }
]

An example component

Imagine a component which can store resources into named vaults. To support arbitrary names, it might store these vaults in a KeyValueStore<String, Vault> as follows. We will use this blueprint for demonstrating some requests.

use scrypto::prelude::*;

#[blueprint]
mod multi_vault {
    use scrypto::prelude::Vault;

    struct MultiVault {
        token_vaults: KeyValueStore<String, Vault>
    }

    impl MultiVault {
        pub fn instantiate_multivault() -> Global<MultiVault> {
            Self {
                token_vaults: KeyValueStore::new()
            }
            .instantiate()
            .prepare_to_globalize(OwnerRole::None)
            .globalize()
        }

        pub fn deposit_to_vault(&mut self, vault_id: String, deposit: Bucket) {
            let tmp_token_vaults = self.token_vaults.get_mut(&vault_id);
            match tmp_token_vaults {
                Some(mut vault) => vault.put(deposit),
                None => {
                    drop(tmp_token_vaults);
                    self.token_vaults.insert(vault_id, Vault::with_bucket(deposit))
                }
            }
        }
    }
}

Querying for KeyValueStore address

Let's say that after creating a component with the above blueprint, we created 3 vaults "1", "2", "3" and transfered some amount of resource to each of them.

If you'd like to look at the content of the KeyValueStore, you need to first get its address. You can do that by calling /state/entity/details with the instantiated component address:

/state/entity/details

{
  "addresses": [
    "component_tdx_2_1crmcapqnz2sex9u6tppnagps64lgpfmkupmyrwazeg5qe3x2z3trcr"
  ]
}

In the response you'll receive the state of that component which will contain the address of that KeyValueStore:

      // ...
      "details": {
        // ...
        "state": {
          "kind": "Tuple",
          "type_name": "MultiVault",
          "fields": [
            {
              "kind": "Own",
              "type_name": "KeyValueStore",
              "field_name": "token_vaults",
              "value": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk"
            }
          ]
        }
      }

Iterating over all KeyValueStore keys

You can use the /state/key-value-store/keys endpoint to iterate over all the keys in a certain key value store. If the queried key value store contains more than one page of keys, a next_cursor will be returned, which can be used as a cursor in the request to fetch further pages.

i.e:

/state/key-value-store/keys

{
  "key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk"
}

Will respond with a first page of the keys of the current entries of the key value store. This collection is ordered by the entry first appearance on the network, descending. Each item includes the entry's key (in both hex and programmatic_json form) and the state version when it was last updated.

{
  ...
  "total_count": 8,
  "items": [
    {
      "key": {
        "raw_hex": "5c0c0131",
        "programmatic_json": {
          "value": "1",
          "kind": "String"
        }
      },
      "last_updated_at_state_version": 4939670
    },
    ...
  ],
  "key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk"
}

Querying for the content under specific keys

You can either use the keys returned from the /state/key-value-store/keys endpoint or construct keys in json form on your own, if you know the key type of the KeyValueStore.

Querying using hex keys

Simply grab the raw_hex key returned from the /state/key-value-store/keys endpoint and call /state/key-value-store/data with it as a parameter.

i.e:

/state/key-value-store/data

{
  "key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk",
  "keys": [
    {
      "key_hex": "5c0c0131"
    }
  ]
}

Will respond with data held under that key:

{
  ...
  "key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk",
  "entries": [
    {
      "key": {
        "raw_hex": "5c0c0131",
        "programmatic_json": {
          "value": "1",
          "kind": "String"
        }
      },
      "value": {
        "raw_hex": "5c90588c6d59227f64bd7fc68e38bf7c7013cf179a78d5562ce9378b1378e2fa",
        "programmatic_json": {
          "value": "internal_vault_tdx_2_1tzxx6kfz0ajt6l7x3cut7lrsz0830xnc64tze6fh3vfh3ch6587c5d",
          "kind": "Own",
          "type_name": "Vault"
        }
      },
      "last_updated_at_state_version": 4939415,
      "is_locked": false
    }
  ]
}

In our case, we may want to look up information about the vault (for example, the vault's resource address and balance). This can be done with the /state/entity/details endpoint.

Constructing json keys

The json keys are specified as programmatic SBOR JSON (which is a recursive data format, with each layer being a discriminated union with the kind discriminator). Search for SBOR on our docs site for more information on SBOR and the programmatic SBOR JSON format.

In this case, our KeyValueStore keys are strings, so each key is identified as programmatic SBOR JSON with two properties:

"key_json": {
    "kind": "String",
    "value": "{Id}"
}

And we can use that json in /state/key-value-store/data simply replacing {Id} with our vault name, for example, "1":

/state/key-value-store/data

{
"key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk",
  "keys": [
    {
      "key_json": {
          "kind": "String",
          "value": "1"
      }
    }
  ]
}

The API will respond with content which is held under the given key:

// Response
{
  // ...
  "key_value_store_address": "internal_keyvaluestore_tdx_2_1kzjd929eqlzd9n02uuj8jd48705vcrpvhv4mgxnaltrgystnca3qxk",
  "entries": [
    {
      "key": {
        "raw_hex": "5c0c0131",
        "programmatic_json": {
          "value": "1",
          "kind": "String"
        }
      },
      "value": {
        "raw_hex": "5c90588c6d59227f64bd7fc68e38bf7c7013cf179a78d5562ce9378b1378e2fa",
        "programmatic_json": {
          "value": "internal_vault_tdx_2_1tzxx6kfz0ajt6l7x3cut7lrsz0830xnc64tze6fh3vfh3ch6587c5d",
          "kind": "Own",
          "type_name": "Vault"
        }
      },
      // ...
    }
  ]
}

In our case, we may want to look up information about the vault (for example, the vault's resource address and balance). This can be done with the /state/entity/details endpoint.

Query information about the Gateway API status.

Query status of, construct, preview and submit transactions.

Browse through the history of transactions.

Query information snapshot about state of ledger entities at present or past time.