MAINNET:
Loading...
TESTNET:
Loading...
/
onflow.org
Flow Playground

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

The Access Nodes hosted by DapperLabs are accessible at:

Current Mainnet

access-mainnet-beta.onflow.org:9000

Check the latest access node URL listed for Mainnet: flow-view-source.com/mainnet/status

We are still in the process of aggregating the past chain data but mainnet 5 to mainnet 1 spork data can be retrieved from the Access nodes mentioned here

Testnet

access.devnet.nodes.onflow.org:9000

Canarynet

access.canary.nodes.onflow.org:9000


Alchemy Access Nodes

Our partner, Alchemy is offering robust access node infrastructure in addition to free logging, monitoring, and more tooling via their dashboard to all builders on Flow. Read their documentation and sign up to get access to their tools. You can find support on their Discord server.

Note: You will need to configure an API key through Alchemy to use these access nodes.

Alchemy Testnet:

flow-testnet.g.alchemy.com:443

Alchemy Mainnet:

flow-mainnet.g.alchemy.com:443​


Ping

Ping will return a successful response if the Access API is ready and available.

rpc 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
message PingRequest {}
Response
message PingResponse {}

Block Headers

The following methods query information about block headers.

GetLatestBlockHeader

GetLatestBlockHeader gets the latest sealed or unsealed block header.

rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)
Request
message GetLatestBlockHeaderRequest {
  bool is_sealed
}
Response
message BlockHeaderResponse {
  flow.BlockHeader block
}

GetBlockHeaderByID

GetBlockHeaderByID gets a block header by ID.

rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)
Request
message GetBlockHeaderByIDRequest {
  bytes id
}
Response
message BlockHeaderResponse {
  flow.BlockHeader block
}

GetBlockHeaderByHeight

GetBlockHeaderByHeight gets a block header by height.

rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)
Request
message GetBlockHeaderByHeightRequest {
  uint64 height
}
Response
message BlockHeaderResponse {
  flow.BlockHeader block
}

Blocks

The following methods query information about full blocks.

GetLatestBlock

GetLatestBlock gets the full payload of the latest sealed or unsealed block.

rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)
Request
message GetLatestBlockRequest {
  bool is_sealed
}
Response
message BlockResponse {
  flow.Block block
}

GetBlockByID

GetBlockByID gets a full block by ID.

rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)
Request
message GetBlockByIDRequest {
  bytes id
}
Response
message BlockResponse {
  flow.Block block
}

GetBlockByHeight

GetBlockByHeight gets a full block by height.

rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)
Request
message GetBlockByHeightRequest {
  uint64 height
}
Response
message BlockResponse {
  flow.Block block
}

Collections

The following methods query information about collections.

GetCollectionByID

GetCollectionByID gets a collection by ID.

rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)
Request
message GetCollectionByIDRequest {
  bytes id
}
Response
message CollectionResponse {
  flow.Collection collection
}

Transactions

The following methods can be used to submit transactions and fetch their results.

SendTransaction

SendTransaction submits a transaction to the network.

rpc 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.

message SendTransactionRequest {
  flow.Transaction transaction
}
Response

SendTransactionResponse message contains the ID of the submitted transaction.

message SendTransactionResponse {
  bytes id
}

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.

rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)
Request

GetTransactionRequest contains the ID of the transaction that is being queried.

message GetTransactionRequest {
  bytes id
}
Response

TransactionResponse contains the basic information about a transaction, but does not include post-execution results.

message TransactionResponse {
  flow.Transaction transaction
}

GetTransactionResult

GetTransactionResult gets the execution result of a transaction.

rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)
Request
message GetTransactionRequest {
  bytes id
}
Response
message TransactionResultResponse {
  flow.TransactionStatus status
  uint32 status_code
  string error_message
  repeated flow.Event events
}

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.

rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)
Request
message GetAccountRequest {
  bytes address
}
Response
message GetAccountResponse {
  Account account
}

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.

rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)
Request
message GetAccountAtLatestBlockRequest {
  bytes address
}
Response
message AccountResponse {
  Account account
}

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.

rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)
Request
message GetAccountAtBlockHeightRequest {
  bytes address
  uint64 block_height
}
Response
message AccountResponse {
  Account account
}

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.

rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)

This method is a shortcut for the following:

header = GetLatestBlockHeader()
value = ExecuteScriptAtBlockID(header.ID, script)
Request
message ExecuteScriptAtLatestBlockRequest {
  bytes script
}
Response
message ExecuteScriptResponse {
  bytes value
}

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.

rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)
Request
message ExecuteScriptAtBlockIDRequest {
  bytes block_id
  bytes script
}
Response
message ExecuteScriptResponse {
  bytes value
}

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.

rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)
Request
message ExecuteScriptAtBlockHeightRequest {
  uint64 block_height
  bytes script
}
Response
message ExecuteScriptResponse {
  bytes value
}

Events

The following methods can be used to query for on-chain events.

GetEventsForHeightRange

GetEventsForHeightRange retrieves events emitted within the specified block range.

rpc 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
message GetEventsForHeightRangeRequest {
  string type
  uint64 start_height = 2;
  uint64 end_height = 3;
}
Response
message EventsResponse {
  message Result {
    bytes block_id = 1;
    uint64 block_height = 2;
    repeated entities.Event events = 3;
    google.protobuf.Timestamp block_timestamp = 4;
  }
  repeated Result results = 1;
}

GetEventsForBlockIDs

GetEventsForBlockIDs retrieves events for the specified block IDs and event type.

rpc 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
message GetEventsForBlockIDsRequest {
  string type = 1;
  repeated bytes block_ids = 2;
}
Response
message EventsResponse {
  message Result {
    bytes block_id = 1;
    uint64 block_height = 2;
    repeated entities.Event events = 3;
    google.protobuf.Timestamp block_timestamp = 4;
  }
  repeated Result results = 1;
}

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.

rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)
Request
message GetNetworkParametersRequest {}
Response
message GetNetworkParametersResponse {
  string chain_id = 1;
}
FieldDescription
chain_idChain 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.

rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);
Request
message GetLatestProtocolStateSnapshotRequest {}
Response
message ProtocolStateSnapshotResponse {
  bytes serializedSnapshot = 1;
}

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.

rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);
Request
message GetExecutionResultForBlockIDRequest {
  bytes block_id = 1;
}
Response
message ExecutionResultForBlockIDResponse {
  flow.ExecutionResult execution_result = 1;
}

Entities

Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.

Block

message Block {
  bytes id
  bytes parent_id
  uint64 height
  google.protobuf.Timestamp timestamp
  repeated CollectionGuarantee collection_guarantees
  repeated BlockSeal block_seals
  repeated bytes signatures
}
FieldDescription
idSHA3-256 hash of the entire block payload
heightHeight of the block in the chain
parent_idID of the previous block in the chain
timestampTimestamp 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_guaranteesList of collection guarantees
block_sealsList of block seals
signaturesBLS 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.

message BlockHeader {
  bytes id
  bytes parent_id
  uint64 height
}
FieldDescription
idSHA3-256 hash of the entire block payload
parent_idID of the previous block in the chain
heightHeight 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.

message BlockSeal {
  bytes block_id
  bytes execution_receipt_id
  repeated bytes execution_receipt_signatures
  repeated bytes result_approval_signatures
}
FieldDescription
block_idID of the block being sealed
executionreceiptidID execution receipt being sealed
executionreceiptsignaturesBLS signatures of verification nodes on the execution receipt contents
resultapprovalsignaturesBLS signatures of verification nodes on the result approval contents

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.

message Collection {
  bytes id
  repeated bytes transaction_ids
}
FieldDescription
idSHA3-256 hash of the collection contents
transaction_idsOrdered 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.

message CollectionGuarantee {
  bytes collection_id
  repeated bytes signatures
}
FieldDescription
collection_idSHA3-256 hash of the collection contents
signaturesBLS signatures of the collection nodes guaranteeing the collection

Transaction

A transaction represents a unit of computation that is submitted to the Flow network.

message Transaction {
  bytes script
  repeated bytes arguments
  bytes reference_block_id
  uint64 gas_limit
  TransactionProposalKey proposal_key
  bytes payer
  repeated bytes authorizers
  repeated TransactionSignature payload_signatures
  repeated TransactionSignature envelope_signatures
}

message TransactionProposalKey {
  bytes address
  uint32 key_id
  uint64 sequence_number
}

message TransactionSignature {
  bytes address
  uint32 key_id
  bytes signature
}
FieldDescription
scriptRaw source code for a Cadence script, encoded as UTF-8 bytes
argumentsArguments passed to the Cadence script, encoded as JSON-Cadence bytes
referenceblockidBlock ID used to determine transaction expiry
proposal_keyAccount key used to propose the transaction
payerAddress of the payer account
authorizersAddresses of the transaction authorizers
signaturesSignatures 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.

FieldDescription
addressAddress of proposer account
key_idID of proposal key on the proposal account
sequence_numberSequence number for the proposal key

Transaction Signature

FieldDescription
addressAddress of the account for this signature
key_idID of the account key
signatureRaw signature byte data

Transaction Status

enum TransactionStatus {
  UNKNOWN = 0;
  PENDING = 1;
  FINALIZED = 2;
  EXECUTED = 3;
  SEALED = 4;
  EXPIRED = 5;
}
ValueDescription
UNKNOWNThe transaction status is not known.
PENDINGThe transaction has been received by a collector but not yet finalized in a block.
FINALIZEDThe consensus nodes have finalized the block that the transaction is included in
EXECUTEDThe execution nodes have produced a result for the transaction
SEALEDThe verification nodes have verified the transaction (the block in which the transaction is) and the seal is included in the latest block
EXPIREDThe 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.

message Account {
  bytes address
  uint64 balance
  bytes code
  repeated AccountKey keys
  map<string, bytes> contracts
}
FieldDescription
addressA unique account identifier
balanceThe account balance
codeThe code deployed to this account (deprecated, use contracts instead)
keysA list of keys configured on this account
contractsA 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.

message AccountKey {
  uint32 id
  bytes public_key
  uint32 sign_algo
  uint32 hash_algo
  uint32 weight
  uint32 sequence_number
  bool revoked
}
FieldDescription
idIndex of the key within the account, used as a unique identifier
public_keyPublic key encoded as bytes
sign_algoSignature algorithm
hash_algoHash algorithm
weightWeight assigned to the key
sequence_numberSequence number for the key
revokedFlag 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.

message Event {
  string type
  bytes transaction_id
  uint32 transaction_index
  uint32 event_index
  bytes payload
}
FieldDescription
typeFully-qualified unique type identifier for the event
transaction_idID of the transaction the event was emitted from
transaction_indexZero-based index of the transaction within the block
event_indexZero-based index of the event within the transaction
payloadEvent fields encoded as JSON-Cadence values

Execution Result

Execution result for a particular block.

message ExecutionResult {
  bytes previous_result_id
  bytes block_id
  repeated Chunk chunks
  repeated ServiceEvent service_events
}
FieldDescription
previousresultidIdentifier of parent block execution result
block_idID of the block this execution result corresponds to
chunksZero or more chunks
service_eventsZero or more service events

Chunk

Chunk described execution information for given collection in a block

message Chunk {
  bytes start_state
  bytes event_collection
  bytes block_id
  uint64 total_computation_used
  uint64 number_of_transactions
  uint64 index
  bytes end_state
}
FieldDescription
start_stateState commitment at start of the chunk
event_collectionHash of events emitted by transactions in this chunk
block_idIdentifier of a block
totalcomputationusedTotal computation used by transactions in this chunk
numberoftransactionsNumber of transactions in a chunk
indexIndex of chunk inside a block (zero-based)
end_stateState commitment after executing chunk

Service Event

Special type of events emitted in system chunk used for controlling Flow system.

message ServiceEvent {
  string type;
  bytes payload;
}
FieldDescription
typeType of an event
payloadJSON-serialized content of an event
Edit on GitHub