@turnkey/ethers

Turnkey Signer for Ethers.js

@turnkey/ethers provides a TurnkeySigner class that is a drop-in replacement for any ethers.Signer. It integrates with both ethers.js v5 and v6, and works with any ethers-compatible provider.

Installation

npm

npm install ethers @turnkey/ethers

Usage

1. Create a Turnkey HTTP client

   Initialize a TurnkeyClient with your credentials. Use ApiKeyStamper for server-side or automated environments.

   import { TurnkeyClient } from "@turnkey/http";
   import { ApiKeyStamper } from "@turnkey/api-key-stamper";
   
   const turnkeyClient = new TurnkeyClient(
     { baseUrl: "https://api.turnkey.com" },
     new ApiKeyStamper({
       apiPublicKey: "your-api-public-key",
       apiPrivateKey: "your-api-private-key",
     }),
   );
   
2. Initialize TurnkeySigner

   Create a TurnkeySigner with the Turnkey client, your organization ID, and a signing identifier.

   import { TurnkeySigner } from "@turnkey/ethers";
   
   const turnkeySigner = new TurnkeySigner({
     client: turnkeyClient,
     organizationId: "your-organization-id",
     signWith: "your-wallet-account-address-or-private-key-id",
   });
   

   The signWith field accepts a wallet account address, a private key address, or a private key ID.

3. Connect to a provider and sign

   Connect the signer to an ethers provider to access blockchain state and broadcast transactions.

   import { ethers } from "ethers";
   
   const provider = new ethers.providers.InfuraProvider("goerli");
   const connectedSigner = turnkeySigner.connect(provider);
   
   const address = await connectedSigner.getAddress();
   const balance = await connectedSigner.getBalance();
   
   const transactionRequest = {
     to: "0x2Ad9eA1E677949a536A270CEC812D6e868C88108",
     value: ethers.utils.parseEther("0.0001"),
     type: 2,
   };
   
   // Sign without broadcasting
   const signedTx = await connectedSigner.signTransaction(transactionRequest);
   
   // Sign and broadcast
   const sentTx = await connectedSigner.sendTransaction(transactionRequest);
   console.log(`Transaction sent: https://goerli.etherscan.io/tx/${sentTx.hash}`);
   

TurnkeySigner constructor options

client · TurnkeyClient | TurnkeyBrowserClient | TurnkeyServerClient | TurnkeySDKClientBase · required

A Turnkey client instance used to submit signing requests.

organizationId · string · required

Your Turnkey organization ID (or sub-organization ID).

signWith · string · required

A wallet account address, private key address, or private key ID to sign with.

Available methods

TurnkeySigner implements the full ethers.Signer interface:

Method	Description
getAddress()	Returns the Ethereum address associated with the signer. If signWith is a private key ID, the address is fetched from the Turnkey API.
signMessage(message)	Signs an arbitrary message. Bytes are treated as binary; strings as UTF-8.
signTransaction(transaction)	Signs a transaction without broadcasting it.
sendTransaction(transaction)	Signs and broadcasts a transaction via the connected provider.
signTypedData(domain, types, value)	Signs EIP-712 typed data.
connect(provider)	Returns a new TurnkeySigner connected to the given provider.

Using WebAuthn / passkeys

Swap ApiKeyStamper for WebauthnStamper to authenticate users with passkeys instead of API keys:

import { WebauthnStamper } from "@turnkey/webauthn-stamper";
import { TurnkeyClient } from "@turnkey/http";
import { TurnkeySigner } from "@turnkey/ethers";

const turnkeyClient = new TurnkeyClient(
  { baseUrl: "https://api.turnkey.com" },
  new WebauthnStamper({
    rpId: "your-domain.com",
  }),
);

const turnkeySigner = new TurnkeySigner({
  client: turnkeyClient,
  organizationId: "your-organization-id",
  signWith: "your-wallet-account-address",
});

WebauthnStamper prompts the user for a passkey signature when a request is made. Use it in browser environments where you want user-controlled signing.

Examples

Example	Description
with-ethers	Create a new Ethereum address, then sign and broadcast a transaction using the Ethers signer with Infura
with-gnosis	Create new Ethereum addresses, configure a 3/3 Gnosis safe, and create and execute a transaction from it
with-uniswap	Sign and broadcast a Uniswap v3 trade using the Ethers signer with Infura
with-nonce-manager	Create a new Ethereum address, then sign and broadcast multiple transactions in a sequential or optimistic manner
sweeper	Sweep funds from one address to a different address
deployer	Compile and deploy a smart contract

For lower-level, fully typed HTTP access to the Turnkey API, see @turnkey/http.