Skip to main content
Version: Current

Flow Client Library (FCL) API Reference

For release updates, see the repo

Table of contents

Configuration

FCL has a mechanism that lets you configure various aspects of FCL. When you move from one instance of the Flow Blockchain to another (Local Emulator to Testnet to Mainnet) the only thing you should need to change for your FCL implementation is your configuration.

Setting Configuration Values​

Values only need to be set once. We recommend doing this once and as early in the life cycle as possible. To set a configuration value, the put method on the config instance needs to be called, the put method returns the config instance so they can be chained.

Alternatively, you can set the config by passing a JSON object directly.


_13
import * as fcl from "@onflow/fcl";
_13
_13
fcl
_13
.config() // returns the config instance
_13
.put("foo", "bar") // configures "foo" to be "bar"
_13
.put("baz", "buz"); // configures "baz" to be "buz"
_13
_13
// OR
_13
_13
fcl.config({
_13
foo: "bar",
_13
baz: "buz",
_13
});

Getting Configuration Values​

The config instance has an asynchronous get method. You can also pass it a fallback value.


_15
import * as fcl from "@onflow/fcl";
_15
_15
fcl.config().put("foo", "bar").put("woot", 5).put("rawr", 7);
_15
_15
const FALLBACK = 1;
_15
_15
async function addStuff() {
_15
var woot = await fcl.config().get("woot", FALLBACK); // will be 5 -- set in the config before
_15
var rawr = await fcl.config().get("rawr", FALLBACK); // will be 7 -- set in the config before
_15
var hmmm = await fcl.config().get("hmmm", FALLBACK); // will be 1 -- uses fallback because this isnt in the config
_15
_15
return woot + rawr + hmmm;
_15
}
_15
_15
addStuff().then((d) => console.log(d)); // 13 (5 + 7 + 1)

Common Configuration Keys​

NameExampleDescription
accessNode.api (required)https://rest-testnet.onflow.orgAPI URL for the Flow Blockchain Access Node you want to be communicating with. See all available access node endpoints here.
app.detail.titleCryptokittiesYour applications title, can be requested by wallets and other services.
app.detail.iconhttps://fcl-discovery.onflow.org/images/blocto.pngUrl for your applications icon, can be requested by wallets and other services.
challenge.handshakeDEPRECATEDUse discovery.wallet instead.
discovery.authn.endpointhttps://fcl-discovery.onflow.org/api/testnet/authnEndpoint for alternative configurable Wallet Discovery mechanism. Read more on discovery
discovery.wallet (required)https://fcl-discovery.onflow.org/testnet/authnPoints FCL at the Wallet or Wallet Discovery mechanism.
discovery.wallet.methodIFRAME/RPC, POP/RPC, TAB/RPC, HTTP/POST, or EXT/RPCDescribes which service strategy a wallet should use.
fcl.limit100Specifies fallback compute limit if not provided in transaction. Provided as integer.
flow.network (recommended)testnetUsed in conjunction with stored interactions and provides FCLCryptoContract address for testnet and mainnet. Possible values: local, canarynet, testnet, mainnet.
## Using Contracts in Scripts and Transactions

Address Replacement​

Configuration keys that start with 0x will be replaced in FCL scripts and transactions, this allows you to write your script or transaction Cadence code once and not have to change it when you point your application at a difference instance of the Flow Blockchain.


_24
import * as fcl from "@onflow/fcl"
_24
_24
fcl.config()
_24
.put("0xFungibleToken", "0xf233dcee88fe0abe")
_24
_24
async function myScript () {
_24
return fcl.send([
_24
fcl.script`
_24
import FungibleToken from 0xFungibleToken // will be replaced with 0xf233dcee88fe0abe because of the configuration
_24
_24
pub fun main() { /* Rest of the script goes here */ }
_24
`
_24
]).then(fcl.decode)
_24
}
_24
_24
async function myTransaction () {
_24
return fcl.send([
_24
fcl.transaction`
_24
import FungibleToken from 0xFungibleToken // will be replaced with 0xf233dcee88fe0abe because of the configuration
_24
_24
transaction { /* Rest of the transaction goes here */ }
_24
`
_24
]).then(fcl.decode)
_24
}

Example​


_10
import * as fcl from "@onflow/fcl"
_10
_10
fcl.config()
_10
.put("flow.network", "testnet")
_10
.put("accessNode.api", "https://rest-testnet.onflow.org")
_10
.put("discovery.wallet", "https://fcl-discovery.onflow.org/testnet/authn")
_10
.put("app.detail.title", "Test Harness")
_10
.put("app.detail.icon", "https://i.imgur.com/r23Zhvu.png")
_10
.put("service.OpenID.scopes", "email email_verified name zoneinfo")
_10
.put("0xFlowToken", "0x7e60df042a9c0868")

Using Flow.json​

A simpler way to import contracts in scripts and transactions is to use the config.load method to ingest your contracts from your flow.json file. This keeps the import syntax unified across tools and lets FCL figure out which address to use for what network based on the network provided in config. To use config.load you must first import your flow.json file and then pass it to config.load as a parameter.


_10
import { config } from '@onflow/fcl'
_10
import flowJSON from '../flow.json'
_10
_10
config({
_10
'flow.network': 'testnet',
_10
'accessNode.api': 'https://rest-testnet.onflow.org',
_10
'discovery.wallet': `https://fcl-discovery.onflow.org/testnet/authn`,
_10
}).load({ flowJSON })

Let's say your flow.json file looks like this:


_10
{
_10
"contracts": {
_10
"HelloWorld": "cadence/contracts/HelloWorld.cdc"
_10
}
_10
}

Then in your scripts and transactions, all you have to do is:


_10
import "HelloWorld"

FCL will automatically replace the contract name with the address for the network you are using.

Note: never put private keys in your flow.json. You should use the key/location syntax to separate your keys into a separate git ignored file.

Wallet Interactions

These methods allows dapps to interact with FCL compatible wallets in order to authenticate the user and authorize transactions on their behalf.

⚠️These methods are async.

Methods​

authenticate​

⚠️This method can only be used in web browsers.

Calling this method will authenticate the current user via any wallet that supports FCL. Once called, FCL will initiate communication with the configured discovery.wallet endpoint which lets the user select a wallet to authenticate with. Once the wallet provider has authenticated the user, FCL will set the values on the current user object for future use and authorization.

Note​

⚠️discovery.wallet value must be set in the configuration before calling this method. See FCL Configuration.

📣 The default discovery endpoint will open an iframe overlay to let the user choose a supported wallet.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
fcl
_10
.config()
_10
.put("accessNode.api", "https://rest-testnet.onflow.org")
_10
.put("discovery.wallet", "https://fcl-discovery.onflow.org/testnet/authn");
_10
// anywhere on the page
_10
fcl.authenticate();

Note​

⚠️ authenticate can also take a service returned from discovery with fcl.authenticate({ service }).

unauthenticate​

⚠️This method can only be used in web browsers.

Logs out the current user and sets the values on the current user object to null.

Note​

⚠️The current user must be authenticated first.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
fcl.config().put("accessNode.api", "https://rest-testnet.onflow.org");
_10
// first authenticate to set current user
_10
fcl.authenticate();
_10
// ... somewhere else & sometime later
_10
fcl.unauthenticate();
_10
// fcl.currentUser.loggedIn === null

reauthenticate​

⚠️This method can only be used in web browsers.

A convenience method that calls fcl.unauthenticate() and then fcl.authenticate() for the current user.

Note​

⚠️The current user must be authenticated first.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
// first authenticate to set current user
_10
fcl.authenticate();
_10
// ... somewhere else & sometime later
_10
fcl.reauthenticate();
_10
// logs out user and opens up login/sign-up flow

signUp​

⚠️This method can only be used in web browsers.

A convenience method that calls and is equivalent to fcl.authenticate().

logIn​

⚠️This method can only be used in web browsers.

A convenience method that calls and is equivalent to fcl.authenticate().

authz​

A convenience method that produces the needed authorization details for the current user to submit transactions to Flow. It defines a signing function that connects to a user's wallet provider to produce signatures to submit transactions.

📣 You can replace this function with your own authorization function if needed.

Returns​

TypeDescription
AuthorizationObjectAn object containing the necessary details from the current user to authorize a transaction in any role.

Usage​

Note: The default values for proposer, payer, and authorizations are already fcl.authz so there is no need to include these parameters, it is shown only for example purposes. See more on signing roles.


_22
import * as fcl from "@onflow/fcl";
_22
// login somewhere before
_22
fcl.authenticate();
_22
// once logged in authz will produce values
_22
console.log(fcl.authz);
_22
// prints {addr, signingFunction, keyId, sequenceNum} from the current authenticated user.
_22
_22
const txId = await fcl.mutate({
_22
cadence: `
_22
import Profile from 0xba1132bc08f82fe2
_22
_22
transaction(name: String) {
_22
prepare(account: AuthAccount) {
_22
account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
_22
}
_22
}
_22
`,
_22
args: (arg, t) => [arg("myName", t.String)],
_22
proposer: fcl.authz, // optional - default is fcl.authz
_22
payer: fcl.authz, // optional - default is fcl.authz
_22
authorizations: [fcl.authz], // optional - default is [fcl.authz]
_22
});

Current User​

Holds the current user, if set, and offers a set of functions to manage the authentication and authorization of the user.

⚠️The following methods can only be used in web browsers.

Methods​

currentUser.subscribe​

The callback passed to subscribe will be called when the user authenticates and un-authenticates, making it easy to update the UI accordingly.

Arguments​

NameType
callbackfunctionThe callback will be called with the current user as the first argument when the current user is set or removed.

Usage​


_24
import React, { useState, useEffect } from "react";
_24
import * as fcl from "@onflow/fcl";
_24
_24
export function AuthCluster() {
_24
const [user, setUser] = useState({ loggedIn: null });
_24
useEffect(() => fcl.currentUser.subscribe(setUser), []); // sets the callback for FCL to use
_24
_24
if (user.loggedIn) {
_24
return (
_24
<div>
_24
<span>{user?.addr ?? "No Address"}</span>
_24
<button onClick={fcl.unauthenticate}>Log Out</button> {/* once logged out in setUser(user) will be called */}
_24
</div>
_24
);
_24
} else {
_24
return (
_24
<div>
_24
<button onClick={fcl.logIn}>Log In</button>{" "}
_24
{/* once logged in setUser(user) will be called */}
_24
<button onClick={fcl.signUp}>Sign Up</button> {/* once signed up, setUser(user) will be called */}
_24
</div>
_24
);
_24
}
_24
}

currentUser.snapshot​

Returns the current user object. This is the same object that is set and available on fcl.currentUser.subscribe(callback).

Usage​


_10
// returns the current user object
_10
const user = fcl.currentUser.snapshot();
_10
_10
// subscribes to the current user object and logs to console on changes
_10
fcl.currentUser.subscribe(console.log);

currentUser.authenticate​

Equivalent to fcl.authenticate.

currentUser.unauthenticate​

Equivalent to fcl.unauthenticate.

currentUser.authorization​

Equivalent to fcl.authz

currentUser.signUserMessage​

A method to use allowing the user to personally sign data via FCL Compatible Wallets/Services.

⚠️ This method requires the current user's wallet to support a signing service endpoint. Currently, only Blocto is compatible with this feature by default.

Arguments​

NameTypeDescription
messagestring (required)A hexadecimal string to be signed

Returns​

TypeDescription
ArrayAn Array of CompositeSignatures: signature

Usage​


_10
import * as fcl from "@onflow/fcl"
_10
_10
export const signMessage = async () => {
_10
const MSG = Buffer.from("FOO").toString("hex")
_10
try {
_10
return await currentUser.signUserMessage(MSG)
_10
} catch (error) {
_10
console.log(error)
_10
}
_10
}

Discovery​

discovery​

Discovery abstracts away code so that developers don't have to deal with the discovery of Flow compatible wallets, integration, or authentication. Using discovery from FCL allows dapps to list and authenticate with wallets while having full control over the UI. Common use cases for this are login or registration pages.

(Alternatively, if you don't need control over your UI you can continue to use the discovery.wallet config value documented in the Quickstart for the simplest configuration.)

⚠️The following methods can only be used in web browsers.

Note​

⚠️discovery.authn.endpoint value must be set in the configuration before calling this method. See FCL Configuration.

Suggested Configuration​

EnvironmentExample
Mainnethttps://fcl-discovery.onflow.org/api/authn
Testnethttps://fcl-discovery.onflow.org/api/testnet/authn

If the Discovery endpoint is set in config, then you can iterate through authn services and pass the chosen service to authenticate to authenticate a user.

Usage​


_21
import "./config"
_21
import { useState, useEffect } from "react"
_21
import * as fcl from "@onflow/fcl"
_21
_21
function Component() {
_21
const [wallets, setWallets] = useState([])
_21
useEffect(() => fcl.discovery.authn.subscribe(res => setWallets(res.results)), [])
_21
_21
return (
_21
<div>
_21
{wallets.map((wallet) => (
_21
<button
_21
key={wallet.provider.address}
_21
onClick={() => fcl.authenticate({ service: wallet })}
_21
>
_21
Login with {wallet.provider.name}
_21
</button>
_21
))}
_21
</div>
_21
)
_21
}

authn​

More Configuration​

By default, limited functionality services or services that require developer registration, like Ledger or Dapper Wallet, require apps to opt-in in order to display to users. To enable opt-in services in an application, use the discovery.authn.include property in your configuration with a value of an array of services you'd like your app to opt-in to displaying for users.


_10
_10
import { config } from "@onflow/fcl"
_10
_10
config({
_10
"discovery.authn.endpoint": "https://fcl-discovery.onflow.org/api/testnet/authn", // Endpoint set to Testnet
_10
"discovery.authn.include": ["0x9d2e44203cb13051"] // Ledger wallet address on Testnet set to be included
_10
})

Opt-In Wallet Addresses on Testnet and Mainnet

ServiceTestnetMainnet
Dapper Wallet0x82ec283f88a62e650xead892083b3e2c6c
Ledger0x9d2e44203cb130510xe5cd26afebe62781

For more details on wallets, view the service list here.

discovery.authn.snapshot()​

Return a list of authn services.

discovery.authn.subscribe(callback)​

The callback sent to subscribe will be called with a list of authn services.

On-chain Interactions

📣 These methods can be used in browsers and NodeJS.

These methods allows dapps to interact directly with the Flow blockchain via a set of functions that currently use the Access Node API.

Methods​

Query and Mutate Flow with Cadence​

If you want to run arbitrary Cadence scripts on the blockchain, these methods offer a convenient way to do so without having to build, send, and decode interactions.

query​

Allows you to submit scripts to query the blockchain.

Options​

Pass in the following as a single object with the following keys.All keys are optional unless otherwise stated.

KeyTypeDescription
cadencestring (required)A valid cadence script.
argsArgumentFunctionAny arguments to the script if needed should be supplied via a function that returns an array of arguments.
limitnumberCompute (Gas) limit for query. Read the documentation about computation cost for information about how computation cost is calculated on Flow.

Returns​

TypeDescription
anyA JSON representation of the response.

Usage​


_16
import * as fcl from "@onflow/fcl";
_16
_16
const result = await fcl.query({
_16
cadence: `
_16
pub fun main(a: Int, b: Int, addr: Address): Int {
_16
log(addr)
_16
return a + b
_16
}
_16
`,
_16
args: (arg, t) => [
_16
arg(7, t.Int), // a: Int
_16
arg(6, t.Int), // b: Int
_16
arg("0xba1132bc08f82fe2", t.Address), // addr: Address
_16
],
_16
});
_16
console.log(result); // 13

Examples​

mutate​

Allows you to submit transactions to the blockchain to potentially mutate the state.

⚠️When being used in the browser, fcl.mutate uses the built-in fcl.authz function to produce the authorization (signatures) for the current user. When calling this method from Node.js, you will need to supply your own custom authorization function.

Options​

Pass in the following as a single object with the following keys. All keys are optional unless otherwise stated.

KeyTypeDescription
cadencestring (required)A valid cadence transaction.
argsArgumentFunctionAny arguments to the script if needed should be supplied via a function that returns an array of arguments.
limitnumberCompute (Gas) limit for query. Read the documentation about computation cost for information about how computation cost is calculated on Flow.
proposerAuthorizationFunctionThe authorization function that returns a valid AuthorizationObject for the proposer role.

Returns​

TypeDescription
stringThe transaction ID.

Usage​


_16
import * as fcl from "@onflow/fcl";
_16
// login somewhere before
_16
fcl.authenticate();
_16
_16
const txId = await fcl.mutate({
_16
cadence: `
_16
import Profile from 0xba1132bc08f82fe2
_16
_16
transaction(name: String) {
_16
prepare(account: AuthAccount) {
_16
account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
_16
}
_16
}
_16
`,
_16
args: (arg, t) => [arg("myName", t.String)],
_16
});

Examples​

verifyUserSignatures (Deprecated)​

Use fcl.AppUtils.verifyUserSignatures

AppUtils​

AppUtils.verifyUserSignatures​

A method allowing applications to cryptographically verify a message was signed by a user's private key/s. This is typically used with the response from currentUser.signUserMessage.

Note​

⚠️ fcl.config.flow.network or options override is required to use this api. See FCL Configuration.

Arguments​

NameTypeDescription
messagestring (required)A hexadecimal string
compositeSignaturesArray (required)An Array of CompositeSignatures
optsObject (optional)opts.fclCryptoContract can be provided to override FCLCryptoContract address for local development

Returns​

TypeDescription
Booleantrue if verified or false

Usage​


_10
import * as fcl from "@onflow/fcl"
_10
_10
const isValid = await fcl.AppUtils.verifyUserSignatures(
_10
Buffer.from('FOO').toString("hex"),
_10
[{f_type: "CompositeSignature", f_vsn: "1.0.0", addr: "0x123", keyId: 0, signature: "abc123"}],
_10
{fclCryptoContract}
_10
)

Examples​

AppUtils.verifyAccountProof​

A method allowing applications to cryptographically prove that a user controls an on-chain account. During user authentication, some FCL compatible wallets will choose to support the FCL account-proof service. If a wallet chooses to support this service, and the user approves the signing of message data, they will return account-proof data and a signature(s) that can be used to prove a user controls an on-chain account. See proving-authentication documentaion for more details.

⚠️ fcl.config.flow.network or options override is required to use this api. See FCL Configuration.

Arguments​

NameTypeDescription
appIdentifierstring (required)A hexadecimal string
accountProofDataObject (required)Object with properties:
address: string - A Flow account address.
nonce: string - A random string in hexadecimal format (minimum 32 bytes in total, i.e 64 hex characters)
signatures: Object[] - An array of composite signatures to verify
optsObject (optional)opts.fclCryptoContract can be provided to overide FCLCryptoContract address for local development

Returns​

TypeDescription
Booleantrue if verified or false

Usage​


_13
import * as fcl from "@onflow/fcl"
_13
_13
const accountProofData = {
_13
address: "0x123",
_13
nonce: "F0123"
_13
signatures: [{f_type: "CompositeSignature", f_vsn: "1.0.0", addr: "0x123", keyId: 0, signature: "abc123"}],
_13
}
_13
_13
const isValid = await fcl.AppUtils.verifyAccountProof(
_13
"AwesomeAppId",
_13
accountProofData,
_13
{fclCryptoContract}
_13
)

Examples​

Query and mutate the blockchain with Builders​

In some cases, you may want to utilize pre-built interactions or build more complex interactions than what the fcl.query and fcl.mutate interface offer. To do this, FCL uses a pattern of building up an interaction with a combination of builders, resolving them, and sending them to the chain.

⚠️Recommendation: Unless you have a specific use case that require usage of these builders, you should be able to achieve most cases with fcl.query({...options} or fcl.mutate({...options})

send​

Sends arbitrary scripts, transactions, and requests to Flow.

This method consumes an array of builders that are to be resolved and sent. The builders required to be included in the array depend on the interaction that is being built.

Note​

⚠️Must be used in conjuction with fcl.decode(response) to get back correct keys and all values in JSON.

Arguments​

NameTypeDescription
builders[Builders]See builder functions.

Returns​

TypeDescription
ResponseObjectAn object containing the data returned from the chain. Should always be decoded with fcl.decode() to get back appropriate JSON keys and values.

Usage​


_18
import * as fcl from "@onflow/fcl";
_18
_18
// a script only needs to resolve the arguments to the script
_18
const response = await fcl.send([fcl.script`${script}`, fcl.args(args)]);
_18
// note: response values are encoded, call await fcl.decode(response) to get JSON
_18
_18
// a transaction requires multiple 'builders' that need to be resolved prior to being sent to the chain - such as setting the authorizations.
_18
const response = await fcl.send([
_18
fcl.transaction`
_18
${transaction}
_18
`,
_18
fcl.args(args),
_18
fcl.proposer(proposer),
_18
fcl.authorizations(authorizations),
_18
fcl.payer(payer),
_18
fcl.limit(9999),
_18
]);
_18
// note: response contains several values (Cad)

decode​

Decodes the response from fcl.send() into the appropriate JSON representation of any values returned from Cadence code.

Note​

📣 To define your own decoder, see tutorial.

Arguments​

NameTypeDescription
responseResponseObjectShould be the response returned from fcl.send([...])

Returns​

TypeDescription
anyA JSON representation of the raw string response depending on the cadence code executed.
The return value can be a single value and type or an object with multiple types.

Usage​


_19
import * as fcl from "@onflow/fcl";
_19
_19
// simple script to add 2 numbers
_19
const response = await fcl.send([
_19
fcl.script`
_19
pub fun main(int1: Int, int2: Int): Int {
_19
return int1 + int2
_19
}
_19
`,
_19
fcl.args([
_19
fcl.arg(1, fcl.t.Int),
_19
fcl.arg(2, fcl.t.Int)
_19
]),
_19
]);
_19
_19
const decoded = await fcl.decode(response);
_19
_19
assert(3 === decoded);
_19
assert(typeof decoded === "number");

Builders​

These methods fill out various portions of a transaction or script template in order to build, resolve, and send it to the blockchain. A valid populated template is referred to as an Interaction.

⚠️These methods must be used with fcl.send([...builders]).then(fcl.decode)

Query Builders​

getAccount​

A builder function that returns the interaction to get an account by address.

⚠️Consider using the pre-built interaction fcl.account(address) if you do not need to pair with any other builders.

Arguments​

NameTypeDescription
addressAddressAddress of the user account with or without a prefix (both formats are supported).

Returns after decoding​

TypeDescription
AccountObjectA JSON representation of a user account.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
// somewhere in an async function
_10
// fcl.account is the same as this function
_10
const getAccount = async (address) => {
_10
const account = await fcl.send([fcl.getAccount(address)]).then(fcl.decode);
_10
return account;
_10
};

getBlock​

A builder function that returns the interaction to get the latest block.

📣 Use with fcl.atBlockId() and fcl.atBlockHeight() when building the interaction to get information for older blocks.

⚠️Consider using the pre-built interaction fcl.latestBlock(isSealed) if you do not need to pair with any other builders.

Arguments​

NameTypeDefaultDescription
isSealedbooleanfalseIf the latest block should be sealed or not. See block states.

Returns after decoding​

TypeDescription
BlockObjectThe latest block if not used with any other builders.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const latestSealedBlock = await fcl
_10
.send([
_10
fcl.getBlock(true), // isSealed = true
_10
])
_10
.then(fcl.decode);

atBlockHeight​

A builder function that returns a partial interaction to a block at a specific height.

⚠️Use with other interactions like fcl.getBlock() to get a full interaction at the specified block height.

Arguments​

NameTypeDescription
blockHeightnumberThe height of the block to execute the interaction at.

Returns​

TypeDescription
Partial InteractionA partial interaction to be paired with another interaction such as fcl.getBlock() or fcl.getAccount().

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
await fcl.send([fcl.getBlock(), fcl.atBlockHeight(123)]).then(fcl.decode);

atBlockId​

A builder function that returns a partial interaction to a block at a specific block ID.

⚠️Use with other interactions like fcl.getBlock() to get a full interaction at the specified block ID.

Arguments​

NameTypeDescription
blockIdstringThe ID of the block to execute the interaction at.

Returns​

TypeDescription
Partial InteractionA partial interaction to be paired with another interaction such as fcl.getBlock() or fcl.getAccount().

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
await fcl.send([fcl.getBlock(), fcl.atBlockId("23232323232")]).then(fcl.decode);

getBlockHeader​

A builder function that returns the interaction to get a block header.

📣 Use with fcl.atBlockId() and fcl.atBlockHeight() when building the interaction to get information for older blocks.

Returns after decoding​

TypeDescription
BlockHeaderObjectThe latest block header if not used with any other builders.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const latestBlockHeader = await fcl
_10
.send([fcl.getBlockHeader()])
_10
.then(fcl.decode);

getEventsAtBlockHeightRange​

A builder function that returns all instances of a particular event (by name) within a height range.

⚠️The block range provided must be from the current spork.

⚠️The block range provided must be 250 blocks or lower per request.

Arguments​

NameTypeDescription
eventNameEventNameThe name of the event.
fromBlockHeightnumberThe height of the block to start looking for events (inclusive).
toBlockHeightnumberThe height of the block to stop looking for events (inclusive).

Returns after decoding​

TypeDescription
[EventObject]An array of events that matched the eventName.

Usage​


_11
import * as fcl from "@onflow/fcl";
_11
_11
const events = await fcl
_11
.send([
_11
fcl.getEventsAtBlockHeightRange(
_11
"A.7e60df042a9c0868.FlowToken.TokensWithdrawn",
_11
35580624,
_11
35580624
_11
),
_11
])
_11
.then(fcl.decode);

getEventsAtBlockIds​

A builder function that returns all instances of a particular event (by name) within a set of blocks, specified by block ids.

⚠️The block range provided must be from the current spork.

Arguments​

NameTypeDescription
eventNameEventNameThe name of the event.
blockIdsnumberThe ids of the blocks to scan for events.

Returns after decoding​

TypeDescription
[EventObject]An array of events that matched the eventName.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const events = await fcl
_10
.send([
_10
fcl.getEventsAtBlockIds("A.7e60df042a9c0868.FlowToken.TokensWithdrawn", [
_10
"c4f239d49e96d1e5fbcf1f31027a6e582e8c03fcd9954177b7723fdb03d938c7",
_10
"5dbaa85922eb194a3dc463c946cc01c866f2ff2b88f3e59e21c0d8d00113273f",
_10
]),
_10
])
_10
.then(fcl.decode);

getCollection​

A builder function that returns all a collection containing a list of transaction ids by its collection id.

⚠️The block range provided must be from the current spork. All events emitted during past sporks is current unavailable.

Arguments​

NameTypeDescription
collectionIDstringThe id of the collection.

Returns after decoding​

TypeDescription
CollectionObjectAn object with the id and a list of transactions within the requested collection.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const collection = await fcl
_10
.send([
_10
fcl.getCollection(
_10
"cccdb0c67d015dc7f6444e8f62a3244ed650215ed66b90603006c70c5ef1f6e5"
_10
),
_10
])
_10
.then(fcl.decode);

getTransactionStatus​

A builder function that returns the status of transaction in the form of a TransactionStatusObject.

⚠️The transactionID provided must be from the current spork.

📣 Considering subscribing to the transaction from fcl.tx(id) instead of calling this method directly.

Arguments​

NameTypeDescription
transactionIdstringThe transactionID returned when submitting a transaction. Example: 9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3

Returns after decoding​

Returns​

TypeDescription
TransactionStatusObjectObject representing the result/status of a transaction

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const status = await fcl
_10
.send([
_10
fcl.getTransactionStatus(
_10
"9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3"
_10
),
_10
])
_10
.then(fcl.decode);

getTransaction​

A builder function that returns a transaction object once decoded.

⚠️The transactionID provided must be from the current spork.

📣 Considering using fcl.tx(id).onceSealed() instead of calling this method directly.

Arguments​

NameTypeDescription
transactionIdstringThe transactionID returned when submitting a transaction. Example: 9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3

Returns after decoding​

Returns​

TypeDescription
TransactionObjectAn full transaction object containing a payload and signatures

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const tx = await fcl
_10
.send([
_10
fcl.getTransaction(
_10
"9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3"
_10
),
_10
])
_10
.then(fcl.decode);

getEvents (Deprecated)​

Use fcl.getEventsAtBlockHeightRange or fcl.getEventsAtBlockIds.

getLatestBlock (Deprecated)​

Use fcl.getBlock.

getBlockById (Deprecated)​

Use fcl.getBlock and fcl.atBlockId.

getBlockByHeight (Deprecated)​

Use fcl.getBlock and fcl.atBlockHeight.

Utility Builders​

These builders are used to compose interactions with other builders such as scripts and transactions.

⚠️Recommendation: Unless you have a specific use case that require usage of these builders, you should be able to achieve most cases with fcl.query({...options} or fcl.mutate({...options})

arg​

A utility builder to be used with fcl.args[...] to create FCL supported arguments for interactions.

Arguments​

NameTypeDescription
valueanyAny value that you are looking to pass to other builders.
typeFTypeA type supported by Flow.

Returns​

TypeDescription
ArgumentObjectHolds the value and type passed in.

Usage​


_15
import * as fcl from "@onflow/fcl";
_15
_15
await fcl
_15
.send([
_15
fcl.script`
_15
pub fun main(a: Int, b: Int): Int {
_15
return a + b
_15
}
_15
`,
_15
fcl.args([
_15
fcl.arg(5, fcl.t.Int), // a
_15
fcl.arg(4, fcl.t.Int), // b
_15
]),
_15
])
_15
.then(fcl.decode);

args​

A utility builder to be used with other builders to pass in arguments with a value and supported type.

Arguments​

NameTypeDescription
args[Argument Objects]An array of arguments that you are looking to pass to other builders.

Returns​

TypeDescription
Partial InteractionAn interaction that contains the arguments and types passed in. This alone is a partial and incomplete interaction.

Usage​


_15
import * as fcl from "@onflow/fcl";
_15
_15
await fcl
_15
.send([
_15
fcl.script`
_15
pub fun main(a: Int, b: Int): Int {
_15
return a + b
_15
}
_15
`,
_15
fcl.args([
_15
fcl.arg(5, fcl.t.Int), // a
_15
fcl.arg(4, fcl.t.Int), // b
_15
]),
_15
])
_15
.then(fcl.decode); // 9

Template Builders​

⚠️Recommended: The following functionality is simplified by fcl.query({...options} or fcl.mutate({...options}) and is reccomended to use over the functions below.

script​

A template builder to use a Cadence script for an interaction.

📣 Use with fcl.args(...) to pass in arguments dynamically.

Arguments​

NameTypeDescription
CODEstringShould be valid Cadence script.

Returns​

TypeDescription
InteractionAn interaction containing the code passed in.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const code = `
_10
pub fun main(): Int {
_10
return 5 + 4
_10
}
_10
`;
_10
const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);
_10
console.log(answer); // 9

transaction​

A template builder to use a Cadence transaction for an interaction.

⚠️Must be used with fcl.payer, fcl.proposer, fcl.authorizations to produce a valid interaction before sending to the chain.

📣 Use with fcl.args[...] to pass in arguments dynamically.

Arguments​

NameTypeDescription
CODEstringShould be valid a Cadence transaction.

Returns​

TypeDescription
Partial InteractionAn partial interaction containing the code passed in. Further builders are required to complete the interaction - see warning.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const code = `
_10
pub fun main(): Int {
_10
return 5 + 4
_10
}
_10
`;
_10
const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);
_10
console.log(answer); // 9

Pre-built Interactions​

These functions are abstracted short hand ways to skip the send and decode steps of sending an interaction to the chain. More pre-built interactions are coming soon.

account​

A pre-built interaction that returns the details of an account from their public address.

Arguments​

NameTypeDescription
addressAddressAddress of the user account with or without a prefix (both formats are supported).

Returns​

TypeDescription
AccountObjectA JSON representation of a user account.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
const account = await fcl.account("0x1d007d755706c469");

block​

A pre-built interaction that returns the latest block (optionally sealed or not), by id, or by height.

Arguments​

NameTypeDefaultDescription
sealedbooleanfalseIf the latest block should be sealed or not. See block states.
idstringID of block to get.
heightintHeight of block to get.

Returns​

TypeDescription
BlockObjectA JSON representation of a block.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
await fcl.block() // get latest finalized block
_10
await fcl.block({sealed: true}) // get latest sealed block
_10
await fcl.block({id: '0b1bdfa9ddaaf31d53c584f208313557d622d1fedee1586ffc38fb5400979faa'}) // get block by id
_10
await fcl.block({height: 56481953}) // get block by height

latestBlock (Deprecated)​

A pre-built interaction that returns the latest block (optionally sealed or not).

Arguments​

NameTypeDefaultDescription
isSealedbooleanfalseIf the latest block should be sealed or not. See block states.

Returns​

TypeDescription
BlockObjectA JSON representation of a block.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
const latestBlock = await fcl.latestBlock();

Transaction Status Utility​

tx​

A utility function that lets you set the transaction to get subsequent status updates (via polling) and the finalized result once available. ⚠️The poll rate is set at 2500ms and will update at that interval until transaction is sealed.

Arguments​

NameTypeDescription
transactionIdstringA valid transaction id.

Returns​

NameTypeDescription
snapshot()functionReturns the current state of the transaction.
subscribe(cb)functionCalls the cb passed in with the new transaction on a status change.
onceFinalized()functionProvides the transaction once status 2 is returned. See Tranasaction Statuses.
onceExecuted()functionProvides the transaction once status 3 is returned. See Tranasaction Statuses.
onceSealed()functionProvides the transaction once status 4 is returned. See Tranasaction Statuses.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
_10
const [txStatus, setTxStatus] = useState(null);
_10
useEffect(() => fcl.tx(txId).subscribe(setTxStatus));

Event Polling Utility​

events​

A utility function that lets you set the transaction to get subsequent status updates (via polling) and the finalized result once available. ⚠️The poll rate is set at 10000ms and will update at that interval for getting new events.

Note: ⚠️fcl.eventPollRate value could be set to change the polling rate of all events subcribers, check FCL Configuration for guide.

Arguments​

NameTypeDescription
eventNamestringA valid event name.

Returns​

NameTypeDescription
subscribe(cb)functionCalls the cb passed in with the new event.

Usage​


_10
import * as fcl from "@onflow/fcl";
_10
// in some react component
_10
fcl.events(eventName).subscribe((event) => {
_10
console.log(event)
_10
})

Examples​

Types, Interfaces, and Definitions

Builders​

Builders are modular functions that can be coupled together with fcl.send([...builders]) to create an Interaction. The builders needed to create an interaction depend on the script or transaction that is being sent.

Interaction​

An interaction is an object containing the information to perform an action on chain.This object is populated through builders and converted into the approriate access node API call. See the interaction object here. A 'partial' interaction is an interaction object that does not have sufficient information to the intended on-chain action. Multiple partial interactions (through builders) can be coupled to create a complete interaction.

CurrentUserObject​

KeyValue TypeDefaultDescription
addrAddressnullThe public address of the current user
cidstringnullAllows wallets to specify a content identifier for user metadata.
expiresAtnumbernullAllows wallets to specify a time-frame for a valid session.
f_typestring'USER'A type identifier used internally by FCL.
f_vsnstring'1.0.0'FCL protocol version.
loggedInbooleannullIf the user is logged in.
services[ServiceObject][]A list of trusted services that express ways of interacting with the current user's identity, including means to further discovery, authentication, authorization, or other kinds of interactions.

AuthorizationObject​

This type conforms to the interface required for FCL to authorize transaction on behalf o the current user.

KeyValue TypeDescription
addrAddressThe address of the authorizer
signingFunctionfunctionA function that allows FCL to sign using the authorization details and produce a valid signature.
keyIdnumberThe index of the key to use during authorization. (Multiple keys on an account is possible).
sequenceNumnumberA number that is incremented per transaction using they keyId.

SignableObject​

An object that contains all the information needed for FCL to sign a message with the user's signature.

KeyValue TypeDescription
addrAddressThe address of the authorizer
keyIdnumberThe index of the key to use during authorization. (Multiple keys on an account is possible).
signaturefunctionA SigningFunction that can produce a valid signature for a user from a message.

AccountObject​

The JSON representation of an account on the Flow blockchain.

KeyValue TypeDescription
addressAddressThe address of the account
balancenumberThe FLOW balance of the account in 10^8.
codeCodeThe code of any Cadence contracts stored in the account.
contractsObject: ContractAn object with keys as the contract name deployed and the value as the the cadence string.
keys[KeyObject]Any contracts deployed to this account.

Address​

Value TypeDescription
string(formatted)A valid Flow address should be 16 characters in length.
A 0x prefix is optional during inputs.
eg. f8d6e0586b0a20c1

ArgumentObject​

An argument object created by fcl.arg(value,type)

KeyValue TypeDescription
valueanyAny value to be used as an argument to a builder.
xformFTypeAny of the supported types on Flow.

ArgumentFunction​

An function that takes the fcl.arg function and fcl types t and returns an array of fcl.arg(value,type).

(arg, t) => Array<Arg>

Parameter NameValue TypeDescription
argfunctionA function that returns an ArgumentObject - fcl.arg.
tFTypesAn object with acccess to all of the supported types on Flow.

Returns

Value TypeDescription
[fcl.args]Array of fcl.args.

Authorization Function​

An authorization function must produce the information of the user that is going to sign and a signing function to use the information to produce a signature.

⚠️This function is always async.

📣 By default FCL exposes fcl.authz that produces the authorization object for the current user (given they are signed in and only on the browser). Replace this with your own function that conforms to this interface to use it wherever an authorization object is needed.

Parameter NameValue TypeDescription
accountAccountObjectThe account of the user that is going to sign.

Returns

Value TypeDescription
Promise<[AuthorizationObject](#authorizationobject)>The object that contains all the information needed by FCL to authorize a user's transaction.

Usage​


_19
const authorizationFunction = async (account) => {
_19
// authorization function need to return an account
_19
const { address, keys } = account
_19
const tempId = `${address}-${keys[process.env.minterAccountIndex]}`;
_19
const keyId = Number(KEY_ID);
_19
let signingFunction = async signable => {
_19
return {
_19
keyId,
_19
addr: fcl.withPrefix(address),
_19
signature: sign(process.env.FLOW_MINTER_PRIVATE_KEY, signable.message), // signing function, read below
_19
}
_19
}
_19
return {
_19
...account,
_19
address,
_19
keyId,
_19
tempId,
_19
signingFunction,
_19
}

Signing Function​

Consumes a payload and produces a signature for a transaction.

⚠️This function is always async.

📣 Only write your own signing function if you are writing your own custom authorization function.

Payload​

Note: These values are destructed from the payload object in the first argument.

Parameter NameValue TypeDescription
messagestringThe encoded string which needs to be used to produce the signature.
addrstringThe encoded string which needs to be used to produce the signature.
keyIdstringThe encoded string which needs to be used to produce the signature.
rolesstringThe encoded string which needs to be used to produce the signature.
voucherobjectThe raw transactions information, can be used to create the message for additional safety and lack of trust in the supplied message.

Returns

Value TypeDescription
Promise<[SignableObject](#signableobject)>The object that contains all the information needed by FCL to authorize a user's transaction.

Usage​


_31
import * as fcl from "@onflow/fcl";
_31
import { ec as EC } from "elliptic";
_31
import { SHA3 } from "sha3";
_31
const ec: EC = new EC("p256");
_31
_31
const produceSignature = (privateKey, msg) => {
_31
const key = ec.keyFromPrivate(Buffer.from(privateKey, "hex"));
_31
const sig = key.sign(this.hashMsg(msg));
_31
const n = 32;
_31
const r = sig.r.toArrayLike(Buffer, "be", n);
_31
const s = sig.s.toArrayLike(Buffer, "be", n);
_31
return Buffer.concat([r, s]).toString("hex");
_31
};
_31
_31
const signingFunction = ({
_31
message, // The encoded string which needs to be used to produce the signature.
_31
addr, // The address of the Flow Account this signature is to be produced for.
_31
keyId, // The keyId of the key which is to be used to produce the signature.
_31
roles: {
_31
proposer, // A Boolean representing if this signature to be produced for a proposer.
_31
authorizer, // A Boolean representing if this signature to be produced for a authorizer.
_31
payer, // A Boolean representing if this signature to be produced for a payer.
_31
},
_31
voucher, // The raw transactions information, can be used to create the message for additional safety and lack of trust in the supplied message.
_31
}) => {
_31
return {
_31
addr, // The address of the Flow Account this signature was produced for.
_31
keyId, // The keyId for which key was used to produce the signature.
_31
signature: produceSignature(message), // The hex encoded string representing the signature of the message.
_31
};
_31
};

Examples:​

TransactionObject​

KeyValue TypeDescription
argsobjectA list of encoded Cadence values passed into this transaction. These have not been decoded by the JS-SDK.
authorizers[Address]A list of the accounts that are authorizing this transaction to mutate to their on-chain account state. See more here.
envelopeSignatures[SignableObject]A list of signatures generated by the payer role. See more here.
gasLimitnumberThe maximum number of computational units that can be used to execute this transaction. See more here.
payerAddressThe account that pays the fee for this transaction. See more here.
payloadSignatures[SignableObject]A list of signatures generated by the proposer and authorizer roles. See more here.
proposalKey[ProposalKey]The account key used to propose this transaction
referenceBlockIdstringA reference to the block used to calculate the expiry of this transaction.
scriptstringThe UTF-8 encoded Cadence source code that defines the execution logic for this transaction

TransactionRolesObject​

Key NameValue TypeDescription
proposerbooleanA Boolean representing if this signature to be produced for a proposer.
authorizerbooleanA Boolean representing if this signature to be produced for an authorizer.
payerbooleanA Boolean representing if this signature to be produced for a payer.

For more on what each transaction role means, see singing roles.

TransactionStatusObject​

KeyValue TypeDescription
blockIdstringID of the block that contains the transaction.
events[EventObject]An array of events that were emitted during the transaction.
statusTransactionStatusThe status of the transaction on the blockchain.
statusStringTransactionStatusThe status as as descriptive text (e.g. "FINALIZED").
errorMessagestringAn error message if it exists. Default is an empty string ''.
statusCodenumberThe pass/fail status. 0 indicates the transaction succeeded, 1 indicates it failed.

EventName​

Value TypeDescription
string(formatted)A event name in Flow must follow the format A.{AccountAddress}.{ContractName}.{EventName}
eg. A.ba1132bc08f82fe2.Debug.Log

Contract​

Value TypeDescription
string(formatted)A formatted string that is a valid cadence contract.

KeyObject​

This is the JSON representation of a key on the Flow blockchain.

KeyValue TypeDescription
indexnumberThe address of the account
publicKeystringThe public portion of a public/private key pair
signAlgonumberAn index referring to one of ECDSA_P256 or ECDSA_secp256k1
hashAlgonumberAn index referring to one of SHA2_256 or SHA3_256
weightnumberA number between 1 and 1000 indicating the relative weight to other keys on the account.
sequenceNumbernumberThis number is incremented for every transaction signed using this key.
revokedbooleanIf this key has been disabled for use.

ProposalKeyObject​

ProposalKey is the account key used to propose this transaction.

A proposal key references a specific key on an account, along with an up-to-date sequence number for that key. This sequence number is used to prevent replay attacks.

You can find more information about sequence numbers here

KeyValue TypeDescription
addressAddressThe address of the account
keyIndexnumberThe index of the account key being referenced
sequenceNumbernumberThe sequence number associated with this account key for this transaction

BlockObject​

The JSON representation of a key on the Flow blockchain.

KeyValue TypeDescription
idstringThe id of the block.
parentIdstringThe id of the parent block.
heightnumberThe height of the block.
timestampobjectContains time related fields.
collectionGuarantees[CollectionGuaranteeObject]Contains the ids of collections included in the block.
blockSeals[SealedBlockObject]The details of which nodes executed and sealed the blocks.
signaturesUint8Array([numbers])All signatures.

BlockHeaderObject​

The subset of the BlockObject containing only the header values of a block.

KeyValue TypeDescription
idstringThe id of the block.
parentIdstringThe id of the parent block.
heightnumberThe height of the block.
timestampobjectContains time related fields.

CollectionGuaranteeObject​

A collection that has been included in a block.

KeyValue TypeDescription
collectionIdstringThe id of the block.
signatures[SignatureObject]All signatures.

CollectionObject​

A collection is a list of transactions that are contained in the same block.

KeyValue TypeDescription
idstringThe id of the collection.
transactionIds[string]The ids of the transactions included in the collection.

ResponseObject​

The format of all responses in FCL returned from fcl.send(...). For full details on the values and descriptions of the keys, view here.

Key
tag
transaction
transactionStatus
transactionId
encodedData
events
account
block
blockHeader
latestBlock
collection

Event Object​

KeyValue TypeDescription
blockIdstringID of the block that contains the event.
blockHeightnumberHeight of the block that contains the event.
blockTimestampstringThe timestamp of when the block was sealed in a DateString format. eg. '2021-06-25T13:42:04.227Z'
typeEventNameA string containing the event name.
transactionIdstringCan be used to query transaction information, eg. via a Flow block explorer.
transactionIndexnumberUsed to prevent replay attacks.
eventIndexnumberUsed to prevent replay attacks.
dataanyThe data emitted from the event.

Transaction Statuses​

The status of a transaction will depend on the Flow blockchain network and which phase it is in as it completes and is finalized.

Status CodeDescription
0Unknown
1Transaction Pending - Awaiting Finalization
2Transaction Finalized - Awaiting Execution
3Transaction Executed - Awaiting Sealing
4Transaction Sealed - Transaction Complete. At this point the transaction result has been committed to the blockchain.
5Transaction Expired

GRPC Statuses​

The access node GRPC implementation follows the standard GRPC Core status code spec. View here.

FType​

FCL arguments must specify one of the following support types for each value passed in.

TypeExample
UIntfcl.arg(1, t.UInt)
UInt8fcl.arg(8, t.UInt8)
UInt16fcl.arg(16, t.UInt16)
UInt32fcl.arg(32, t.UInt32)
UInt64fcl.arg(64, t.UInt64)
UInt128fcl.arg(128, t.UInt128)
UInt256fcl.arg(256, t.UInt256)
Intfcl.arg(1, t.Int)
Int8fcl.arg(8, t.Int8)
Int16fcl.arg(16, t.Int16)
Int32fcl.arg(32, t.Int32)
Int64fcl.arg(64, t.Int64)
Int128fcl.arg(128, t.Int128)
Int256fcl.arg(256, t.Int256)
Word8fcl.arg(8, t.Word8)
Word16fcl.arg(16, t.Word16)
Word32fcl.arg(32, t.Word32)
Word64fcl.arg(64, t.Word64)
UFix64fcl.arg("64.123", t.UFix64)
Fix64fcl.arg("64.123", t.Fix64)
Stringfcl.arg("Flow", t.String)
Characterfcl.arg("c", t.String)
Boolfcl.arg(true, t.String)
Addressfcl.arg("0xABC123DEF456", t.Address)
Optionalfcl.arg("Flow", t.Optional(t.String))
Arrayfcl.args([ fcl.arg(["First", "Second"], t.Array(t.String)) ])
Dictionaryfcl.args([fcl.arg([{key: 1, value: "one"}, {key: 2, value: "two"}], t.Dictionary({key: t.Int, value: t.String}))])
Pathfcl.arg({ domain: "public", identifier: "flowTokenVault" }, t.Path)