Powered by Redocly

Radix Gateway API (1.1.4)

Download OpenAPI specification:Download

License: The Radix License, Version 1.0

This API is designed to enable clients to efficiently query information on the RadixDLT ledger, and allow clients to simply build and submit transactions to the network.

The API is designed for use by the Radix Foundation's Desktop Wallet and Explorer, and replaces the original Olympia "Archive Node API".

Gateway API Overview

The Gateway API is separated into distinct groupings:

  • /gateway - Information about the Gateway API status
  • /account/* - To query account-related information
  • /token/* - To query token-related information
  • /validator/* and /validators - To query validator-related information
  • /transaction/* - To build, finalize and submit transactions, and to read the status and content of submitted and on-ledger transactions.

The Gateway API is implemented by the Network Gateway, which is configured to read from full node/s to extract and index data from the network.

Gateway API Format

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

  • All requests are POST requests.
  • Any error is returned with an HTTP status code of 500, with a returned error object.
    • The error object contains an HTTP-like code
    • The error object also contains a structured/typed details sub-object, with a type discriminator, allowing for structured error interpretation in clients.

Comparison to other Radix APIs

  • Core API - The Core API is a low level API exposed by full nodes, and designed for use on internal networks. It is primarily designed for network integrations such as exchanges, ledger analytics providers, or hosted ledger data dashboards. The Core API provides endpoints for reading the mempool, constructing transactions and also exposes a stream of committed transactions.

  • System API - The System API is a private API exposed by full nodes to read system status.

The Gateway API offers a much wider range of query options and is more performant than the Core API. It is built on top of the Core API, ingesting data via the Core API transaction stream into a relational database.

The Gateway API transaction/construction endpoints operate with the concept of "actions" - these are higher-levels of intent compared with the Core API, which makes it easier for clients to use. The Core API should be used if you require more power/flexiblity for managing UTXOs, or submitting transactions which can't be mapped to a Gateway API action.

Status Endpoints

To query information about the Gateway API status.

Get Gateway Info

Returns the Gateway API version, network and current ledger state.

Request
Request Body schema: application/json
required
object (GatewayRequest)
Responses
200

The Network

500

Gateway Error

post/gateway
Request samples
application/json
{ }
Response samples
application/json
{
  • "network_identifier": {
    },
  • "ledger_state": null,
  • "target_ledger_state": null
}

Account Endpoints

To query account-related information.

Derive Account Identifier

Returns the account address associated with the given public key.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (PublicKey)
Responses
200

Token info

500

Gateway Error

post/account/derive
Request samples
application/json
{
  • "network_identifier": {
    },
  • "public_key": {
    }
}
Response samples
application/json
{
  • "account_identifier": {
    }
}

Get Account Balances

Returns an account's available and staked token balances, given an account address. If an account address is valid, but doesn't have any ledger transactions against it, this endpoint still returns a successful response.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (AccountIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Balances of Account

500

Gateway Error

post/account/balances
Request samples
application/json
{
  • "network_identifier": {
    },
  • "account_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "account_balances": {
    }
}

Get Stake Positions

Returns the xrd which the account has in pending and active delegated stake positions with validators, given an account address. If an account address is valid, but doesn't have any ledger transactions against it, this endpoint still returns a successful response.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (AccountIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

List of Stake Positions

500

Gateway Error

post/account/stakes
Request samples
application/json
{
  • "network_identifier": {
    },
  • "account_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "pending_stakes": [
    ],
  • "stakes": [
    ]
}

Get Unstake Positions

Returns the xrd which the account has in pending and temporarily-locked delegated unstake positions with validators, given an account address. If an account address is valid, but doesn't have any ledger transactions against it, this endpoint still returns a successful response.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (AccountIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

List of Unstake Positions

500

Gateway Error

post/account/unstakes
Request samples
application/json
{
  • "network_identifier": {
    },
  • "account_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "pending_unstakes": [
    ],
  • "unstakes": [
    ]
}

Get Account Transactions

Returns user-initiated transactions involving the given account address which have been succesfully committed to the ledger. The transactions are returned in a paginated format, ordered by most recent. If an account address is valid, but doesn't have any ledger transactions against it, this endpoint still returns a successful response.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (AccountIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

cursor
string

This cursor allows forward pagination, by providing the cursor from the previous request.

limit
integer

The page size requested. The maximum value is 30 at present.

Responses
200

List of Transactions

500

Gateway Error

post/account/transactions
Request samples
application/json
{
  • "network_identifier": {
    },
  • "account_identifier": {
    },
  • "cursor": "0",
  • "limit": 10
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "total_count": 0,
  • "next_cursor": "string",
  • "transactions": [
    ]
}

Token Endpoints

To query token-related information.

Get Native Token Info

Returns information about XRD, including its Radix Resource Identifier.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Token info

500

Gateway Error

post/token/native
Request samples
application/json
{
  • "network_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "token": {
    }
}

Get Token Info

Returns information about any token, given its Radix Resource Identifier.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (TokenIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Token info

500

Gateway Error

post/token
Request samples
application/json
{
  • "network_identifier": {
    },
  • "token_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "token": {
    }
}

Derive Token Identifier

Returns the Radix Resource Identifier of a token with the given symbol, created by an account with the given public key.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (PublicKey)
symbol
required
string
Responses
200

Token info

500

Gateway Error

post/token/derive
Request samples
application/json
{
  • "network_identifier": {
    },
  • "public_key": {
    },
  • "symbol": "yourtoken"
}
Response samples
application/json
{
  • "token_identifier": {
    }
}

Validator Endpoints

To query validator-related information.

Get Validator

Returns information about a validator, given a validator address. If a validator address is valid, but has not appeared on ledger as a validator, this endpoint still returns a successful response.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (ValidatorIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Validator Info

500

Gateway Error

post/validator
Request samples
application/json
{
  • "network_identifier": {
    },
  • "validator_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "validator": {
    }
}

Get Validator Identifier

Returns the validator address associated with the given public key.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (PublicKey)
Responses
200

Validator Info

500

Gateway Error

post/validator/derive
Request samples
application/json
{
  • "network_identifier": {
    },
  • "public_key": {
    }
}
Response samples
application/json
{
  • "account_identifier": {
    }
}

Get Validators

Returns information about all validators.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Ordered list of validators

500

Gateway Error

post/validators
Request samples
application/json
{
  • "network_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "validators": [
    ]
}

Get Validator Stakes

Returns paginated results about the delegated stakes from accounts to a validator. The results are totalled by account, and ordered by account age (oldest to newest).

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

required
object (ValidatorIdentifier)
cursor
string

This cursor allows forward pagination, by providing the cursor from the previous request.

limit
integer

The page size requested. The maximum value is 30 at present.

Responses
200

Page of account-validator stakes.

500

Gateway Error

post/validator/stakes
Request samples
application/json
{
  • "network_identifier": {
    },
  • "validator_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "total_count": 0,
  • "next_cursor": "string",
  • "account_stake_delegations": [
    ]
}

Transaction Endpoints

To build, finalize and submit transactions, and to query transaction status and contents.

Get Transaction Rules

Returns the current rules used to build and validate transactions in the Radix Engine.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Rules for transaction construction

500

Gateway Error

post/transaction/rules
Request samples
application/json
{
  • "network_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "transaction_rules": {
    }
}

Get Recent Transactions

Returns user-initiated transactions which have been succesfully committed to the ledger. The transactions are returned in a paginated format, ordered by most recent.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

cursor
string

This cursor allows forward pagination, by providing the cursor from the previous request.

limit
integer

The page size requested. The maximum value is 30 at present.

Responses
200

A page of the most recent transactions

500

Gateway Error

post/transaction/recent
Request samples
application/json
{
  • "network_identifier": {
    },
  • "limit": 10
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "next_cursor": "string",
  • "transactions": [
    ]
}

Build Transaction

Returns a built unsigned transaction payload, from a set of intended actions.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

required
Array of objects (Action)
required
object (AccountIdentifier)
message
string

The hex-encoded message bytes.

disable_token_mint_and_burn
boolean

If true, mints and burns (aside from fee payments) are not permitted during transaction execution.

Responses
200

An unsigned transaction

500

Gateway Error

post/transaction/build
Request samples
application/json
{
  • "network_identifier": {
    },
  • "actions": [
    ],
  • "fee_payer": {
    },
  • "disable_token_mint_and_burn": true
}
Response samples
application/json
{
  • "transaction_build": {
    }
}

Finalize Transaction

Returns a signed transaction payload and transaction identifier, from an unsigned transaction payload and signature.

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

The unsigned transaction payload, hex encoded.

required
object (Signature)
submit
boolean

If true, the transaction is immediately submitted after finalization. However, we recommend that a transaction is submitted in a step after finalization. This ensures that you have a transaction identifier on hand to monitor the transaction status, even if the submission request failed with an uncertain error.

Responses
200

Final Signed Transaction

500

Gateway Error

post/transaction/finalize
Request samples
application/json
{
  • "network_identifier": {
    },
  • "unsigned_transaction": "0d00010776bf65acf2d25e9dcf4c716f5f39f201dccbfa173ad9c7f1c1dbcb8a86776b4d0000000101002100000000000000000000000000000000000000000000000000012901c1cf3900000200450600040279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798010000000000000000000000000000000000000000000000017afba303493b7ff8000800000200450600040279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798010000000000000000000000000000000000000000000000017afba303493b7f9402004506000402c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5010000000000000000000000000000000000000000000000000000000000000064000c003430303030366336663631363432303734363537333734363936653637323037343732363136653733363136333734363936663665",
  • "signature": {
    },
  • "submit": false
}
Response samples
application/json
{
  • "signed_transaction": "string",
  • "transaction_identifier": {
    }
}

Submit Transaction

Submits a signed transaction payload to the network. The transaction identifier from finalize or submit can then be used to track the transaction status.

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

The signed transaction payload which can be submitted, hex encoded.

Responses
200

Successful Submission

500

Gateway Error

post/transaction/submit
Request samples
application/json
{
  • "network_identifier": {
    },
  • "signed_transaction": "0d00010776bf65acf2d25e9dcf4c716f5f39f201dccbfa173ad9c7f1c1dbcb8a86776b4d0000000101002100000000000000000000000000000000000000000000000000012901c1cf3900000200450600040279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798010000000000000000000000000000000000000000000000017afba303493b7ff8000800000200450600040279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798010000000000000000000000000000000000000000000000017afba303493b7f9402004506000402c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5010000000000000000000000000000000000000000000000000000000000000064000c0034303030303663366636313634323037343635373337343639366536373230373437323631366537333631363337343639366636650b00cda0fcd31bf976aa65c31c180b4f595a61c866252c52898b952b8fe1d8fdcc33999e83036f9529c6250c07423d8b57f252dfba1b843385970bfa69f2c367658e"
}
Response samples
application/json
{
  • "transaction_identifier": {
    }
}

Transaction Status

Returns the status and contents of the transaction with the given transaction identifier. Transaction identifiers which aren't recognised as either belonging to a committed transaction or a transaction submitted through this Network Gateway may return a TransactionNotFoundError. Transaction identifiers relating to failed transactions will, after a delay, also be reported as a TransactionNotFoundError.

Request
Request Body schema: application/json
required
required
object (NetworkIdentifier)
required
object (TransactionIdentifier)
object (PartialLedgerStateIdentifier)

Optional. Allows a client to request a response referencing an earlier (at_* properties) or later (from_* properties) ledger state.

Responses
200

Transaction Status

500

Gateway Error

post/transaction/status
Request samples
application/json
{
  • "network_identifier": {
    },
  • "transaction_identifier": {
    }
}
Response samples
application/json
{
  • "ledger_state": {
    },
  • "transaction": {
    }
}