logo
Powered by Redocly

Babylon Core API (0.2.0)

Download OpenAPI specification:Download

License: The Radix License, Version 1.0

This API is exposed by the Babylon Radix node to give clients access to the Radix Engine, Mempool and State in the node. It is intended for use by node-runners on a private network, and is not intended to be exposed publicly. Heavy load may impact the node's function.

If you require queries against historical ledger state, you may also wish to consider using the Gateway API.

Sub-APIs

The API is split into 5 sub apis:

  • Status (/status/*) - For status and configuration details for the node / engine.
  • Transaction (/transaction/*) - For transaction construction, preview, submission, and monitoring the status of an individual transaction.
  • Mempool (/mempool/*) - For information on the contents of the node's mempool.
  • Current State (/state/*) - For reading the state of entities. At present, we only support reading details from the top of the currently committed ledger.
  • Stream (/stream/*) - For reading the committed transactions.

Concepts

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.

Transactions

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 status of rejected transactions can be read at submission time or from the transaction status endpoint - by virtue of a rejection cache on the node. This cache is limited in size, so rejected statuses may no longer be tracked after a period of time.

For a more robust handling of transaction rejections, consider running your own Gateway.

State Model

The Radix Engine State Model can be thought of as a forest of state sub-trees. A state sub-tree consists of "entities". These entities have an ID, and 0 or more "substates" at keys underneath them. These substates are typed, and can own other entities, forming a tree of ownership.

Each state sub-tree has a root entity, and a single Bech32M Global Address, with a human-readable-prefix (and prefix byte) matching the root entity type.

As an example, entities include concepts like Components, Packages, Vaults, Resource Managers and Key-Value Stores. Substates under a component include the Component Struct, Component Data, and Access Rules substates.

Status Endpoints

For status and configuration details for the node / engine.

Get Network Configuration

Returns the network configuration of the network the node is connected to.

Responses
200

Network Configuration

500

Server error

post/status/network-configuration
Response samples
application/json
{
  • "version": {
    },
  • "network": "{{network}}",
  • "network_id": 255,
  • "network_hrp_suffix": "string",
  • "address_types": [
    ],
  • "well_known_addresses": {
    }
}

Get Network Status

Returns the current state and status of the node's copy of the ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

Responses
200

Network Status

500

Server error

post/status/network-status
Request samples
application/json
{
  • "network": "{{network}}"
}
Response samples
application/json
{
  • "pre_genesis_state_identifier": {
    },
  • "post_genesis_state_identifier": {
    },
  • "current_state_identifier": {
    }
}

Transaction Endpoints

For transaction construction, preview, submission, and monitoring the status of an individual transaction.

Parse Transaction Payload

Extracts the contents and hashes of various types of transaction payloads, or sub-payloads.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

payload_hex
required
string

A hex-encoded payload of a full transaction or a partial transaction - either a notarized transaction, a signed transaction intent an unsigned transaction intent, or a transaction manifest.

parse_mode
string

The type of transaction payload that should be assumed. If omitted, "Any" is used - where the payload is attempted to be parsed as each of the following in turn: Notarized, Signed, Unsigned, Manifest, Ledger.

Enum: "Any" "Notarized" "Signed" "Unsigned" "Manifest" "Ledger"
validation_mode
string

The type of validation that should be performed, if the payload correctly decompiles as a Notarized Transaction. This is only relevant for Notarized payloads. If omitted, "Static" is used.

Enum: "None" "Static" "Full"
response_mode
string

The amount of information to return in the response. "Basic" includes the type, validity information, and any relevant identifiers. "Full" also includes the fully parsed information. If omitted, "Full" is used.

Enum: "Basic" "Full"
Responses
200

Transaction Parse Response

400

Client error

500

Server error

post/transaction/parse
Request samples
application/json
{
  • "network": "{{network}}",
  • "payload_hex": "string",
  • "parse_mode": "Any",
  • "validation_mode": "None",
  • "response_mode": "Basic"
}
Response samples
application/json
{
  • "parsed": {
    }
}

Transaction Submit

Submits a notarized transaction to the network. Returns whether the transaction submission was already included in the node's mempool.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

notarized_transaction_hex
required
string

A hex-encoded, compiled notarized transaction.

Responses
200

Transaction Submit Response

400

Client error

500

Server error

post/transaction/submit
Request samples
application/json
{
  • "network": "{{network}}",
  • "notarized_transaction_hex": "string"
}
Response samples
application/json
{
  • "duplicate": true
}

Get Transaction Status

Shares the node's knowledge of any payloads associated with the given intent hash. Generally there will be a single payload for a given intent, but it's theoretically possible there may be multiple. This knowledge is summarised into a status for the intent. This summarised status in the response is likely sufficient for most clients.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

intent_hash
required
string (IntentHash) = 64 characters

The hex-encoded transaction intent hash. This is known as the Intent Hash, Transaction ID or Transaction Identifier for user transactions. This hash is SHA256(SHA256(compiled_intent))

Responses
200

Transaction status response

400

Client error

500

Server error

post/transaction/status
Request samples
application/json
{
  • "network": "{{network}}",
  • "intent_hash": "stringstringstringstringstringstringstringstringstringstringstri"
}
Response samples
application/json
{
  • "intent_status": "CommittedSuccess",
  • "status_description": "string",
  • "invalid_from_epoch": 10000000000,
  • "known_payloads": [
    ]
}

Get Transaction Receipt

Gets the transaction receipt for a committed transaction.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

intent_hash
required
string (IntentHash) = 64 characters

The hex-encoded transaction intent hash. This is known as the Intent Hash, Transaction ID or Transaction Identifier for user transactions. This hash is SHA256(SHA256(compiled_intent))

Responses
200

Committed transaction found response

400

Client error

404

Committed transaction not found response

500

Server error

post/transaction/receipt
Request samples
application/json
{
  • "network": "{{network}}",
  • "intent_hash": "stringstringstringstringstringstringstringstringstringstringstri"
}
Response samples
application/json
{
  • "committed": {
    }
}

Scrypto Call Preview

Preview a scrypto function or method call against the latest network state. Returns the result of the scrypto function or method call.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

required
object (TargetIdentifier)
arguments
required
Array of strings

Argument list

Responses
200

Result of the scrypto function call

400

Client error

500

Server error

post/transaction/call-preview
Request samples
application/json
{
  • "target": {
    },
  • "arguments": [
    ]
}
Response samples
application/json
{
  • "status": "Succeeded",
  • "output": {
    },
  • "error_message": "string"
}

Transaction Preview

Preview a transaction against the latest network state, and returns the preview receipt.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

manifest
required
string

A text-representation of a transaction manifest

blobs_hex
Array of strings

An array of hex-encoded blob data (optional)

start_epoch_inclusive
required
integer <int64> [ 0 .. 10000000000 ]

An integer between 0 and 10^10, marking the epoch at which the transaction starts being valid

end_epoch_exclusive
required
integer <int64> [ 0 .. 10000000000 ]

An integer between 0 and 10^10, marking the epoch at which the transaction is no longer valid

object (PublicKey)

The notary public key to use (optional)

notary_as_signatory
boolean

Whether the notary should count as a signatory (optional, default false)

cost_unit_limit
required
integer <int64> [ 0 .. 4294967295 ]

An integer between 0 and 2^32 - 1, giving the maximum number of cost units available for transaction execution

tip_percentage
required
integer <int32> [ 0 .. 255 ]

An integer between 0 and 255, giving the validator tip as a percentage amount. A value of 1 corresponds to 1% of the fee.

nonce
required
string

A decimal-string-encoded integer between 0 and 2^64 - 1, used to ensure the transaction intent is unique.

required
Array of objects (PublicKey)

A list of public keys to be used as transaction signers

required
object
Responses
200

Transaction preview response

400

Client error

500

Server error

post/transaction/preview
Request samples
application/json
{
  • "network": "{{network}}",
  • "manifest": "string",
  • "blobs_hex": [
    ],
  • "start_epoch_inclusive": 10000000000,
  • "end_epoch_exclusive": 10000000000,
  • "notary_public_key": {
    },
  • "notary_as_signatory": true,
  • "cost_unit_limit": 4294967295,
  • "tip_percentage": 255,
  • "nonce": "string",
  • "signer_public_keys": [
    ],
  • "flags": {
    }
}
Response samples
application/json
{
  • "receipt": {
    },
  • "resource_changes": [
    ],
  • "logs": [
    ]
}

Mempool Endpoints

For information on the contents of the node's mempool.

Get Mempool List

Returns the hashes of all the transactions currently in the mempool

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

Responses
200

Mempool List Response

500

Server error

post/mempool/list
Request samples
application/json
{
  • "network": "{{network}}"
}
Response samples
application/json
{
  • "contents": [
    ]
}

Get Mempool Transaction

Returns the payload of a transaction currently in the mempool

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

payload_hash
required
string (PayloadHash) = 64 characters

The hex-encoded notarized transaction hash. This is known as the Notarized Transaction Hash, Payload Hash or User Payload Hash. This hash is SHA256(SHA256(compiled_notarized_transaction))

Responses
200

Mempool Transaction Response

404

Not found error

500

Server error

post/mempool/transaction
Request samples
application/json
{
  • "network": "{{network}}",
  • "payload_hash": "stringstringstringstringstringstringstringstringstringstringstri"
}
Response samples
application/json
{
  • "notarized_transaction": {
    }
}

State Endpoints

For reading the state of entities. At present, we only support reading details from the top of the currently committed ledger.

Get Epoch Details

Reads the epoch manager's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

Responses
200

Current state response

400

Client error

500

Server error

post/state/epoch
Request samples
application/json
{
  • "network": "{{network}}"
}
Response samples
application/json
{
  • "epoch": 10000000000,
  • "epoch_manager": {
    },
  • "active_validator_set": {
    }
}

Get Clock Details

Reads the clock's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

Responses
200

Current state response

400

Client error

500

Server error

post/state/clock
Request samples
application/json
{
  • "network": "{{network}}"
}
Response samples
application/json
{
  • "current_minute": {
    }
}

Get Component Details

Reads the component's substate/s from the top of the current ledger. Also recursively extracts vault balance totals from the component's entity subtree.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

component_address
required
string

The Bech32m-encoded human readable version of the component's global address

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/component
Request samples
application/json
{
  • "network": "{{network}}",
  • "component_address": "string"
}
Response samples
application/json
{
  • "info": {
    },
  • "state": {
    },
  • "royalty_config": {
    },
  • "royalty_accumulator": {
    },
  • "metadata": {
    },
  • "access_rules": {
    },
  • "state_owned_vaults": [
    ],
  • "descendent_ids": [
    ]
}

Get Validator Details

Reads the validator's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

validator_address
required
string (ComponentAddress)

The Bech32m-encoded human readable version of the component address

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/validator
Request samples
application/json
{
  • "network": "{{network}}",
  • "validator_address": "string"
}
Response samples
application/json
{
  • "state": {
    },
  • "metadata": {
    },
  • "access_rules": {
    },
  • "state_owned_vaults": [
    ],
  • "descendent_ids": [
    ]
}

Get Access Controller Details

Reads the access controller's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

controller_address
required
string (ComponentAddress)

The Bech32m-encoded human readable version of the component address

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/access-controller
Request samples
application/json
{
  • "network": "{{network}}",
  • "controller_address": "string"
}
Response samples
application/json
{
  • "state": {
    },
  • "metadata": {
    },
  • "access_rules": {
    },
  • "state_owned_vaults": [
    ],
  • "descendent_ids": [
    ]
}

Get Resource Details

Reads the resource manager's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

resource_address
required
string

The Bech32m-encoded human readable version of the resource's global address

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/resource
Request samples
application/json
{
  • "network": "{{network}}",
  • "resource_address": "string"
}
Response samples
application/json
{
  • "manager": {
    },
  • "metadata": {
    },
  • "access_rules": {
    },
  • "vault_access_rules": {
    }
}

Get Non-Fungible Details

Reads the data associated with a single Non-Fungible Unit under a Non-Fungible Resource.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

resource_address
required
string

The Bech32m-encoded human readable version of the resource's global address

non_fungible_id
required
string (NonFungibleIdSimpleRepresentation)

The simple string representation of the non-fungible id. For string id types, this is simply the string itself; for integer types, this is the integer as a decimal; and for the bytes id type, this is the lower case hex representation. A non-fungible resource has a fixed NonFungibleIdType, so this representation uniquely identifies this non-fungible under the given resource address.

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/non-fungible
Request samples
application/json
{
  • "network": "{{network}}",
  • "resource_address": "string",
  • "non_fungible_id": "string"
}
Response samples
application/json
{
  • "non_fungible": {
    }
}

Get Package Details

Reads the package's substate/s from the top of the current ledger.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

package_address
required
string

The Bech32m-encoded human readable version of the package's global address

Responses
200

Current state response

400

Client error

404

Not found error

500

Server error

post/state/package
Request samples
application/json
{
  • "network": "{{network}}",
  • "package_address": "string"
}
Response samples
application/json
{
  • "info": {
    },
  • "royalty_config": {
    },
  • "royalty_accumulator": {
    },
  • "metadata": {
    },
  • "access_rules": {
    }
}

Stream Endpoints

To query the transaction stream of the ledger.

Get Committed Transactions

Returns the list of committed transactions.

Request
Request Body schema: application/json
network
required
string (NetworkIdentifier)

The logical name of the network

from_state_version
required
integer <int64> [ 1 .. 100000000000000 ]

An integer between 1 and 10^13, giving the first (resultant) state version to be returned

limit
required
integer

The maximum number of transactions that will be returned.

Responses
200

Committed transactions response

400

Client error

500

Server error

post/stream/transactions
Request samples
application/json
{
  • "network": "{{network}}",
  • "from_state_version": 1,
  • "limit": 0
}
Response samples
application/json
{
  • "from_state_version": 1,
  • "count": 10000,
  • "max_ledger_state_version": 1,
  • "transactions": [
    ]
}