Full Reference

Version: 1.4.1

OpenAPI 3.0 Rosetta API Spec

Endpoints

Account

Method	Endpoint	Description
POST	/account/balance	Get an Account Balance

Block

Method	Endpoint	Description
POST	/block	Get a Block
POST	/block/transaction	Get a Block Transaction

Construction

Method	Endpoint	Description
POST	/construction/combine	Create Network Transaction from Signatures
POST	/construction/derive	Derive an Address from a PublicKey
POST	/construction/hash	Get the Hash of a Signed Transaction
POST	/construction/metadata	Get Metadata for Transaction Construction
POST	/construction/parse	Parse a Transaction
POST	/construction/payloads	Generate an Unsigned Transaction and Signing Payloads
POST	/construction/preprocess	Create a Request to Fetch Metadata
POST	/construction/submit	Submit a Signed Transaction

Mempool

Method	Endpoint	Description
POST	/mempool	Get All Mempool Transactions
POST	/mempool/transaction	Get a Mempool Transaction

Network

Method	Endpoint	Description
POST	/network/list	Get List of Available Networks
POST	/network/options	Get Network Options
POST	/network/status	Get Network Status

Models

Objects

Model	Description
Allow	Allow specifies supported Operation status, Operation types, and all possible error statuses. This Allow object is used by clients to validate the correctness of a Rosetta Server implementation. It is expected that these clients will error if they receive some response that contains any of the above information that is not specified here.
Amount	Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.
Block	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.
Coin	Coin contains its unique identifier and the amount it represents.
CoinAction	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.
CoinChange	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).
Currency	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).
CurveType	CurveType is the type of cryptographic curve associated with a PublicKey.
Operation	Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction.
PublicKey	PublicKey contains a public key byte array for a particular CurveType encoded in hex. Note that there is no PrivateKey struct as this is NEVER the concern of an implementation.
Signature	Signature contains the payload that was signed, the public keys of the keypairs used to produce the signature, the signature (encoded in hex), and the SignatureType. PublicKey is often times not known during construction of the signing payloads but may be needed to combine signatures properly.
SignatureType	SignatureType is the type of a cryptographic signature.
SigningPayload	SigningPayload is signed by the client with the keypair associated with an address using the specified SignatureType. SignatureType can be optionally populated if there is a restriction on the signature scheme that can be used to sign the payload.
Transaction	Transactions contain an array of Operations that are attributable to the same TransactionIdentifier.

Identifiers

Model	Description
AccountIdentifier	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).
BlockIdentifier	The block_identifier uniquely identifies a block in a particular network.
CoinIdentifier	CoinIdentifier uniquely identifies a Coin.
NetworkIdentifier	The network_identifier specifies which network a particular object is associated with.
OperationIdentifier	The operation_identifier uniquely identifies an operation within a transaction.
PartialBlockIdentifier	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.
SubAccountIdentifier	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.
SubNetworkIdentifier	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.
TransactionIdentifier	The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

Requests and Responses

Model	Description
AccountBalanceRequest	An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.
AccountBalanceResponse	An AccountBalanceResponse is returned on the /account/balance endpoint. If an account has a balance for each AccountIdentifier describing it (ex: an ERC-20 token balance on a few smart contracts), an account balance request must be made with each AccountIdentifier.
BlockRequest	A BlockRequest is utilized to make a block request on the /block endpoint.
BlockResponse	A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions).
BlockTransactionRequest	A BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse.
BlockTransactionResponse	A BlockTransactionResponse contains information about a block transaction.
ConstructionCombineRequest	ConstructionCombineRequest is the input to the /construction/combine endpoint. It contains the unsigned transaction blob returned by /construction/payloads and all required signatures to create a network transaction.
ConstructionCombineResponse	ConstructionCombineResponse is returned by /construction/combine. The network payload will be sent directly to the construction/submit endpoint.
ConstructionDeriveRequest	ConstructionDeriveRequest is passed to the /construction/derive endpoint. Network is provided in the request because some blockchains have different address formats for different networks. Metadata is provided in the request because some blockchains allow for multiple address types (i.e. different address for validators vs normal accounts).
ConstructionDeriveResponse	ConstructionDeriveResponse is returned by the /construction/derive endpoint.
ConstructionHashRequest	ConstructionHashRequest is the input to the /construction/hash endpoint.
ConstructionMetadataRequest	A ConstructionMetadataRequest is utilized to get information required to construct a transaction. The Options object used to specify which metadata to return is left purposely unstructured to allow flexibility for implementers.
ConstructionMetadataResponse	The ConstructionMetadataResponse returns network-specific metadata used for transaction construction.
ConstructionParseRequest	ConstructionParseRequest is the input to the /construction/parse endpoint. It allows the caller to parse either an unsigned or signed transaction.
ConstructionParseResponse	ConstructionParseResponse contains an array of operations that occur in a transaction blob. This should match the array of operations provided to /construction/preprocess and /construction/payloads.
ConstructionPayloadsRequest	ConstructionPayloadsRequest is the request to /construction/payloads. It contains the network, a slice of operations, and arbitrary metadata that was returned by the call to /construction/metadata.
ConstructionPayloadsResponse	ConstructionTransactionResponse is returned by /construction/payloads. It contains an unsigned transaction blob (that is usually needed to construct the a network transaction from a collection of signatures) and an array of payloads that must be signed by the caller.
ConstructionPreprocessRequest	ConstructionPreprocessRequest is passed to the /construction/preprocess endpoint so that a Rosetta implementation can determine which metadata it needs to request for construction.
ConstructionPreprocessResponse	ConstructionPreprocessResponse contains the request that will be sent directly to /construction/metadata. If it is not necessary to make a request to /construction/metadata, options should be null.
ConstructionSubmitRequest	The transaction submission request includes a signed transaction.
MempoolResponse	A MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier.
MempoolTransactionRequest	A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.
MempoolTransactionResponse	A MempoolTransactionResponse contains an estimate of a mempool transaction. It may not be possible to know the full impact of a transaction in the mempool (ex: fee paid).
MetadataRequest	A MetadataRequest is utilized in any request where the only argument is optional metadata.
NetworkListResponse	A NetworkListResponse contains all NetworkIdentifiers that the node can serve information for.
NetworkOptionsResponse	NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors.
NetworkRequest	A NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier.
NetworkStatusResponse	NetworkStatusResponse contains basic information about the node's view of a blockchain network. It is assumed that any BlockIdentifier.Index less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional oldest_block_identifier field with the oldest block available to query. If this is not populated, it is assumed that the genesis_block_identifier is the oldest queryable block. If a Rosetta implementation performs some pre-sync before it is possible to query blocks, sync_status should be populated so that clients can still monitor healthiness. Without this field, it may appear that the implementation is stuck syncing and needs to be terminated.
TransactionIdentifierResponse	TransactionIdentifierResponse contains the transaction_identifier of a transaction that was submitted to either /construction/hash or /construction/submit.

Miscellaneous

Model	Description
Error	Instead of utilizing HTTP status codes to describe node errors (which often do not have a good analog), rich errors are returned using this object. Both the code and message fields can be individually used to correctly identify an error. Implementations MUST use unique values for both fields.
OperationStatus	OperationStatus is utilized to indicate which Operation status are considered successful.
Peer	A Peer is a representation of a node's peer.
SyncStatus	SyncStatus is used to provide additional context about an implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried until some sync phase occurs. If an implementation is immediately queryable, this model is often not populated.
Version	The Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.