Skip to main content

Full Reference

Version: 1.4.10

OpenAPI 3.0 Rosetta API Spec

Endpoints

Account

MethodEndpointDescription
POST/account/balanceGet an Account's Balance
POST/account/coinsGet an Account's Unspent Coins

Block

MethodEndpointDescription
POST/block/transactionGet a Block Transaction
POST/blockGet a Block

Call

MethodEndpointDescription
POST/callMake a Network-Specific Procedure Call

Construction

MethodEndpointDescription
POST/construction/combineCreate Network Transaction from Signatures
POST/construction/deriveDerive an AccountIdentifier from a PublicKey
POST/construction/hashGet the Hash of a Signed Transaction
POST/construction/metadataGet Metadata for Transaction Construction
POST/construction/parseParse a Transaction
POST/construction/payloadsGenerate an Unsigned Transaction and Signing Payloads
POST/construction/preprocessCreate a Request to Fetch Metadata
POST/construction/submitSubmit a Signed Transaction

Events

MethodEndpointDescription
POST/events/blocks[INDEXER] Get a range of BlockEvents

Mempool

MethodEndpointDescription
POST/mempoolGet All Mempool Transactions
POST/mempool/transactionGet a Mempool Transaction

Network

MethodEndpointDescription
POST/network/listGet List of Available Networks
POST/network/optionsGet Network Options
POST/network/statusGet Network Status
MethodEndpointDescription
POST/search/transactions[INDEXER] Search for Transactions

Models

Objects

ModelDescription
AllowAllow 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.
AmountAmount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.
BalanceExemptionBalanceExemption indicates that the balance for an exempt account could change without a corresponding Operation. This typically occurs with staking rewards, vesting balances, and Currencies with a dynamic supply. Currently, it is possible to exempt an account from strict reconciliation by SubAccountIdentifier.Address or by Currency. This means that any account with SubAccountIdentifier.Address would be exempt or any balance of a particular Currency would be exempt, respectively. BalanceExemptions should be used sparingly as they may introduce significant complexity for integrators that attempt to reconcile all account balance changes. If your implementation relies on any BalanceExemptions, you MUST implement historical balance lookup (the ability to query an account balance at any BlockIdentifier).
BlockBlocks 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.
BlockEventBlockEvent represents the addition or removal of a BlockIdentifier from storage. Streaming BlockEvents allows lightweight clients to update their own state without needing to implement their own syncing logic.
BlockEventTypeBlockEventType determines if a BlockEvent represents the addition or removal of a block.
BlockTransactionBlockTransaction contains a populated Transaction and the BlockIdentifier that contains it.
CoinCoin contains its unique identifier and the amount it represents.
CoinActionCoinActions 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.
CoinChangeCoinChange 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).
CurrencyCurrency 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).
CurveTypeCurveType is the type of cryptographic curve associated with a PublicKey.
DirectionUsed by RelatedTransaction to indicate the direction of the relation (i.e. cross-shard/cross-network sends may reference backward to an earlier transaction and async execution may reference forward). Can be used to indicate if a transaction relation is from child to parent or the reverse.
ExemptionTypeExemptionType is used to indicate if the live balance for an account subject to a BalanceExemption could increase above, decrease below, or equal the computed balance. * greater_or_equal: The live balance may increase above or equal the computed balance. This typically occurs with staking rewards that accrue on each block. * less_or_equal: The live balance may decrease below or equal the computed balance. This typically occurs as balance moves from locked to spendable on a vesting account. * dynamic: The live balance may increase above, decrease below, or equal the computed balance. This typically occurs with tokens that have a dynamic supply.
OperationOperations 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. Operations are used both to represent on-chain data (Data API) and to construct new transactions (Construction API), creating a standard interface for reading and writing to blockchains.
OperatorOperator is used by query-related endpoints to determine how to apply conditions. If this field is not populated, the default and value will be used.
PublicKeyPublicKey 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.
RelatedTransactionThe related_transaction allows implementations to link together multiple transactions. An unpopulated network identifier indicates that the related transaction is on the same network.
SignatureSignature 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.
SignatureTypeSignatureType is the type of a cryptographic signature.
SigningPayloadSigningPayload is signed by the client with the keypair associated with an AccountIdentifier 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.
TransactionTransactions contain an array of Operations that are attributable to the same TransactionIdentifier.

Identifiers

ModelDescription
AccountIdentifierThe 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).
BlockIdentifierThe block_identifier uniquely identifies a block in a particular network.
CoinIdentifierCoinIdentifier uniquely identifies a Coin.
NetworkIdentifierThe network_identifier specifies which network a particular object is associated with.
OperationIdentifierThe operation_identifier uniquely identifies an operation within a transaction.
PartialBlockIdentifierWhen 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.
SubAccountIdentifierAn 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.
SubNetworkIdentifierIn 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.
TransactionIdentifierThe transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

Requests and Responses

ModelDescription
AccountBalanceRequestAn 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.
AccountBalanceResponseAn 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. The coins field was removed and replaced by by /account/coins in v1.4.7.
AccountCoinsRequestAccountCoinsRequest is utilized to make a request on the /account/coins endpoint.
AccountCoinsResponseAccountCoinsResponse is returned on the /account/coins endpoint and includes all unspent Coins owned by an AccountIdentifier.
BlockRequestA BlockRequest is utilized to make a block request on the /block endpoint.
BlockResponseA BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indices can be skipped). If a query for one of these omitted indices is made, the response should not include a Block object. It is VERY important to note that blocks MUST still form a canonical, connected chain of blocks where each block has a unique index. In other words, the PartialBlockIdentifier of a block after an omitted block should reference the last non-omitted block.
BlockTransactionRequestA BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse.
BlockTransactionResponseA BlockTransactionResponse contains information about a block transaction.
CallRequestCallRequest is the input to the /call endpoint.
CallResponseCallResponse contains the result of a /call invocation.
ConstructionCombineRequestConstructionCombineRequest 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.
ConstructionCombineResponseConstructionCombineResponse is returned by /construction/combine. The network payload will be sent directly to the construction/submit endpoint.
ConstructionDeriveRequestConstructionDeriveRequest 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).
ConstructionDeriveResponseConstructionDeriveResponse is returned by the /construction/derive endpoint.
ConstructionHashRequestConstructionHashRequest is the input to the /construction/hash endpoint.
ConstructionMetadataRequestA 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. Options is not required in the case that there is network-wide metadata of interest. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.
ConstructionMetadataResponseThe ConstructionMetadataResponse returns network-specific metadata used for transaction construction. Optionally, the implementer can return the suggested fee associated with the transaction being constructed. The caller may use this info to adjust the intent of the transaction or to create a transaction with a different account that can pay the suggested fee. Suggested fee is an array in case fee payment must occur in multiple currencies.
ConstructionParseRequestConstructionParseRequest is the input to the /construction/parse endpoint. It allows the caller to parse either an unsigned or signed transaction.
ConstructionParseResponseConstructionParseResponse 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.
ConstructionPayloadsRequestConstructionPayloadsRequest 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. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.
ConstructionPayloadsResponseConstructionTransactionResponse 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.
ConstructionPreprocessRequestConstructionPreprocessRequest is passed to the /construction/preprocess endpoint so that a Rosetta implementation can determine which metadata it needs to request for construction. Metadata provided in this object should NEVER be a product of live data (i.e. the caller must follow some network-specific data fetching strategy outside of the Construction API to populate required Metadata). If live data is required for construction, it MUST be fetched in the call to /construction/metadata. The caller can provide a max fee they are willing to pay for a transaction. This is an array in the case fees must be paid in multiple currencies. The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided).
ConstructionPreprocessResponseConstructionPreprocessResponse contains options that will be sent unmodified to /construction/metadata. If it is not necessary to make a request to /construction/metadata, options should be omitted. Some blockchains require the PublicKey of particular AccountIdentifiers to construct a valid transaction. To fetch these PublicKeys, populate required_public_keys with the AccountIdentifiers associated with the desired PublicKeys. If it is not necessary to retrieve any PublicKeys for construction, required_public_keys should be omitted.
ConstructionSubmitRequestThe transaction submission request includes a signed transaction.
EventsBlocksRequestEventsBlocksRequest is utilized to fetch a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state.
EventsBlocksResponseEventsBlocksResponse contains an ordered collection of BlockEvents and the max retrievable sequence.
MempoolResponseA MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier.
MempoolTransactionRequestA MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.
MempoolTransactionResponseA 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).
MetadataRequestA MetadataRequest is utilized in any request where the only argument is optional metadata.
NetworkListResponseA NetworkListResponse contains all NetworkIdentifiers that the node can serve information for.
NetworkOptionsResponseNetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors.
NetworkRequestA NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier.
NetworkStatusResponseNetworkStatusResponse 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.
SearchTransactionsRequestSearchTransactionsRequest is used to search for transactions matching a set of provided conditions in canonical blocks.
SearchTransactionsResponseSearchTransactionsResponse contains an ordered collection of BlockTransactions that match the query in SearchTransactionsRequest. These BlockTransactions are sorted from most recent block to oldest block.
TransactionIdentifierResponseTransactionIdentifierResponse contains the transaction_identifier of a transaction that was submitted to either /construction/hash or /construction/submit.

Miscellaneous

ModelDescription
ErrorInstead 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.
OperationStatusOperationStatus is utilized to indicate which Operation status are considered successful.
PeerA Peer is a representation of a node's peer.
SyncStatusSyncStatus is used to provide additional context about an implementation's sync status. This object is often used by implementations to indicate healthiness when block data cannot be queried until some sync phase completes or cannot be determined by comparing the timestamp of the most recent block with the current time.
VersionThe Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.

Was this helpful?