HTTP Client

Low-level typed HTTP client for the Turnkey API

@turnkey/http is a lower-level, fully typed HTTP client for interacting with the Turnkey API. It gives you direct access to every Turnkey endpoint with complete TypeScript types for all inputs and responses.

For most use cases, higher-level packages like @turnkey/sdk-server, @turnkey/ethers, or @turnkey/viem wrap this client and are easier to work with. Use @turnkey/http directly when you need fine-grained control over individual API calls.

Installation

npm

npm install @turnkey/http

TurnkeyClient

TurnkeyClient is the main class exported from @turnkey/http. It accepts a configuration object and a stamper, then exposes typed async methods for every Turnkey API endpoint.

Constructor

new TurnkeyClient(config: THttpConfig, stamper: TStamper)

config · THttpConfig · required

Configuration object for the client.

Show THttpConfig properties

baseUrl · string · required

The base URL of the Turnkey API. Use https://api.turnkey.com for production.

stamper · TStamper · required

A stamper instance that signs outgoing requests. Turnkey provides two stampers:

• ApiKeyStamper from @turnkey/api-key-stamper — signs with a P-256 API key pair
• WebAuthnStamper from @turnkey/webauthn-stamper — signs with a passkey or WebAuthn device

Any object implementing the TStamper interface ({ stamp: (input: string) => Promise<TStamp> }) is accepted.

Usage example

import { ApiKeyStamper } from "@turnkey/api-key-stamper";
import { TurnkeyClient } from "@turnkey/http";

// This stamper produces signatures using the API key pair passed in.
const stamper = new ApiKeyStamper({
  apiPublicKey: "...",
  apiPrivateKey: "...",
});

// The Turnkey client uses the passed-in stamper to produce signed requests
// and sends them to Turnkey.
const client = new TurnkeyClient(
  {
    baseUrl: "https://api.turnkey.com",
  },
  stamper,
);

// Make authenticated requests
const data = await client.getWhoami({
  organizationId: "<Your organization id>",
});

Key methods

Every method on TurnkeyClient follows the same pattern: it accepts a typed input object and returns a typed response. For each endpoint, there is also a corresponding stamp* method that produces a signed request without sending it — useful for proxy scenarios.

Read methods

Method	Description
getWhoami(input)	Returns the user and organization associated with the current credentials
getWallets(input)	Lists all wallets in an organization
getWallet(input)	Returns details for a single wallet
getWalletAccounts(input)	Lists all accounts derived from a wallet
getWalletAccount(input)	Returns details for a single wallet account
getPrivateKeys(input)	Lists all raw private keys in an organization
getPrivateKey(input)	Returns details for a single private key
getActivity(input)	Returns the current state of an activity by ID
getActivities(input)	Lists activities for an organization
getOrganizationConfigs(input)	Returns configuration for an organization
getUser(input)	Returns details for a single user
getPolicies(input)	Lists all policies in an organization

Mutation methods

All mutation endpoints are asynchronous and return an activity object. The activity’s status field starts as ACTIVITY_STATUS_PENDING and must be polled to completion. See Activity Polling for details.

The exceptions are private key signing endpoints (signTransaction, signRawPayload, signRawPayloads), which complete synchronously.

Method	Description
createWallet(input)	Creates an HD wallet and derives the first account
createWalletAccounts(input)	Derives additional accounts from an existing wallet
createPrivateKeys(input)	Creates one or more raw private keys
createSubOrganization(input)	Creates a sub-organization under the current org
signTransaction(input)	Signs a transaction — completes synchronously
signRawPayload(input)	Signs an arbitrary payload — completes synchronously
signRawPayloads(input)	Batch-signs multiple payloads — completes synchronously
createApiKeys(input)	Adds API key authenticators to a user
createUsers(input)	Creates users within an organization
deleteUsers(input)	Removes users from an organization
createPolicy(input)	Creates an access control policy
exportWallet(input)	Initiates a wallet mnemonic export
importWallet(input)	Initiates a wallet mnemonic import
exportPrivateKey(input)	Initiates a private key export
importPrivateKey(input)	Initiates a private key import

Stamp methods

For every method above, a corresponding stamp* method is available. It signs the request without sending it, returning a TSignedRequest:

const signedRequest = await client.stampGetWhoami({
  organizationId: "<Your organization id>",
});
// signedRequest: { body: string, stamp: TStamp, url: string }

This is useful when building proxy servers that forward pre-signed requests.

Exported types and utilities

import {
  TurnkeyClient,
  TurnkeyActivityError,
  TurnkeyActivityConsensusNeededError,
  TurnkeyRequestError,
  withAsyncPolling,
  createActivityPoller,
  getWebAuthnAttestation,
  sealAndStampRequestBody,
  assertActivityCompleted,
  getSignatureFromActivity,
  getSignaturesFromActivity,
  getSignedTransactionFromActivity,
  assertNonNull,
  TERMINAL_ACTIVITY_STATUSES,
  type TurnkeyApiTypes,
  type TActivity,
  type TActivityId,
  type TActivityStatus,
  type TActivityType,
  type TSignedRequest,
  type TSignature,
} from "@turnkey/http";

TStamper interface

If you need to build a custom stamper, implement the TStamper interface:

import type { TStamp } from "@turnkey/http";

const myStamper = {
  stamp: async (input: string): Promise<TStamp> => {
    // Sign `input` and return the header name/value pair
    return {
      stampHeaderName: "X-Stamp",
      stampHeaderValue: "<your-signature>",
    };
  },
};

TurnkeyRequestError

When the Turnkey API returns a non-2xx response, TurnkeyClient throws a TurnkeyRequestError:

import { TurnkeyRequestError } from "@turnkey/http";

try {
  await client.getWhoami({ organizationId: "..." });
} catch (error) {
  if (error instanceof TurnkeyRequestError) {
    console.log(error.code);    // gRPC status code
    console.log(error.message); // human-readable message
    console.log(error.details); // additional details array, or null
  }
}