Flow Access API Specification
The Access API is implemented as a gRPC service.
A language-agnostic specification for this API is defined using Protocol Buffers, which can be used to generate client libraries in a variety of programming languages.
Flow Access Node Endpoints
| Network | GRPC | Web GRPC | REST |
|---|---|---|---|
| Mainnet | access.mainnet.nodes.onflow.org:9000 | mainnet.onflow.org | rest-mainnet.onflow.org |
| Testnet | access.devnet.nodes.onflow.org:9000 | testnet.onflow.org | rest-testnet.onflow.org |
| Previewnet | access.previewnet.nodes.onflow.org:9000 | previewnet.onflow.org | reset-previewnet.onflow.org |
Ping
Ping will return a successful response if the Access API is ready and available.
_10rpc Ping(PingRequest) returns (PingResponse)
If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.
Request
_10message PingRequest {}
Response
_10message PingResponse {}
Block Headers
The following methods query information about block headers.
GetLatestBlockHeader
GetLatestBlockHeader gets the latest sealed or unsealed block header.
_10rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)
Request
_10message GetLatestBlockHeaderRequest {_10 bool is_sealed_10}
Response
_10message BlockHeaderResponse {_10 flow.BlockHeader block_10 flow.BlockStatus block_status_10}
GetBlockHeaderByID
GetBlockHeaderByID gets a block header by ID.
_10rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)
Request
_10message GetBlockHeaderByIDRequest {_10 bytes id_10}
Response
_10message BlockHeaderResponse {_10 flow.BlockHeader block_10 flow.BlockStatus block_status_10}
GetBlockHeaderByHeight
GetBlockHeaderByHeight gets a block header by height.
_10rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)
Request
_10message GetBlockHeaderByHeightRequest {_10 uint64 height_10}
Response
_10message BlockHeaderResponse {_10 flow.BlockHeader block_10 flow.BlockStatus block_status_10}
Blocks
The following methods query information about full blocks.
GetLatestBlock
GetLatestBlock gets the full payload of the latest sealed or unsealed block.
_10rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)
Request
_10message GetLatestBlockRequest {_10 bool is_sealed_10}
Response
_10message BlockResponse {_10 flow.Block block_10 flow.BlockStatus block_status_10}
GetBlockByID
GetBlockByID gets a full block by ID.
_10rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)
Request
_10message GetBlockByIDRequest {_10 bytes id_10}
Response
_10message BlockResponse {_10 flow.Block block_10 flow.BlockStatus block_status_10}
GetBlockByHeight
GetBlockByHeight gets a full block by height.
_10rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)
Request
_10message GetBlockByHeightRequest {_10 uint64 height_10}
Response
_10message BlockResponse {_10 flow.Block block_10 flow.BlockStatus block_status_10}
Collections
The following methods query information about collections.
GetCollectionByID
GetCollectionByID gets a collection by ID.
_10rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)
Request
_10message GetCollectionByIDRequest {_10 bytes id_10}
Response
_10message CollectionResponse {_10 flow.Collection collection_10}
Transactions
The following methods can be used to submit transactions and fetch their results.
SendTransaction
SendTransaction submits a transaction to the network.
_10rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse)
SendTransaction determines the correct cluster of collection nodes that is responsible for collecting the transaction based on the hash of the transaction and forwards the transaction to that cluster.
Request
SendTransactionRequest message contains the transaction that is being request to be executed.
_10message SendTransactionRequest {_10 flow.Transaction transaction_10}
Response
SendTransactionResponse message contains the ID of the submitted transaction.
_10message SendTransactionResponse {_10 bytes id_10}
GetTransaction
GetTransaction gets a transaction by ID.
If the transaction is not found in the access node cache, the request is forwarded to a collection node.
Currently, only transactions within the current epoch can be queried.
_10rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)
Request
GetTransactionRequest contains the ID of the transaction that is being queried.
_10message GetTransactionRequest {_10 bytes id_10}
Response
TransactionResponse contains the basic information about a transaction, but does not include post-execution results.
_10message TransactionResponse {_10 flow.Transaction transaction_10}
GetTransactionResult
GetTransactionResult gets the execution result of a transaction.
_10rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)
Request
_10message GetTransactionRequest {_10 bytes id_10}
Response
_10message TransactionResultResponse {_10 flow.TransactionStatus status_10 uint32 status_code_10 string error_message_10 repeated flow.Event events_10}
Accounts
GetAccount
GetAccount gets an account by address at the latest sealed block.
⚠️ Warning: this function is deprecated. It behaves identically to GetAccountAtLatestBlock and will be removed in a future version.
_10rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)
Request
_10message GetAccountRequest {_10 bytes address_10}
Response
_10message GetAccountResponse {_10 Account account_10}
GetAccountAtLatestBlock
GetAccountAtLatestBlock gets an account by address.
The access node queries an execution node for the account details, which are stored as part of the sealed execution state.
_10rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)
Request
_10message GetAccountAtLatestBlockRequest {_10 bytes address_10}
Response
_10message AccountResponse {_10 Account account_10}
GetAccountAtBlockHeight
GetAccountAtBlockHeight gets an account by address at the given block height.
The access node queries an execution node for the account details, which are stored as part of the execution state.
_10rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)
Request
_10message GetAccountAtBlockHeightRequest {_10 bytes address_10 uint64 block_height_10}
Response
_10message AccountResponse {_10 Account account_10}
Scripts
ExecuteScriptAtLatestBlock
ExecuteScriptAtLatestBlock executes a read-only Cadence script against the latest sealed execution state.
This method can be used to read execution state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)
This method is a shortcut for the following:
_10header = GetLatestBlockHeader()_10value = ExecuteScriptAtBlockID(header.ID, script)
Request
_10message ExecuteScriptAtLatestBlockRequest {_10 bytes script_10}
Response
_10message ExecuteScriptResponse {_10 bytes value_10}
ExecuteScriptAtBlockID
ExecuteScriptAtBlockID executes a ready-only Cadence script against the execution state at the block with the given ID.
This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)
Request
_10message ExecuteScriptAtBlockIDRequest {_10 bytes block_id_10 bytes script_10}
Response
_10message ExecuteScriptResponse {_10 bytes value_10}
ExecuteScriptAtBlockHeight
ExecuteScriptAtBlockHeight executes a ready-only Cadence script against the execution state at the given block height.
This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)
Request
_10message ExecuteScriptAtBlockHeightRequest {_10 uint64 block_height_10 bytes script_10}
Response
_10message ExecuteScriptResponse {_10 bytes value_10}
Events
The following methods can be used to query for on-chain events.
GetEventsForHeightRange
GetEventsForHeightRange retrieves events emitted within the specified block range.
_10rpc GetEventsForHeightRange(GetEventsForHeightRangeRequest) returns (GetEventsForHeightRangeResponse)
Events can be requested for a specific sealed block range via the start_height and end_height (inclusive) fields and further filtered by event type via the type field.
If start_height is greater than the current sealed chain height, then this method will return an error.
If end_height is greater than the current sealed chain height, then this method will return events up to and including the latest sealed block.
The event results are grouped by block, with each group specifying a block ID, height and block timestamp.
Event types are name-spaced with the address of the account and contract in which they are declared.
Request
_10message GetEventsForHeightRangeRequest {_10 string type_10 uint64 start_height = 2;_10 uint64 end_height = 3;_10}
Response
_10message EventsResponse {_10 message Result {_10 bytes block_id = 1;_10 uint64 block_height = 2;_10 repeated entities.Event events = 3;_10 google.protobuf.Timestamp block_timestamp = 4;_10 }_10 repeated Result results = 1;_10}
GetEventsForBlockIDs
GetEventsForBlockIDs retrieves events for the specified block IDs and event type.
_10rpc GetEventsForBlockIDs(GetEventsForBlockIDsRequest) returns (GetEventsForBlockIDsResponse)
Events can be requested for a list of block IDs via the block_ids field and further filtered by event type via the type field.
The event results are grouped by block, with each group specifying a block ID, height and block timestamp.
Request
_10message GetEventsForBlockIDsRequest {_10 string type = 1;_10 repeated bytes block_ids = 2;_10}
Response
_10message EventsResponse {_10 message Result {_10 bytes block_id = 1;_10 uint64 block_height = 2;_10 repeated entities.Event events = 3;_10 google.protobuf.Timestamp block_timestamp = 4;_10 }_10 repeated Result results = 1;_10}
Network Parameters
Network parameters provide information about the Flow network. Currently, it only includes the chain ID. The following method can be used to query for network parameters.
GetNetworkParameters
GetNetworkParameters retrieves the network parameters.
_10rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)
Request
_10message GetNetworkParametersRequest {}
Response
_10message GetNetworkParametersResponse {_10 string chain_id = 1;_10}
| Field | Description |
|---|---|
| chain_id | Chain ID helps identify the Flow network. It can be one of flow-mainnet, flow-testnet or flow-emulator |
Protocol state snapshot
The following method can be used to query the latest protocol state snapshot.
GetLatestProtocolStateSnapshotRequest
GetLatestProtocolStateSnapshotRequest retrieves the latest Protocol state snapshot serialized as a byte array.
It is used by Flow nodes joining the network to bootstrap a space-efficient local state.
_10rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);
Request
_10message GetLatestProtocolStateSnapshotRequest {}
Response
_10message ProtocolStateSnapshotResponse {_10 bytes serializedSnapshot = 1;_10}
Execution results
The following method can be used to query the for execution results for a given block.
GetExecutionResultForBlockID
GetExecutionResultForBlockID retrieves execution result for given block. It is different from Transaction Results,
and contain data about chunks/collection level execution results rather than particular transactions.
Particularly, it contains EventsCollection hash for every chunk which can be used to verify the events for a block.
_10rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);
Request
_10message GetExecutionResultForBlockIDRequest {_10 bytes block_id = 1;_10}
Response
_10message ExecutionResultForBlockIDResponse {_10 flow.ExecutionResult execution_result = 1;_10}
Entities
Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.
Block
_10message Block {_10 bytes id_10 bytes parent_id_10 uint64 height_10 google.protobuf.Timestamp timestamp_10 repeated CollectionGuarantee collection_guarantees_10 repeated BlockSeal block_seals_10 repeated bytes signatures_10}
| Field | Description |
|---|---|
| id | SHA3-256 hash of the entire block payload |
| height | Height of the block in the chain |
| parent_id | ID of the previous block in the chain |
| timestamp | Timestamp of when the proposer claims it constructed the block. NOTE: It is included by the proposer, there are no guarantees on how much the time stamp can deviate from the true time the block was published. Consider observing blocks' status changes yourself to get a more reliable value. |
| collection_guarantees | List of collection guarantees |
| block_seals | List of block seals |
| signatures | BLS signatures of consensus nodes |
The detailed semantics of block formation are covered in the block formation guide.
Block Header
A block header is a summary of a block and contains only the block ID, height, and parent block ID.
_10message BlockHeader {_10 bytes id_10 bytes parent_id_10 uint64 height_10}
| Field | Description |
|---|---|
| id | SHA3-256 hash of the entire block payload |
| parent_id | ID of the previous block in the chain |
| height | Height of the block in the chain |
Block Seal
A block seal is an attestation that the execution result of a specific block has been verified and approved by a quorum of verification nodes.
_10message BlockSeal {_10 bytes block_id_10 bytes execution_receipt_id_10 repeated bytes execution_receipt_signatures_10 repeated bytes result_approval_signatures_10}
| Field | Description |
|---|---|
| block_id | ID of the block being sealed |
| execution_receipt_id | ID execution receipt being sealed |
| execution_receipt_signatures | BLS signatures of verification nodes on the execution receipt contents |
| result_approval_signatures | BLS signatures of verification nodes on the result approval contents |
Block Status
_10enum BlockStatus {_10 UNKNOWN = 0;_10 FINALIZED = 1;_10 SEALED = 2;_10}
| Value | Description |
|---|---|
| UNKNOWN | The block status is not known. |
| FINALIZED | The consensus nodes have finalized the block |
| SEALED | The verification nodes have verified the block |
Collection
A collection is a batch of transactions that have been included in a block. Collections are used to improve consensus throughput by increasing the number of transactions per block.
_10message Collection {_10 bytes id_10 repeated bytes transaction_ids_10}
| Field | Description |
|---|---|
| id | SHA3-256 hash of the collection contents |
| transaction_ids | Ordered list of transaction IDs in the collection |
Collection Guarantee
A collection guarantee is a signed attestation that specifies the collection nodes that have guaranteed to store and respond to queries about a collection.
_10message CollectionGuarantee {_10 bytes collection_id_10 repeated bytes signatures_10}
| Field | Description |
|---|---|
| collection_id | SHA3-256 hash of the collection contents |
| signatures | BLS signatures of the collection nodes guaranteeing the collection |
Transaction
A transaction represents a unit of computation that is submitted to the Flow network.
_23message Transaction {_23 bytes script_23 repeated bytes arguments_23 bytes reference_block_id_23 uint64 gas_limit_23 TransactionProposalKey proposal_key_23 bytes payer_23 repeated bytes authorizers_23 repeated TransactionSignature payload_signatures_23 repeated TransactionSignature envelope_signatures_23}_23_23message TransactionProposalKey {_23 bytes address_23 uint32 key_id_23 uint64 sequence_number_23}_23_23message TransactionSignature {_23 bytes address_23 uint32 key_id_23 bytes signature_23}
| Field | Description |
|---|---|
| script | Raw source code for a Cadence script, encoded as UTF-8 bytes |
| arguments | Arguments passed to the Cadence script, encoded as JSON-Cadence bytes |
| reference_block_id | Block ID used to determine transaction expiry |
| proposal_key | Account key used to propose the transaction |
| payer | Address of the payer account |
| authorizers | Addresses of the transaction authorizers |
| signatures | Signatures from all signer accounts |
The detailed semantics of transaction creation, signing and submission are covered in the transaction submission guide.
Proposal Key
The proposal key is used to specify a sequence number for the transaction. Sequence numbers are covered in more detail here.
| Field | Description |
|---|---|
| address | Address of proposer account |
| key_id | ID of proposal key on the proposal account |
| sequence_number | Sequence number for the proposal key |
Transaction Signature
| Field | Description |
|---|---|
| address | Address of the account for this signature |
| key_id | ID of the account key |
| signature | Raw signature byte data |
Transaction Status
_10enum TransactionStatus {_10 UNKNOWN = 0;_10 PENDING = 1;_10 FINALIZED = 2;_10 EXECUTED = 3;_10 SEALED = 4;_10 EXPIRED = 5;_10}
| Value | Description |
|---|---|
| UNKNOWN | The transaction status is not known. |
| PENDING | The transaction has been received by a collector but not yet finalized in a block. |
| FINALIZED | The consensus nodes have finalized the block that the transaction is included in |
| EXECUTED | The execution nodes have produced a result for the transaction |
| SEALED | The verification nodes have verified the transaction (the block in which the transaction is) and the seal is included in the latest block |
| EXPIRED | The transaction was submitted past its expiration block height. |
Account
An account is a user's identity on Flow. It contains a unique address, a balance, a list of public keys and the code that has been deployed to the account.
_10message Account {_10 bytes address_10 uint64 balance_10 bytes code_10 repeated AccountKey keys_10 map<string, bytes> contracts_10}
| Field | Description |
|---|---|
| address | A unique account identifier |
| balance | The account balance |
| code | The code deployed to this account (deprecated, use contracts instead) |
| keys | A list of keys configured on this account |
| contracts | A map of contracts or contract interfaces deployed on this account |
The code and contracts fields contain the raw Cadence source code, encoded as UTF-8 bytes.
More information on accounts can be found here.
Account Key
An account key is a reference to a public key associated with a Flow account. Accounts can be configured with zero or more public keys, each of which can be used for signature verification when authorizing a transaction.
_10message AccountKey {_10 uint32 id_10 bytes public_key_10 uint32 sign_algo_10 uint32 hash_algo_10 uint32 weight_10 uint32 sequence_number_10 bool revoked_10}
| Field | Description |
|---|---|
| id | Index of the key within the account, used as a unique identifier |
| public_key | Public key encoded as bytes |
| sign_algo | Signature algorithm |
| hash_algo | Hash algorithm |
| weight | Weight assigned to the key |
| sequence_number | Sequence number for the key |
| revoked | Flag indicating whether or not the key has been revoked |
More information on account keys, key weights and sequence numbers can be found here.
Event
An event is emitted as the result of a transaction execution. Events are either user-defined events originating from a Cadence smart contract, or built-in Flow system events.
_10message Event {_10 string type_10 bytes transaction_id_10 uint32 transaction_index_10 uint32 event_index_10 bytes payload_10}
| Field | Description |
|---|---|
| type | Fully-qualified unique type identifier for the event |
| transaction_id | ID of the transaction the event was emitted from |
| transaction_index | Zero-based index of the transaction within the block |
| event_index | Zero-based index of the event within the transaction |
| payload | Event fields encoded as JSON-Cadence values |
Execution Result
Execution result for a particular block.
_10message ExecutionResult {_10 bytes previous_result_id_10 bytes block_id_10 repeated Chunk chunks_10 repeated ServiceEvent service_events_10}
| Field | Description |
|---|---|
| previous_result_id | Identifier of parent block execution result |
| block_id | ID of the block this execution result corresponds to |
| chunks | Zero or more chunks |
| service_events | Zero or more service events |
Chunk
Chunk described execution information for given collection in a block
_10message Chunk {_10 bytes start_state_10 bytes event_collection_10 bytes block_id_10 uint64 total_computation_used_10 uint64 number_of_transactions_10 uint64 index_10 bytes end_state_10}
| Field | Description |
|---|---|
| start_state | State commitment at start of the chunk |
| event_collection | Hash of events emitted by transactions in this chunk |
| block_id | Identifier of a block |
| total_computation_used | Total computation used by transactions in this chunk |
| number_of_transactions | Number of transactions in a chunk |
| index | Index of chunk inside a block (zero-based) |
| end_state | State commitment after executing chunk |
Service Event
Special type of events emitted in system chunk used for controlling Flow system.
_10message ServiceEvent {_10 string type;_10 bytes payload;_10}
| Field | Description |
|---|---|
| type | Type of an event |
| payload | JSON-serialized content of an event |
Subscriptions
SubscribeEvents
SubscribeEvents streams events for all blocks starting at the requested start block, up until the latest available block. Once the latest is
reached, the stream will remain open and responses are sent for each new block as it becomes available.
Events within each block are filtered by the provided EventFilter, and only those events that match the filter are returned. If no filter is provided, all events are returned.
Responses are returned for each block containing at least one event that matches the filter. Additionally, heatbeat responses (SubscribeEventsResponse with no events) are returned periodically to allow clients to track which blocks were searched. Clients can use this information to determine which block to start from when reconnecting.
_10 rpc SubscribeEvents(SubscribeEventsRequest) returns (stream SubscribeEventsResponse)
Request
_10message SubscribeEventsRequest {_10 bytes start_block_id_10 uint64 start_block_height_10 EventFilter filter_10 uint64 heartbeat_interval_10 entities.EventEncodingVersion event_encoding_version_10}
| Field | Description |
|---|---|
| start_block_id | The first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
| start_block_height | Block height of the first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
| filter | Filter to apply to events for each block searched. If no filter is provided, all events are returned |
| heartbeat_interval | Interval in block heights at which the server should return a heartbeat message to the client |
| event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Response
_10message SubscribeEventsResponse {_10 bytes block_id_10 uint64 block_height_10 repeated entities.Event events_10 google.protobuf.Timestamp block_timestamp_10}
SubscribeExecutionData
SubscribeExecutionData streams execution data for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new execution data as it becomes available.
_10 rpc SubscribeExecutionData(SubscribeExecutionDataRequest) returns (stream SubscribeExecutionDataResponse)
Request
_10message SubscribeExecutionDataRequest {_10 bytes start_block_id_10 uint64 start_block_height_10 entities.EventEncodingVersion event_encoding_version_10}
| Field | Description |
|---|---|
| start_block_id | The first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
| start_block_height | Block height of the first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
| event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Response
_10message SubscribeExecutionDataResponse {_10 uint64 block_height_10 entities.BlockExecutionData block_execution_data_10 google.protobuf.Timestamp block_timestamp_10}
Execution data
EventFilter
EventFilter defines the filter to apply to block events. Filters are applied as an OR operation, i.e. any event matching any of the filters is returned.
If no filters are provided, all events are returned. If there are any invalid filters, the API will return an InvalidArgument error.
_10message EventFilter {_10 repeated string event_type_10 repeated string contract_10 repeated string address_10}
| Field | Description |
|---|---|
| event_type | A list of full event types to include. Event types have 2 formats: _ Protocol events: flow.[event name]_ Smart contract events: A.[contract address].[contract name].[event name] |
| contract | A list of contracts who's events should be included. Contracts have the following name formats: _ Protocol events: flow_ Smart contract events: A.[contract address].[contract name]This filter matches on the full contract including its address, not just the contract's name |
| address | A list of addresses who's events should be included. Addresses must be Flow account addresses in hex format and valid for the network the node is connected to. i.e. only a mainnet address is valid for a mainnet node. Addresses may optionally include the 0x prefix |