@osiris-ai/turnkey-sdk

A minimal TypeScript SDK for interacting with the Turnkey API to create, manage, and sign with crypto wallets using API key authentication.

Features

• 🔐 Secure API Key Authentication - Uses Turnkey's API key stamper for request signing
• 🏦 Wallet Management - Create wallets, list wallets, and manage wallet accounts
• ✍️ Transaction Signing - Sign raw payloads, multiple payloads, and transactions
• 📝 Full TypeScript Support - Comprehensive type definitions for all API interactions
• 🚀 Lightweight - Minimal dependencies with tree-shakeable exports

Installation

npm install @osiris-ai/turnkey-sdk

Quick Start

import { TurnkeySDK } from '@osiris-ai/turnkey-sdk';

const sdk = new TurnkeySDK({
  organizationId: 'your-organization-id',
  apiPublicKey: 'your-api-public-key',
  apiPrivateKey: 'your-api-private-key',
  baseUrl: 'https://api.turnkey.com'
});

// List wallets
const wallets = await sdk.listWallets({
  organizationId: 'your-organization-id'
});

// Sign a raw payload
const signature = await sdk.signRawPayload({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payload: 'your-hex-payload',
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});

API Reference

Configuration

interface TurnkeyConfig {
  organizationId: string;    // Your Turnkey organization ID
  apiPublicKey: string;      // Your API public key
  apiPrivateKey: string;     // Your API private key
  baseUrl: string;           // Turnkey API base URL
}

Wallet Management

listWallets(request: ListWalletsRequest): Promise<ListWalletsResponse>

Lists all wallets in an organization.

const wallets = await sdk.listWallets({
  organizationId: 'your-organization-id'
});

listWalletAccounts(request: ListWalletAccountsRequest): Promise<ListWalletAccountsResponse>

Lists all accounts in a specific wallet.

const accounts = await sdk.listWalletAccounts({
  organizationId: 'your-organization-id',
  walletId: 'your-wallet-id',
  paginationOptions: {
    limit: '10',
    before: '',
    after: ''
  }
});

createWallet(request: CreateWalletRequest): Promise<CreateWalletResponse>

Creates a new wallet (sub-organization) with specified accounts.

const wallet = await sdk.createWallet({
  subOrganizationName: 'my-wallet',
  rootUsers: [{
    userName: 'wallet-admin',
    apiKeys: [{
      apiKeyName: 'admin-key',
      publicKey: 'your-public-key',
      curveType: 'API_KEY_CURVE_P256'
    }],
    authenticators: [],
    oauthProviders: []
  }],
  rootQuorumThreshold: 1,
  wallet: {
    walletName: 'my-wallet',
    accounts: [{
      pathFormat: 'PATH_FORMAT_BIP32',
      path: "m/44'/60'/0'/0/0",
      curve: 'CURVE_SECP256K1',
      addressFormat: 'ADDRESS_FORMAT_ETHEREUM'
    }],
    mnemonicLength: 12
  }
});

addWalletAccount(request: AddWalletAccountsRequest): Promise<AddWalletAccountsResponse>

Adds new accounts to an existing wallet.

const result = await sdk.addWalletAccount({
  type: 'ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    walletId: 'your-wallet-id',
    accounts: [{
      curve: 'CURVE_SECP256K1',
      pathFormat: 'PATH_FORMAT_BIP32',
      path: "m/44'/60'/0'/0/1",
      addressFormat: 'ADDRESS_FORMAT_ETHEREUM'
    }]
  }
});

Signing Operations

signRawPayload(request: SignRawPayloadRequest): Promise<SignRawPayloadResponse>

Signs a single raw payload.

const signature = await sdk.signRawPayload({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payload: '0x1234567890abcdef',
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});

signRawPayloads(request: SignRawPayloadsRequest): Promise<SignRawPayloadsResponse>

Signs multiple raw payloads in a single request.

const signatures = await sdk.signRawPayloads({
  type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOADS',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    payloads: ['0x1234567890abcdef', '0xfedcba0987654321'],
    encoding: 'PAYLOAD_ENCODING_HEXADECIMAL',
    hashFunction: 'HASH_FUNCTION_KECCAK256'
  }
});

signTransaction(request: SignTransactionRequest): Promise<SignTransactionResponse>

Signs a transaction.

const signedTx = await sdk.signTransaction({
  type: 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2',
  timestampMs: Date.now().toString(),
  organizationId: 'your-organization-id',
  parameters: {
    signWith: 'your-private-key-id',
    unsignedTransaction: '0x...',
    type: 'TRANSACTION_TYPE_ETHEREUM'
  }
});

Error Handling

The SDK includes built-in error handling for common scenarios:

try {
  const result = await sdk.signRawPayloads(request);
} catch (error) {
  console.error('Signing failed:', error.message);
}

Requirements

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher (for development)

Peer Dependencies

• @noble/curves ^1.9.2 (optional) - For cryptographic operations
• viem ^2.30.1 (optional) - For Ethereum utilities

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on the GitHub repository.