@turnkey/viem

Turnkey Custom Account for Viem

@turnkey/viem provides a Turnkey-backed Custom Account compatible with viem’s WalletClient. It implements all signing APIs expected by viem, including support for legacy, EIP-2930, EIP-1559, EIP-4844, and EIP-7702 transaction types.

Installation

npm

npm install viem @turnkey/viem

Usage

1. Create a Turnkey HTTP client

   import { TurnkeyClient } from "@turnkey/http";
   import { ApiKeyStamper } from "@turnkey/api-key-stamper";
   
   const httpClient = new TurnkeyClient(
     { baseUrl: "https://api.turnkey.com" },
     new ApiKeyStamper({
       apiPublicKey: "your-api-public-key",
       apiPrivateKey: "your-api-private-key",
     }),
   );
   
2. Create a Turnkey viem account

   import { createAccount } from "@turnkey/viem";
   
   const turnkeyAccount = await createAccount({
     client: httpClient,
     organizationId: "your-organization-id",
     signWith: "your-wallet-account-address-or-private-key-id",
     // optional: provide the Ethereum address directly to avoid a network round-trip
     // ethereumAddress: "0x...",
   });
   

   If signWith is a private key ID (not an Ethereum address) and ethereumAddress is not provided, createAccount fetches the address from the Turnkey API automatically.

   If you are using a passkey client, provide ethereumAddress explicitly to avoid prompting the user for passkey authentication just to retrieve their address.

3. Use the account with a viem WalletClient

   The returned LocalAccount is a standard viem account — use it anywhere viem expects an account.

   import { createWalletClient, http } from "viem";
   import { sepolia } from "viem/chains";
   
   const client = createWalletClient({
     account: turnkeyAccount,
     chain: sepolia,
     transport: http("https://sepolia.infura.io/v3/your-infura-api-key"),
   });
   
   const txHash = await client.sendTransaction({
     to: "0x08d2b0a37F869FF76BACB5Bab3278E26ab7067B7",
     value: 1000000000000000n, // 0.001 ETH
   });
   
   console.log(`Transaction hash: ${txHash}`);
   

createAccount options

client · TurnkeyClient | TurnkeyBrowserClient | TurnkeyServerClient | TurnkeySDKClientBase · required

A Turnkey client instance.

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.

ethereumAddress · string

The Ethereum address to use for this account. Required if signWith is a private key ID. If omitted, createAccount fetches it from the Turnkey API.

Synchronous initialization

Use createAccountWithAddress when you already know the Ethereum address and want to avoid an async API call:

import { createAccountWithAddress } from "@turnkey/viem";

const turnkeyAccount = createAccountWithAddress({
  client: httpClient,
  organizationId: "your-organization-id",
  signWith: "your-private-key-id",
  ethereumAddress: "0xYourAddress",
});

Supported transaction types

@turnkey/viem supports all viem transaction types:

Type	Standard
Legacy	Pre-EIP-2930
Type 1	EIP-2930 (access lists)
Type 2	EIP-1559 (fee market)
Type 3	EIP-4844 (blob transactions)
Type 4	EIP-7702 (set code)

Error handling

@turnkey/viem exports viem-compatible error classes:

• TurnkeyActivityError — thrown when a Turnkey activity returns an unexpected status
• TurnkeyConsensusNeededError — thrown when a Turnkey activity requires policy consensus before proceeding

Both errors expose activityId and activityStatus for programmatic handling.

import { isTurnkeyActivityError, isTurnkeyActivityConsensusNeededError } from "@turnkey/viem";

try {
  await client.sendTransaction(...);
} catch (error) {
  if (isTurnkeyActivityConsensusNeededError(error)) {
    // Handle consensus required
  }
}

If you need a standard EIP-1193 provider interface (for use with MetaMask-compatible libraries or browser wallets), see @turnkey/eip-1193-provider.

Examples

• with-viem: create, sign, and broadcast a transaction on Sepolia using various transaction types