Flow Rest API, RPC & gRPC (Access API)

With QuickNode, you get access to our global network which always routes your API requests to the nearest available location, ensuring low latency and fastest speeds.

Note:

The QuickNode Flow documentation constantly evolves as the chain undergoes upgrades and changes. We highly recommend cross-referencing with the Flow Documentation for the latest updates.

Overview

At QuickNode, we are currently running Flow endpoints. In aggregate, we serve 100s of billions of requests every month. To make it easier for developers to integrate with QuickNode, we've created this documentation that shows how to make API requests using cURL, JavaScript, Python, go, Ruby and any applicable Web3 SDKs. QuickNode-supported Flow APIs include:

• Flow REST API
• Flow gRPC (Access API)
• Ethereum JSON-RPC API
• Debug API

Note

Please note that the Ethereum JSON-RPC API is currently in Beta.

Flow Network Support

Network	WSS	HTTPS
TESTNET	✅	✅
MAINNET	✅	✅

Making Flow REST API Requests

In REST API documentation, you will see example requests made with various programming languages for each supported Flow method. This section will explain how to execute each one of them on your machine.

cURL

Most *nix based systems have cURL support out of the box. cURL is a command line tool and library for transferring data with URLs. Check if you have it by running the following:

curl -h

Python

To run our Python code examples, you'll need to have Python installed as well as the requests package. You can install this package with the following command:

python -m pip install requests

JavaScript

To run our JavaScript code examples, you'll need to have Node v18 and up installed. You can follow this official document to install the latest, stable version of Node globally. Check if you have it by running the following:

node -v

Ruby

To run our Ruby code examples, you'll need to have Ruby installed. You can follow this official installation document for more information. Check if you have it by running the following:

ruby -v

Making Flow Ethereum JSON API Requests

Along with the programming languages mentioned above, you can also use the Web3 SDKs and libraries listed below to send requests to Flow Ethereum JSON RPCs:

Web3.py

Web3.py is a Python library for interacting with Ethereum. If you'd like to use it, please be sure to install it like so:

pip install web3

Ethers.js

At QuickNode we prefer ethers.js as our JS library for interacting with JSON-RPCs when possible. Ethers aims to be a complete and compact library for interacting with the Ethereum Blockchain and its ecosystem. If you'd like to use it, please be sure to install it like so:

npm install --save ethers

Web3.js

There is also Web3.js - it's a collection of libraries that allow you to interact with a local or remote ethereum node using HTTP, IPC or WebSocket. If you'd like to use it, please be sure to install it like so:

npm install web3

Eth.rb

Eth.rb is a comprehensive ruby library that provides a high-level interface to interact with the Ethereum blockchain, making it easier for developers to manage accounts, send transactions, and work with smart contracts. If you'd like to use it, please be sure to install it like so:

gem install eth

Making Flow gRPC (Access API) Requests

In Access API documentation, you will see example requests made with go programming language for each supported Flow method. This section will explain how to execute each one of them on your machine.

go

Go is a statically-typed, compiled language known for its simplicity, efficiency, and strong concurrency support, making it well-suited for developing applications and services. You can follow this official installation document for more information. Check if you have it by running the following:

go version

Authentication Required for Flow gRPC (Access API)

To ensure secure access to Flow gRPC (Access API), users are required to authenticate themselves. This authentication process is necessary before utilizing any method. QuickNode endpoints consist of two crucial components: the endpoint name and the corresponding token. Users will need to use these two components to configure a gRPC client with authentication credentials before they make any method calls.

Authentication for the Flow gRPC (Access API) can be handled in two ways:

1. Basic Authentication
2. x-token Authentication

Throughout this documentation, we will call either the getAccessClientWithBasicAuth or getAccessClientWithXToken functions to demonstrate how to handle these different authentication mechanisms.

Basic Authentication

The getAccessClientWithBasicAuth function demonstrates how to handle authentication using Basic Authentication, which encodes the credentials as base64. Below is the code implementation of the getAccessClientWithBasicAuth function as well as the basicAuth implementation of RPC credentials:

import (
    "context"
    "crypto/tls"
    "encoding/base64"
    "fmt"
    "github.com/onflow/flow/protobuf/go/flow/access"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

func getAccessClientWithBasicAuth(endpoint, token string) (access.AccessAPIClient, error) {
    target := endpoint + ".flow-mainnet.quiknode.pro:8999" // for TLS connections
    client, err := grpc.Dial(target,
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithPerRPCCredentials(basicAuth{
            username: endpoint,
            password: token,
        }),
    )
    if err != nil {
        return nil, fmt.Errorf("Unable to dial endpoint %w", err)
    }
    return access.NewAccessAPIClient(client), nil
}

// basicAuth implements the credentials.PerRPCCredentials interface to support basic authentication for grpc requests.
type basicAuth struct {
    username string
    password string
}

func (b basicAuth) GetRequestMetadata(ctx context.Context, in ...string) (map[string]string, error) {
    auth := b.username + ":" + b.password
    enc := base64.StdEncoding.EncodeToString([]byte(auth))
    return map[string]string{"authorization": "Basic " + enc}, nil
}

func (basicAuth) RequireTransportSecurity() bool {
    return false
}

The getAccessClientWithBasicAuth function configures a gRPC client with the necessary security options and establishes a connection to the specified endpoint on port 8999. It takes the endpoint name and token as input parameters and returns an instance of the AccessAPIClient interface, which you can use to make authenticated API calls.

client, err := getAccessClientWithBasicAuth("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("err: %v", err)
}

x-token Authentication

The getAccessClientWithXToken function demonstrates how to handle authentication using an x-token. This method attaches the token to the x-token header of each request.

import (
    "context"
    "crypto/tls"
    "fmt"
    "github.com/onflow/flow/protobuf/go/flow/access"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
)

func getAccessClientWithXToken(endpoint, token string) (access.AccessAPIClient, error) {
    target := endpoint + ".flow-mainnet.quiknode.pro:8999" // for TLS connections
    client, err := grpc.Dial(target,
        grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
        grpc.WithPerRPCCredentials(auth{
            token: token,
        }),
    )
    if err != nil {
        return nil, fmt.Errorf("Unable to dial endpoint %w", err)
    }
    return access.NewAccessAPIClient(client), nil
}

// auth implements the credentials.PerRPCCredentials interface to support x-token authentication for grpc requests.
type auth struct {
    token string
}

func (a *auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
    return map[string]string{
        "x-token": a.token,
    }, nil
}

func (auth) RequireTransportSecurity() bool {
    return false
}

This method configures a gRPC client similarly to the basic authentication example, but it attaches the authentication token in the x-token header. Here's how you can use this function to make API calls:

client, err := getAccessClientWithXToken("ENDPOINT_NAME", "TOKEN")
if err != nil {
    log.Fatalf("err: %v", err)
}

API Credits

Usage in our pricing plans is measured in API Credits. To learn more about the API Credits for Flow, please visit this page.

Endpoint Rate Limits

To ensure fair usage and service stability, we apply the following rate limits on requests to our public and paid access endpoints:

Service Category	Public Rate Limit	Paid Rate Limit	Custom Rate Limit
SendTransaction	50 requests/second	As per the chosen plan	Contact Us
ExecuteScript Calls (Includes ExecuteScriptAtLastestBlock, ExecuteScriptAtBlockID, and ExecuteScriptAtBlockHeight)	5 requests/second	As per the chosen plan	Contact Us
GetEvents	30 requests/second	As per the chosen plan	Contact Us
Other Get Requests (e.g., GetBlock, GetCollection, etc.)	100 requests/second	As per the chosen plan	Contact Us

Please design your applications to respect these limits. Contact us if you have questions or need adjustments to these limits.

Endpoint Authentication Options

Note:

Please note that setting JWT (JSON Web Tokens), configuring all whitelist options, and changing any rate limits beyond credits per second are only available to users on the Growth plan and higher. Users on the Free or Starter plans can only change their requests per second rate limit or add, use, and delete an authentication token. Visit our pricing page for more information.

Token Authentication

By default, all endpoints created on QuickNode are protected by a token in the URL which looks something like this:

http://sample-endpoint-name.network.quiknode.pro/token-goes-here/

Approved Referrer List

For endpoints on the shared network, you are able to add a list of approved referrers. This requires any HTTP request to send a REFERRER header or any WebSocket request to send an ORIGIN header populated with one of the referrers you entered into our user panel.

Disabling Token Authentication

You can also disable the token authentication completely in your security settings for a given endpoint. This will allow anyone to make requests to the endpoint without the token.

JWT (JSON Web Tokens)

For additional security, you can also enable JWT for each of your deployed endpoints. JWT allows for stateless authentication between you and your endpoint. Learn how to use JWT with QuickNode in this step-by-step guide.

Multiple Authentication Tokens

Create multiple authentication tokens for each of your deployed endpoints. This allows you to revoke any tokens that may be comprised, without needing to restart your non-compromised endpoint.

To roll an individual authentication token, create an additional token and then delete the previous token. Learn more about multiple authentication tokens in this QuickNode guide.

Secure Your QuickNode Flow Endpoint

Enhance the security of your QuickNode RPC endpoints using the Endpoint Armor add-on. This add-on provides a secure URL for safer public and front-end usage, allowing you to control access, set rate limits, and restrict methods for heightened security and streamlined management. You can find more information about Endpoint Armor on this page.

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!