Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tkhq/sdk/llms.txt
Use this file to discover all available pages before exploring further.
@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 install viem @turnkey/viem
Usage
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",
}),
);
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...",
});
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.
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.
Your Turnkey organization ID (or sub-organization ID).
A wallet account address, private key address, or private key ID to sign with.
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 statusTurnkeyConsensusNeededError — 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
