@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

``bash
npm install @osiris-ai/turnkey-sdk
`

Quick Start

`typescript
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

$3

`typescript
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
}
`

$3

#### listWallets(request: ListWalletsRequest): Promise

Lists all wallets in an organization.

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

#### listWalletAccounts(request: ListWalletAccountsRequest): Promise

Lists all accounts in a specific wallet.

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

#### createWallet(request: CreateWalletRequest): Promise

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

`typescript
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

Adds new accounts to an existing wallet.

`typescript
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'
}]
}
});
`

$3

#### signRawPayload(request: SignRawPayloadRequest): Promise

Signs a single raw payload.

`typescript
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

Signs multiple raw payloads in a single request.

`typescript
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

Signs a transaction.

`typescript
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:

`typescript
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.