@turnkey/eip-1193-provider

EIP-1193 Ethereum Provider powered by Turnkey

@turnkey/eip-1193-provider delivers a Turnkey-compatible Ethereum provider that adheres to the EIP-1193 standard. It supports account management, message signing, transaction signing, and direct RPC forwarding across any EVM-compatible chain.

Authentication uses WebAuthn passkeys by default via @turnkey/webauthn-stamper. Passkey prompts appear when the user calls signing methods such as eth_requestAccounts, personal_sign, or eth_sendTransaction.

Installation

npm

npm install @turnkey/eip-1193-provider @turnkey/http @turnkey/webauthn-stamper

Initialization

1. Set up the Turnkey client

   import { WebauthnStamper } from "@turnkey/webauthn-stamper";
   import { TurnkeyClient } from "@turnkey/http";
   
   const stamper = new WebauthnStamper({
     rpId: "your-domain.com",
   });
   
   const turnkeyClient = new TurnkeyClient(
     { baseUrl: "https://api.turnkey.com" },
     stamper,
   );
   
2. Resolve the organization and wallet IDs

   // Get the sub-organization ID associated with the user's account
   const { organizationId } = await turnkeyClient.getWhoami({
     organizationId: process.env.ORGANIZATION_ID,
   });
   
   // Get the user's wallets
   const { wallets } = await turnkeyClient.getWallets({ organizationId });
   const walletId = wallets[0].walletId;
   
3. Create the EIP-1193 provider

   import { createEIP1193Provider } from "@turnkey/eip-1193-provider";
   
   const provider = await createEIP1193Provider({
     walletId,
     organizationId,
     turnkeyClient,
     chains: [
       {
         chainName: "Ethereum Mainnet",
         chainId: "0x1",
         rpcUrls: ["https://mainnet.infura.io/v3/your-infura-project-id"],
       },
     ],
   });
   

Configuration options

createEIP1193Provider accepts a TurnkeyEIP1193ProviderOptions object:

walletId · UUID · required

The ID of the Turnkey wallet to use for signing. Accounts are derived from this wallet.

organizationId · UUID · required

The Turnkey organization ID (or sub-organization ID) that owns the wallet.

turnkeyClient · TurnkeyClient | TurnkeyBrowserClient · required

A Turnkey client instance configured with a stamper.

chains · AddEthereumChainParameter[] · required

An array of chain configurations. Each chain requires a chainName, a chainId (hex string), and at least one rpcUrls entry. The provider validates that each chainId matches the value returned by the RPC endpoint at initialization.

Supported JSON-RPC methods

The provider handles these methods directly using Turnkey signing:

Method	Description
eth_requestAccounts	Returns all Ethereum addresses in the configured wallet. Prompts passkey authentication.
eth_accounts	Returns the current list of connected accounts.
personal_sign	Signs a message with the specified account. Prompts passkey authentication.
eth_sign	Signs data with the specified account. Prompts passkey authentication.
eth_signTypedData_v4	Signs EIP-712 typed data. Prompts passkey authentication.
eth_signTransaction	Signs a transaction without broadcasting it. Prompts passkey authentication.
eth_sendTransaction	Signs a transaction and broadcasts it via the configured RPC endpoint.

All other standard Ethereum JSON-RPC methods (e.g., eth_blockNumber, eth_getBalance, eth_call, eth_estimateGas, eth_getLogs) are forwarded directly to the active chain’s RPC URL.

Multi-chain support

Pass multiple chains to support chain switching at runtime:

const provider = await createEIP1193Provider({
  walletId,
  organizationId,
  turnkeyClient,
  chains: [
    {
      chainName: "Ethereum Mainnet",
      chainId: "0x1",
      rpcUrls: ["https://mainnet.infura.io/v3/your-infura-project-id"],
    },
    {
      chainName: "Sepolia Testnet",
      chainId: "0xaa36a7",
      rpcUrls: ["https://sepolia.infura.io/v3/your-infura-project-id"],
    },
  ],
});

Switch chains at runtime with the standard wallet_switchEthereumChain method:

await provider.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0xaa36a7" }],
});

Add a new chain at runtime with wallet_addEthereumChain:

await provider.request({
  method: "wallet_addEthereumChain",
  params: [
    {
      chainName: "Polygon",
      chainId: "0x89",
      rpcUrls: ["https://polygon-rpc.com"],
    },
  ],
});

Events

The provider emits standard EIP-1193 events:

Event	When emitted
connect	The provider successfully connects to a chain
disconnect	The provider is disconnected from all configured chains
chainChanged	The active chain is switched via wallet_switchEthereumChain

provider.on("connect", ({ chainId }) => {
  console.log(`Connected to chain ${chainId}`);
});

provider.on("chainChanged", ({ chainId }) => {
  console.log(`Switched to chain ${chainId}`);
});

provider.removeListener("connect", handler);

The provider throws a ProviderDisconnectedError if it loses connectivity to all configured chains. If it is only disconnected from the active chain (but still connected to others), it throws ChainDisconnectedError instead.