Getting Started

Quick guide to getting started and testing requests on Flow using Alchemy.

πŸ‘‹ New to Alchemy? Get access for free here!

NOTE: For specific questions about Flow, or to get help from the Flow team, check out the official Flow forum. For Alchemy related questions, post in the Flow Discord channel!

To use Alchemy with Flow, make sure your version of@onflow/fcl is at least 0.0.72

πŸ“‹ Overview

This guide assumes you already have an Alchemy Flow account and access to our Dashboard.

  1. πŸ”‘ Create an Alchemy Flow App

  2. ✍ Make requests

πŸ”‘ Create an Alchemy Flow App

To use Alchemy's products and connect to the Flow chain, you need an API key to authenticate your requests.

You can create API keys directly from the Alchemy Flow dashboard. To make a new key, click on the "Create App" button circled below:

Fill in the details under "Create App" to get your new key. There are two options for networks: Mainnet and Testnet (the API methods for both are the same), but they each have different gRPC endpoints:

At anytime, you can visit your dashboard homepage and view your app's keys by clicking the key icon on the far right. To make requests to flow via gRPC, you'll need both the gRPC endpoint and your unique api_key.

By clicking the β€˜View Details’ button, you can also see additional information, including your keys and recent requests.

✍ Make requests

Flow uses the gRPC protocol to make requests. There are several ways to make requests to the Flow blockchain, we've included instructions for two below.

If you're already building on Flow, or getting started on a specific project, we recommend starting with the Flow JavaScript SDK. If you're just looking for an easy way to sample requests and responses on Flow, you should get set up with Wombat.

Flow JavaScript SDK​

Already using the JavaScript SDK? Skip to step 3 to learn how to configure it to point to your Alchemy access node! The two main steps are:

  • Update your .env ACCESS_NODE to point to the Alchemy testnet endpoint: https://flow-testnet.g.alchemy.com​

  • Update your config.js file to include your Alchemy api_key:

fcl.config()
.put("grpc.metadata", {"api_key": "your-api-key"})

1. Get started with the Flow App Quickstart Guide​

This is a guide to understand the basics of how to build an app that interacts with the Flow blockchain using the Flow Javascript SDK (@onflow/fcl).

2. Create a new project and Install the Flow SDK​

Run the following commands on your command line to initialize a new FCL project. In the Flow docs, they use an example react for the example app but feel free to use and name your app whatever you want!

yarn create react-app my-app
cd my-app
yarn add @onflow/fcl @onflow/types

In this example, we used yarn to install @onflow/fclbut you can also use NPM.

  • @onflow/fcl is the latest build of FCL.

  • @onflow/types is a conversion layer between JavaScript and Cadence (Flow's native language). These are used when we want to pass JavaScript into Cadence transactions and scripts.

3. Configure your app + Alchemy access node

Generally it's a good idea to use environment variables for your configuration. This will allow us to change environments easily and Create React App comes with fairly good support for them out of the box. We will then need to pass these environment variables to FCL before it talks to anything else. To achieve this we will create two files (./.env.local, ./src/config.js) one to hold our env. variables locally, one to import those env. variables and supply them to FCL. Then we will import our FCL configuration as the very first thing in our application.

NOTE: Create React App requires all environment variables to be prefixed with REACT_APP_*

1. From your command line, create these two files:

touch .env.local # Create a .env.local file to store our environment variables
touch ./src/config.js # Create a ./src/config.js file where we will import our environment variables and configure FCL

Now that we have our files we should add in our environment variables and configure your Alchemy access node.

  • REACT_APP_ACCESS_NODE is your gRPC Endpoint in your Alchemy dashboard

2. Open .env.local and add the following to it:

# File: .env.local
​
# REACT_APP_ACCESS_NODE will be the Alchemy endpoint for our application
# REACT_APP_ALCHEMY_API_KEY is your unique Alchemy API key.
REACT_APP_ACCESS_NODE= https://flow-testnet.g.alchemy.com
REACT_APP_ALCHEMY_API_KEY= "your-api-key"
​
# WALLET_DISCOVERY will be the endpoint our application
# will use to discover available FCL compatible wallets.
REACT_APP_WALLET_DISCOVERY= https://fcl-discovery.onflow.org/testnet/authn
​
# CONTRACT_PROFILE will be the address that has the Profile
# smart contract we will be using in this guide.
REACT_APP_CONTRACT_PROFILE= 0xba1132bc08f82fe2

NOTE: If you're not following along with the Quickstart guide, the important part of this step is configuring your REACT_APP_ACCESS_NODE variable to point to the Alchemy endpoint and including your Alchemy API key as another variable:

REACT_APP_ACCESS_NODE = https://flow-testnet.g.alchemy.com
REACT_APP_ALCHEMY_API_KEY= "your-api-key"

These environment variables should now be available for us to use when we configure FCL, which we will do next.

3. Open ./src/config.js and add the following to it:

// File: ./src/config.js
import * as fcl from "@onflow/fcl"
​
fcl.config()
.put("grpc.metadata", {"api_key": process.env.REACT_APP_ALCHEMY_API_KEY})
.put("accessNode.api", process.env.REACT_APP_ACCESS_NODE) // Configure FCL's Alchemy Access Node
.put("challenge.handshake", process.env.REACT_APP_WALLET_DISCOVERY) // Configure FCL's Wallet Discovery mechanism
.put("0xProfile", process.env.REACT_APP_CONTRACT_PROFILE) // Will let us use `0xProfile` in our Cadence

4. Import the config.js file in your index.js

We now have a file that configures FCL but... it is not yet being invoked, so FCL still remains un-configured in our application. The final step of this section is to import this file as the first thing in our application. Open ./src/index.js and add the following as the first line:

// File: ./src/index.js
​
import "./config" // Imports environment variables and configures FCL
// Then the rest of ./src/index.js
import React from "react"
import ReactDOM from "react-dom"
​

Congrats!! You have configured FCL, which is the very first step in having a decentralized application built on Flow πŸŽ‰.

Check out the official Flow documentation for the next steps in the Quickstart guide (Authentication).

Flow Go SDK

To specifically configure the Flow Go SDK for Alchemy, refer to the following snippets:

import "github.com/onflow/flow-go-sdk/client"
​
// connect to an emulator running locally
c, err := client.New("flow-mainnet.g.alchemy.com:443")
if err != nil {
panic("failed to connect to emulator")
}

Original:

err = flowClient.SendTransaction(context.Background(), *tx)

Updated Example:

header := metadata.New(map[string]string{"api-key": "your-api-key"})
ctx := metadata.NewContext(context.Background(), header)
​
request := // construct a request for your service
response, err := flowClient.SendTransaction(ctx, *tx)

Using Wombat​

To test out your requests using Wombat, follow these instructions below!

The gRPC protocol doesn't allow command line requests like JSON-RPC, so in order to test our requests, we'll use Wombat, an open source gRPC client that allows you to make requests to Flow using your Alchemy endpoint.

NOTE: There are many gRPC clients out there besides Wombat, feel free to choose whichever you prefer!

1. Download & Open Wombat​

You can find the download instructions for MacOS, Linux, and Windows in the download section here.

If you're using MacOS and encounter an error opening Wombat, you may need to use Right Click -> Open to open the application successfully.

2. Make requests!

NOTE: You'll need to specify the port number when making Wombat requests, the endpoint should look like this:

https://flow-testnet.g.alchemy.com:443

Once you have Wombat installed, open it up and follow along with the video below.

Note that if your alchemy endpoint does not end in :443, you may need to add it after copying the URL into Wombat. You need the port number for server side endpoints, however, it's not needed for gRPC web connections (JavaScript SDK).

Want to learn more? Check out the Flow Playground for interactive tutorials that will teach you Cadence, Flow’s Resource-Oriented smart contract programming language.