👋 New to Alchemy? Get access for free 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.

rpc Ping(PingRequest) returns (PingResponse)

Request

message PingRequest {}

Result

message PingResponse {}

Block Headers

The following methods query information about block headers.​

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

Gets a block header by ID

rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)

Request

message GetBlockHeaderByIDRequest {
  bytes id
}

Response

message BlockHeaderResponse {
  flow.BlockHeader block
}

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

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

Gets a full block by ID.

rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)

Request

message GetBlockByIDRequest {
  bytes id
}

Response

message BlockResponse {
  flow.Block block
}

GetBlockByHeight

Gets a full block by height.

rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)

Request

message GetBlockByHeightRequest {
  uint64 height
}

Response

message BlockResponse {
  flow.Block block
}

Collections

he following methods query information about collections.

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

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.

rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse)

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

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

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

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

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.

rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)

Request

message GetAccountAtLatestBlockRequest {
  bytes address
}

Response

message AccountResponse {
  Account account
}

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

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

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

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

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.

rpc GetEventsForHeightRange(GetEventsForHeightRangeRequest) returns (GetEventsForHeightRangeResponse)

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

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.

rpc GetEventsForBlockIDs(GetEventsForBlockIDsRequest) returns (GetEventsForBlockIDsResponse)

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 methods can be used to query for network parameters.

GetNetworkParameters

Retrieves the network parameters.

rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)

Request

message GetNetworkParametersRequest {}

Response

mmessage GetNetworkParametersResponse {
  string chain_id = 1;
}

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.

rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);

Request

message GetLatestProtocolStateSnapshotRequest {}

Response

message ProtocolStateSnapshotResponse {
  bytes serializedSnapshot = 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
}

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
}

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
}

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
}

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
}

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
}

Transaction Proposal Key

The proposal key is used to specify a sequence number for the transaction. Sequence numbers are covered in more detail here.

Transaction Signature

Transaction Status

enum TransactionStatus {
  UNKNOWN = 0;
  PENDING = 1;
  FINALIZED = 2;
  EXECUTED = 3;
  SEALED = 4;
  EXPIRED = 5;
}

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
}

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
}

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
}

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.