Skip to main content

Get a Block

Retrieves the Block information for a given block identifier including a list of all transactions in the block.

Request Body REQUIRED
network_identifier object REQUIRED

The network_identifier specifies which network a particular object is associated with.

blockchain string REQUIRED

Blockchain name

network string REQUIRED

If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.

sub_network_identifier object

In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.

network string REQUIRED

Network name

metadata object

Meta data from subnetwork identifier

producer string REQUIRED

producer

block_identifier object REQUIRED

When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

Responses
200

Success

Schema OPTIONAL
block object OPTIONAL

Blocks contain an array of Transactions that occurred at a particular BlockIdentifier. A hard requirement for blocks returned by Rosetta implementations is that they MUST be inalterable: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents.

block_identifier object

The block_identifier uniquely identifies a block in a particular network.

hash string

This is also known as the block hash.

index integer

This is also known as the block height.

parent_block_identifier object

The block_identifier uniquely identifies a block in a particular network.

index integer

This is also known as the block height.

hash string

Block hash

timestamp integer

The timestamp of the block in milliseconds since the Unix Epoch. The timestamp is stored in milliseconds because some blockchains produce blocks more often than once a second.

transactions object[]

All the transactions in the block

transaction_identifier object

The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

hash string

Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier.

operations object[]

List of operations

operation_identifier object

The operation_identifier uniquely identifies an operation within a transaction.

index integer

The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described.

network_index integer OPTIONAL

Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).

related_operations object[] OPTIONAL

Restrict referenced related_operations to identifier indexes < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.

index integer

Describes the index of related operation.

network_index integer OPTIONAL

Some blockchains specify an operation index that is essential for client use. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).

type string

The network-specific type of the operation. Ensure that any type that can be returned here is also specified in the NetworkStatus. This can be very useful to downstream consumers that parse all block data.

status string OPTIONAL

The network-specific status of the operation. Status is not defined on the transaction object because blockchains with smart contracts may have transactions that partially apply. Blockchains with atomic transactions (all operations succeed or all operations fail) will have the same status for each operation.

account object OPTIONAL

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

address string

The address may be a cryptographic public key (or some encoding of it) or a provided username.

sub_account object OPTIONAL

An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.

address string

The address may be a cryptographic public key (or some encoding of it) or a provided username.

metadata object OPTIONAL

If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.

metadata object OPTIONAL

Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.

amount object OPTIONAL

Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.

value string

Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.

currency object

Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).

symbol string

Canonical symbol associated with a currency.

decimals integer

Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.

metadata object OPTIONAL

Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.

metadata object OPTIONAL
coin_change object OPTIONAL

CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model).

coin_identifier object

CoinIdentifier uniquely identifies a Coin.

identifier string

Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.

coin_action string

Possible values: [coin_created, coin_spent]

CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.

metadata object OPTIONAL

Operations Meta Data

metadata object OPTIONAL

Transactions that are related to other transactions (like a cross-shard transaction) should include the tranaction_identifier of these transactions in the metadata.

memo string OPTIONAL

STX token transfer memo.

size integer OPTIONAL

The Size

lockTime integer OPTIONAL

The locktime

metadata object

meta data

burn_block_height number
other_transactions object[] OPTIONAL

Some blockchains may require additional transactions to be fetched that weren't returned in the block response (ex: block only returns transaction hashes). For blockchains with a lot of transactions in each block, this can be very useful as consumers can concurrently fetch all transactions returned.

hash string

Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier.

400

Error

Schema OPTIONAL
code integer

Code is a network-specific error code. If desired, this code can be equivalent to an HTTP status code.

message string

Message is a network-specific error message. The message MUST NOT change for a given code. In particular, this means that any contextual information should be included in the details field.

retriable boolean

An error is retriable if the same request may succeed if submitted again.

details object OPTIONAL

Often times it is useful to return context specific to the request that caused the error (i.e. a sample of the stack trace or impacted account) in addition to the standard error message.

address string OPTIONAL
error string OPTIONAL