The Gateway API is split into 4 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/*, /entity/* and /non-fungible/*) - For reading the current or past ledger state of the network.

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 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.

Collections can grow in size therefore every dynamic-length collection is a subject to pagination where a generic data struct is used to represent a chunk (page) of underlying data. Gateway API uses cursor-based pagination model where the sole existence of the cursor indicates that next chunk (page) of the underlying collection is available.

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

• total_count (optional) if present specifies 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,
• previous_cursor (optional) if present indicates that the previous chunk (page) exists and can be fetched using collection-specific endpoint and cursor value,
• items a chunk (page) of unerlying collection items.

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.