WalletUtils

Overview

Namespace containing WalletUtils utilities

Functions

approve

Sends an approval response to FCL with the provided data. This indicates that the user has approved the requested operation (authentication, transaction signing, etc.) and includes the resulting data (signatures, account information, etc.).

Sends "FCL:VIEW:RESPONSE". with status "APPROVED".

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.approve(data)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.approve(data)

Usage


_19// Approve authentication with account data
_19import { approve } from "@onflow/fcl"
_19
_19const accountData = {
_19  f_type: "AuthnResponse",
_19  f_vsn: "1.0.0",
_19  addr: "0x1234567890abcdef",
_19  services: [
_19    {
_19      f_type: "Service",
_19      f_vsn: "1.0.0",
_19      type: "authz",
_19      method: "HTTP/POST",
_19      endpoint: "https://wallet.example.com/authz"
_19    }
_19  ]
_19}
_19
_19approve(accountData)

Parameters

`data`

Type: any
Description: The approval data to send back to FCL (signatures, account info, etc.)

Returns

void

close

Closes the wallet service window/iframe and notifies FCL that the service is shutting down. This should be called when the user cancels an operation or when the wallet service needs to close itself.

Sends "FCL:VIEW:CLOSE".

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.close()

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.close()

Returns

void

decline

Sends a decline response to FCL indicating that the user has rejected or cancelled the requested operation. This should be called when the user explicitly cancels an operation or when an error prevents the operation from completing.

Sends "FCL:VIEW:RESPONSE". with status "DECLINED".

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.decline(reason)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.decline(reason)

Usage


_10// Decline when user cancels authentication
_10import { decline } from "@onflow/fcl"
_10
_10document.getElementById('cancel-btn').addEventListener('click', () => {
_10  decline("User cancelled authentication")
_10})

Parameters

`reason`

Type: string
Description: Human-readable reason for declining the request

Returns

void

encodeAccountProof

Encodes account proof data for cryptographic signing on the Flow blockchain. This function creates a standardized message format that combines the application identifier, account address, and nonce into a format suitable for cryptographic signing. The encoded message can then be signed by the account's private key to create an account proof.

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.encodeAccountProof(accountProofData, includeDomainTag)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.encodeAccountProof(accountProofData, includeDomainTag)

Usage


_11// Basic account proof encoding
_11import { encodeAccountProof } from "@onflow/fcl"
_11
_11const accountProofData = {
_11  address: "0x1234567890abcdef",
_11  nonce: "75f8587e5bd982ec9289c5be1f9426bd12b4c1de9c7a7e4d8c5f9e8b2a7c3f1e9", // 64 hex chars (32 bytes)
_11  appIdentifier: "MyAwesomeApp"
_11}
_11
_11const encodedMessage = encodeAccountProof(accountProofData)
_11console.log("Encoded message:", encodedMessage)

Parameters

`accountProofData`

Type:


_10export interface AccountProofData {
_10  address: string
_10  nonce: string
_10  signatures: CompositeSignature[]
_10}

`includeDomainTag` (optional)

Type: boolean
Description: Whether to include the FCL domain tag in the encoding

Returns

string

injectExtService

Injects an external authentication service into the global FCL extensions array. This function is used by wallet providers to register their authentication services with FCL, making them available for user authentication. The service must be of type "authn" and have a valid endpoint.

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.injectExtService(service)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.injectExtService(service)

Usage


_10// Register a wallet authentication service
_10const walletService = {
_10  type: "authn",
_10  endpoint: "https://example-wallet.com/fcl/authn",
_10  method: "HTTP/POST",
_10  identity: { address: "0x123..." },
_10  provider: { name: "Example Wallet" }
_10}
_10fcl.WalletUtils.injectExtService(walletService)

Parameters

`service`

Type: Service
Description: The authentication service to inject. Must have type "authn" and a valid endpoint

Returns

void

onMessageFromFCL

Sets up a message listener to receive messages from the parent FCL application. This function is used by wallet services to listen for specific message types from FCL and respond accordingly. It handles message filtering, data sanitization, and provides context about the message origin for security purposes.

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.onMessageFromFCL(messageType, cb)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.onMessageFromFCL(messageType, cb)

Usage


_20// Listen for authentication requests from FCL
_20import { onMessageFromFCL } from "@onflow/fcl"
_20
_20const removeListener = onMessageFromFCL("FCL:VIEW:READY:RESPONSE", (data, context) => {
_20  console.log("FCL is ready for communication")
_20  console.log("Message from:", context.origin)
_20  console.log("Ready data:", data)
_20
_20  // Verify origin for security
_20  if (context.origin === "https://myapp.com") {
_20    initializeWalletServices()
_20  } else {
_20    console.warn("Unexpected origin:", context.origin)
_20  }
_20})
_20
_20// Stop listening when wallet service closes
_20window.addEventListener("beforeunload", () => {
_20  removeListener()
_20})

Parameters

`messageType`

Type: string
Description: The specific message type to listen for (e.g., "FCL:VIEW:READY:RESPONSE")

`cb` (optional)

Type:


_10(data: any, context: { origin: string; }) => void

Description: Callback function executed when a matching message is received

Returns


_10() => void

ready

Initiates the communication handshake between a wallet service and FCL. This function listens for the "FCL:VIEW:READY:RESPONSE" message from FCL and automatically sends "FCL:VIEW:READY" to indicate the wallet service is ready to receive requests. This is typically the first function called when a wallet service loads.

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.ready(cb, msg)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.ready(cb, msg)

Usage


_11// Basic wallet service initialization
_11import { ready } from "@onflow/fcl"
_11
_11ready((data, context) => {
_11  console.log("FCL is ready to communicate")
_11  console.log("FCL origin:", context.origin)
_11  console.log("Ready data:", data)
_11
_11  // Wallet service is now ready to handle authentication requests
_11  initializeWalletUI()
_11})

Parameters

`cb`

Type:


_10(data: any, context: { origin: string; }) => void

Description: Callback function executed when FCL responds with ready confirmation

`msg` (optional)

Type:


_10export interface PollingResponse {
_10  f_type: "PollingResponse"
_10  f_vsn: "1.0.0"
_10  status: "APPROVED" | "DECLINED" | "REDIRECT"
_10  reason: string | null
_10  data: any
_10}

Description: Optional message payload to include with ready signal

Returns

void

redirect

Sends a redirect response to FCL indicating that the operation requires a redirect to complete. This is used when the wallet service needs to redirect the user to another URL (such as a native app deep link or external service).

Sends "FCL:VIEW:RESPONSE". with status "REDIRECT".

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.redirect(data)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.redirect(data)

Usage


_10// Redirect to native wallet app
_10import { redirect } from "@onflow/fcl"
_10
_10redirect({
_10  f_type: "RedirectResponse",
_10  f_vsn: "1.0.0",
_10  url: "flow-wallet://sign?transaction=abc123",
_10  callback: "https://myapp.com/callback"
_10})

Parameters

`data`

Type: any
Description: Redirect data containing the target URL and any additional parameters

Returns

void

sendMsgToFCL

Sends messages from a wallet or service back to the parent FCL application. This function handles communication between wallet UIs (running in iframes, popups, or redirects) and the main FCL application. It automatically detects the communication method (redirect, iframe, or popup) and sends the message accordingly.

Import

You can import the entire package and access the function:


_10import * as fcl from "@onflow/fcl-core"
_10
_10fcl.WalletUtils.sendMsgToFCL(type, msg)

Or import the namespace directly:


_10import { WalletUtils } from "@onflow/fcl-core"
_10
_10WalletUtils.sendMsgToFCL(type, msg)

Usage


_10// Send approval response with signature data
_10import { sendMsgToFCL } from "@onflow/fcl"
_10
_10sendMsgToFCL("FCL:VIEW:RESPONSE", {
_10  f_type: "CompositeSignature",
_10  f_vsn: "1.0.0",
_10  addr: "0x1234567890abcdef",
_10  keyId: 0,
_10  signature: "abc123..."
_10})

Parameters

`type`

Type: string
Description: The message type identifier (e.g., "FCL:VIEW:RESPONSE", "FCL:VIEW:READY")

`msg` (optional)

Type:


_10export interface PollingResponse {
_10  f_type: "PollingResponse"
_10  f_vsn: "1.0.0"
_10  status: "APPROVED" | "DECLINED" | "REDIRECT"
_10  reason: string | null
_10  data: any
_10}

Description: Optional message payload containing response data

Returns

void

Overview​

Functions​

approve​

Import​

Usage​

Parameters​

data​

Returns​

close​

Import​

Returns​

decline​

Import​

Usage​

Parameters​

reason​

Returns​

encodeAccountProof​

Import​

Usage​

Parameters​

accountProofData​

includeDomainTag (optional)​

Returns​

injectExtService​

Import​

Usage​

Parameters​

service​

Returns​

onMessageFromFCL​

Import​

Usage​

Parameters​

messageType​

cb (optional)​

Returns​

ready​

Import​

Usage​

Parameters​

cb​

msg (optional)​

Returns​

redirect​

Import​

Usage​

Parameters​

data​

Returns​

sendMsgToFCL​

Import​

Usage​

Parameters​

type​

msg (optional)​

Returns​

Rate this page

Overview

Functions

approve

Import

Usage

Parameters

`data`

Returns

close

Import

Returns

decline

Import

Usage

Parameters

`reason`

Returns

encodeAccountProof

Import

Usage

Parameters

`accountProofData`

`includeDomainTag` (optional)

Returns

injectExtService

Import

Usage

Parameters

`service`

Returns

onMessageFromFCL

Import

Usage

Parameters

`messageType`

`cb` (optional)

Returns

ready

Import

Usage

Parameters

`cb`

`msg` (optional)

Returns

redirect

Import

Usage

Parameters

`data`

Returns

sendMsgToFCL

Import

Usage

Parameters

`type`

`msg` (optional)

Returns