Skip to main content
info

This package is currently in alpha and is subject to change.

FCL Ethereum Provider

Exposes a client-side EIP-1193 compatible Ethereum provider that uses an FCL-authenticated Cadence Owned Account (COA) under the hood. If a wallet does not natively provide EVM capabilities, this provider emulates Ethereum JSON-RPC by delegating to FCL for signing and COA interactions.

Installation​


_10
npm install @onflow/fcl-ethereum-provider

Usage​


_40
import * as fcl from "@onflow/fcl"
_40
import { createEthereumProvider } from "@onflow/fcl-ethereum-provider"
_40
_40
// Configure FCL (pointing to whichever Flow network you require)
_40
fcl.config({
_40
"accessNode.api": "https://rest-testnet.onflow.org",
_40
"discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn",
_40
})
_40
_40
// Create the EIP-1193 provider
_40
const provider = createEthereumProvider({
_40
// Optional configuration:
_40
// service?: Service // Custom FCL service config
_40
// gateway?: Eip1193Provider | string // EVM Gateway provider or URL
_40
})
_40
_40
// Example: request EVM-style accounts (COA addresses)
_40
const accounts = await provider.request({ method: "eth_requestAccounts" })
_40
console.log("EVM Accounts:", accounts)
_40
_40
// Use the same session to sign a message
_40
const signature = await provider.request({
_40
method: "personal_sign",
_40
params: ["0x68656c6c6f20776f726c64", accounts[0]], // hex-encoded "hello world"
_40
})
_40
console.log("Signature:", signature)
_40
_40
// Or send transactions
_40
const txHash = await provider.request({
_40
method: "eth_sendTransaction",
_40
params: [
_40
{
_40
from: accounts[0],
_40
to: "0x1234...",
_40
data: "0xabcd1234...",
_40
value: "0x0",
_40
},
_40
],
_40
})
_40
console.log("Transaction Hash:", txHash)

API​

createEthereumProvider(config?: CreateEthereumProviderConfig): Eip1193Provider​

  • Parameters

    • config.service?: Service
      An [FCL “Service” object][fcl-service-docs] for custom FCL authentication flows. If omitted, the default FCL discovery service is used.
    • config.gateway?: Eip1193Provider | string
      An EIP-1193 provider (or a string URL) pointing to a Flow EVM gateway. Defaults to the public Flow EVM gateway if omitted.

  • Returns: An EIP-1193 provider instance you can pass into EVM tooling or interact with directly in your app.

Supported JSON-RPC Methods​

Below are the main request methods handled within the FCL Ethereum provider:

  1. eth_requestAccounts / eth_accounts

    • Behavior:
      • Invokes the FCL authentication flow (if not already authenticated)
      • Returns the Cadence-Owned Account (COA) address
      • Stores the COA at /storage/evm (creates if missing)

  2. eth_sendTransaction

    • Behavior:
      • Wraps the transaction in a Cadence transaction that invokes coa.call(...) in the Flow EVM
      • Uses the user’s authenticated COA for signing
      • Returns the resulting EVM transaction hash

  3. personal_sign

    • Behavior:
      • Requests a user signature via FCL’s signUserMessage or equivalent mechanism
      • Returns an RLP-encoded COA ownership proof in place of a raw secp256k1 signature

  4. eth_chainId

    • Behavior:
      • Returns the numeric Flow EVM chain ID (e.g., 0x747 for Flow EVM Mainnet)

  5. wallet_switchEthereumChain

    • Behavior:
      • Allows dApps to request switching to a different Flow EVM chain (e.g. testnet to mainnet).
      • Under the hood, this can trigger reconfiguration of FCL for a different Flow access node and Flow EVM gateway if recognized.
      • If the requested chain ID is not recognized, the call will throw an error (matching EIP-1193 standard error codes).

  6. wallet_addEthereumChain

    • Behavior:
      • Allows a dApp to request adding a Flow EVM chain config.
      • If the chain is recognized by the provider or is one the provider can handle, it will register it. Otherwise, it may reject with an EIP-1193 error.
      • Since Flow EVM is typically a single chain per environment, usage is limited. However, in principle, custom EVM networks or local dev can be added if your provider/gateway supports them.

Fallback Behavior​

Any unknown or unsupported request methods will be proxied to the gateway (if you provided a standard JSON-RPC URL or EIP-1193 provider). If the gateway does not handle them, an error will be returned.

Provider Events​

  • connect: Emitted once the user successfully authenticates via FCL, indicating that the provider is ready.
  • disconnect: Emitted if the FCL session ends or user explicitly logs out, severing the session.
  • accountsChanged: Emitted when the current user changes (e.g. re-authentication, or switching user in the wallet).
  • chainChanged: Emitted when the user switches to a different Flow EVM chain (e.g. testnet to mainnet).
Rate this page