Flow Access API

Alchemy x Flow
Website Dashboard Roadmap
Search…
👋
Welcome to Alchemy's Flow Docs!
Documentation
Flow Access API
Compute Units
Official Flow Documentation
Guides
Getting Started
Other Chains
Ethereum Docs
Crypto.org Docs
Flow Access API
All methods supported by the Flow Access API, implemented as a gRPC service.
👋 New to Alchemy? Get access for free here!
For more details and information about the Flow API, check out the official Flow documentation. 
New to gRPC? Check out this quick description here. 
Ping
ping
Returns a successful response if the Access API is ready and available. If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.
1
rpc Ping(PingRequest) returns (PingResponse)
Copied!
Request
1
message PingRequest {}
Copied!
Result
1
message PingResponse {}
Copied!
Block Headers
The following methods query information about block headers.​
GetLatestBlockHeader
Gets the latest sealed or unsealed block header.
1
rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)
Copied!
Request
1
message GetLatestBlockHeaderRequest {
2
  bool is_sealed
3
}
Copied!
Response
1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
}
Copied!
GetBlockHeaderByID
Gets a block header by ID
1
rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)
Copied!
Request
1
message GetBlockHeaderByIDRequest {
2
  bytes id
3
}
Copied!
Response
1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
}
Copied!
GetBlockHeaderByHeight
Gets a block header by height.
1
rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)
Copied!
Request
1
message GetBlockHeaderByHeightRequest {
2
  uint64 height
3
}
Copied!
Response
1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
}
Copied!
Blocks
The following methods query information about full blocks.
GetLatestBlock
Gets the full payload of the latest sealed or unsealed block.
1
rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)
Copied!
Request
1
message GetLatestBlockRequest {
2
  bool is_sealed
3
}
Copied!
Response
1
message BlockResponse {
2
  flow.Block block
3
}
Copied!
GetBlockByID
Gets a full  block by ID. 
1
rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)
Copied!
Request
1
message GetBlockByIDRequest {
2
  bytes id
3
}
Copied!
Response
1
message BlockResponse {
2
  flow.Block block
3
}
Copied!
GetBlockByHeight
Gets a full  block by height. 
1
rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)
Copied!
Request
1
message GetBlockByHeightRequest {
2
  uint64 height
3
}
Copied!
Response
1
message BlockResponse {
2
  flow.Block block
3
}
Copied!
Collections
he following methods query information about collections.
GetCollectionByID
Gets a collection by ID. 
1
rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)
Copied!
Request
1
message GetCollectionByIDRequest {
2
  bytes id
3
}
Copied!
Response
1
message CollectionResponse {
2
  flow.Collection collection
3
}
Copied!
Transactions
The following methods can be used to submit transactions and fetch their results.
SendTransaction
Submits a transaction to the network, and 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.
1
rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse)
Copied!
Request
SendTransactionRequest message contains the transaction that is being request to be executed.
1
message SendTransactionRequest {
2
  flow.Transaction transaction
3
}
Copied!
Response
SendTransactionResponse message contains the ID of the submitted transaction.
1
message SendTransactionResponse {
2
  bytes id
3
}
Copied!
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.
1
rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)
Copied!
Request
GetTransactionRequest contains the ID of the transaction that is being queried.
1
message GetTransactionRequest {
2
  bytes id
3
}
Copied!
Response
TransactionResponse contains the basic information about a transaction, but does not include post-execution results.
1
message TransactionResponse {
2
  flow.Transaction transaction
3
}
Copied!
GetTransactionResult
Gets the execution result of a transaction.
1
rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)
Copied!
Request
1
message GetTransactionRequest {
2
  bytes id
3
}
Copied!
Response
1
message TransactionResultResponse {
2
  flow.TransactionStatus status
3
  uint32 status_code
4
  string error_message
5
  repeated flow.Event events
6
}
Copied!
Accounts
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.
1
rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)
Copied!
Request
1
message GetAccountRequest {
2
  bytes address
3
}
Copied!
Response
1
message GetAccountResponse {
2
  Account account
3
}
Copied!
GetAccountAtLatestBlock
Gets an account by address at the latest sealed block.
The access node queries an execution node for the account details, which are stored as part of the sealed execution state.
1
rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)
Copied!
Request
1
message GetAccountAtLatestBlockRequest {
2
  bytes address
3
}
Copied!
Response
1
message AccountResponse {
2
  Account account
3
}
Copied!
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.
1
rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)
Copied!
Request
1
message GetAccountAtBlockHeightRequest {
2
  bytes address
3
  uint64 block_height
4
}
Copied!
Response
1
message AccountResponse {
2
  Account account
3
}
Copied!
Scripts
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.
1
rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)
Copied!
This method is a shortcut for the following:
1
header = GetLatestBlockHeader()
2
value = ExecuteScriptAtBlockID(header.ID, script)
Copied!
Request
1
message ExecuteScriptAtLatestBlockRequest {
2
  bytes script
3
}
Copied!
Response
1
message ExecuteScriptResponse {
2
  bytes value
3
}
Copied!
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.
1
rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)
Copied!
Request
1
message ExecuteScriptAtBlockIDRequest {
2
  bytes block_id
3
  bytes script
4
}
Copied!
Response
1
message ExecuteScriptResponse {
2
  bytes value
3
}
Copied!
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.
1
rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)
Copied!
Request
1
message ExecuteScriptAtBlockHeightRequest {
2
  uint64 block_height
3
  bytes script
4
}
Copied!
Response
1
message ExecuteScriptResponse {
2
  bytes value
3
}
Copied!
Events
The following methods can be used to query for on-chain events.
GetEventsForHeightRange
Retrieves events emitted within the specified block range.
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.
1
rpc GetEventsForHeightRange(GetEventsForHeightRangeRequest) returns (GetEventsForHeightRangeResponse)
Copied!
Request
1
message GetEventsForHeightRangeRequest {
2
  string type
3
  uint64 start_height = 2;
4
  uint64 end_height = 3;
5
}
Copied!
Response
1
message EventsResponse {
2
  message Result {
3
    bytes block_id = 1;
4
    uint64 block_height = 2;
5
    repeated entities.Event events = 3;
6
    google.protobuf.Timestamp block_timestamp = 4;
7
  }
8
  repeated Result results = 1;
9
}
Copied!
GetEventsForBlockIDs
Retrieves events for the specified block IDs and event type.
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.
1
rpc GetEventsForBlockIDs(GetEventsForBlockIDsRequest) returns (GetEventsForBlockIDsResponse)
Copied!
Request
1
message GetEventsForBlockIDsRequest {
2
  string type = 1;
3
  repeated bytes block_ids = 2;
4
}
Copied!
Response
1
message EventsResponse {
2
  message Result {
3
    bytes block_id = 1;
4
    uint64 block_height = 2;
5
    repeated entities.Event events = 3;
6
    google.protobuf.Timestamp block_timestamp = 4;
7
  }
8
  repeated Result results = 1;
9
}
Copied!
Network Parameters
Network parameters provide information about the Flow network. Currently, it only includes the chain ID. 
The following methods can be used to query for network parameters.
GetNetworkParameters
Retrieves the network parameters.
1
rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)
Copied!
Request
1
message GetNetworkParametersRequest {}
Copied!
Response
1
mmessage GetNetworkParametersResponse {
2
  string chain_id = 1;
3
}
Copied!
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
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.
1
rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);
Copied!
Request
1
message GetLatestProtocolStateSnapshotRequest {}
Copied!
Response
1
message ProtocolStateSnapshotResponse {
2
  bytes serializedSnapshot = 1;
3
}
Copied!
Entities 
Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.
Block
1
message Block {
2
  bytes id
3
  bytes parent_id
4
  uint64 height
5
  google.protobuf.Timestamp timestamp
6
  repeated CollectionGuarantee collection_guarantees
7
  repeated BlockSeal block_seals
8
  repeated bytes signatures
9
}
Copied!
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
Block Header
A block header is a summary of a block and contains only the block ID, height, and parent block ID.
1
message BlockHeader {
2
  bytes id
3
  bytes parent_id
4
  uint64 height
5
}
Copied!
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.
1
message BlockSeal {
2
  bytes block_id
3
  bytes execution_receipt_id
4
  repeated bytes execution_receipt_signatures
5
  repeated bytes result_approval_signatures
6
}
Copied!
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
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.
1
message Collection {
2
  bytes id
3
  repeated bytes transaction_ids
4
}
Copied!
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.
1
message CollectionGuarantee {
2
  bytes collection_id
3
  repeated bytes signatures
4
}
Copied!
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.
NOTE: For more info on transaction signing check out this guide.
1
message Transaction {
2
  bytes script
3
  repeated bytes arguments
4
  bytes reference_block_id
5
  uint64 gas_limit
6
  TransactionProposalKey proposal_key
7
  bytes payer
8
  repeated bytes authorizers
9
  repeated TransactionSignature payload_signatures
10
  repeated TransactionSignature envelope_signatures
11
}
12
​
13
message TransactionProposalKey {
14
  bytes address
15
  uint32 key_id
16
  uint64 sequence_number
17
}
18
​
19
message TransactionSignature {
20
  bytes address
21
  uint32 key_id
22
  bytes signature
23
}
Copied!
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
referenceblockid
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
Transaction 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
1
enum TransactionStatus {
2
  UNKNOWN = 0;
3
  PENDING = 1;
4
  FINALIZED = 2;
5
  EXECUTED = 3;
6
  SEALED = 4;
7
  EXPIRED = 5;
8
}
Copied!
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.
1
message Account {
2
  bytes address
3
  uint64 balance
4
  bytes code
5
  repeated AccountKey keys
6
  map<string, bytes> contracts
7
}
Copied!
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.
1
message AccountKey {
2
  uint32 id
3
  bytes public_key
4
  uint32 sign_algo
5
  uint32 hash_algo
6
  uint32 weight
7
  uint32 sequence_number
8
  bool revoked
9
}
Copied!
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.
1
message Event {
2
  string type
3
  bytes transaction_id
4
  uint32 transaction_index
5
  uint32 event_index
6
  bytes payload
7
}
Copied!
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​
About gRPC:
Unlike REST APIs, which normally use JSON, gRPC utilizes protocol buffers to encode data, allowing it to hold more compressed data compared to JSON’s text-based storage format.  As a binary transfer format, protocol buffers transmit data as a binary which vastly improve transmission speed and save network bandwidth.  
In addition, JSON primiarly uses HTTP whereas gRPC was designed for HTTP/2 allowing for multiplexing of multiple calls over a single TCP connection.  As a language-agnostic API, gRPC also allows users to more simply generate client libraries across its supported programming languages.  
While protocol buffers do offer a time, space, and conversion efficiency, Protobuf files and data are not as human-readable as JSON or XML and have less generality, with a smaller developer community compared to other RPCs.
Ultimately, gRPC is perfectly suited as a last mile solution for distributed computing and microservice architectures like the Flow API.
For more information about gRPC services and quick start tutorials, refer to official documentation. 
Welcome to Alchemy's Flow Docs!
Next - Documentation
Compute Units
Last modified 3mo ago