@hightop/signer

TypeScript SDK for the Hightop Signer API. Provides a type-safe client for all signer endpoints and viem-compatible wallet integrations.

Installation

npm install @hightop/signer viem

Quick Start

import { createSignerClient } from '@hightop/signer'

const client = createSignerClient({
  url: 'https://signer.example.com',
  keyId: 'your-key-id',
  keySecret: 'your-key-secret',
})

// Sign a hash
const { signature } = await client.sign({
  hash: '0x...',
})

// Broadcast a transaction via Smart Account
const { txHash } = await client.broadcast({
  to: '0x1234...',
  data: '0x',
  value: '1000000000000000000', // 1 ETH in wei (string)
})

API Reference

createSignerClient(config)

Creates a new SignerClient instance.

import { createSignerClient } from '@hightop/signer'

const client = createSignerClient({
  url: string, // Base URL of the signer API
  keyId: string, // API key ID
  keySecret: string, // API key secret
})

Methods

client.sign(params)

Sign a hash using the signer's private key.

const { signature } = await client.sign({
  hash: '0x...', // 32-byte hash to sign
})

client.broadcast(params)

Broadcast a transaction via the Smart Account.

const { txHash } = await client.broadcast({
  to: '0x...',           // Target address
  data: '0x...',         // Calldata
  value?: '0',           // Value in wei (string, optional)
  index?: '0',           // Broadcaster index (string, optional)
})

client.getBroadcasterAddress(params?)

Get the Smart Account broadcaster address.

const { address } = await client.getBroadcasterAddress({
  index?: '0', // Broadcaster index (optional)
})

client.waitForBroadcastReceipt(params)

Wait for a user operation to be included in a block and get the receipt.

const receipt = await client.waitForBroadcastReceipt({
  hash: '0x...', // User operation hash (returned from broadcast)
  timeout?: 30000, // Optional timeout in ms
})

// Receipt contains:
// - actualGasCost: string
// - actualGasUsed: string
// - success: boolean
// - reason?: string (if failed)
// - logs: array of log entries
// - receipt: { transactionHash, blockNumber, blockHash, gasUsed, status }

client.executeSafe(params)

Execute a batch of transactions via Safe.

const { txHash } = await client.executeSafe({
  transactions: [
    { to: '0x...', value: '0', data: '0x...' },
    { to: '0x...', value: '0', data: '0x...' },
  ],
})

client.waitForSafeReceipt(params)

Wait for a Safe user operation to be included in a block and get the receipt.

const receipt = await client.waitForSafeReceipt({
  hash: '0x...', // User operation hash (returned from executeSafe)
  maxAttempts?: 10, // Optional max polling attempts
})

// Receipt contains:
// - success: boolean
// - timestamp?: number
// - receipt: { transactionHash, blockHash, blockNumber }

client.getWallet(params)

Get or create a wallet for a user.

const { wallet } = await client.getWallet({
  userId: 'user-123',
  email: '[email protected]',
})

client.sendAuthCode(params)

Send an auth code to a user's email.

const { otpId } = await client.sendAuthCode({
  userId: 'user-123',
  email: '[email protected]',
})

client.verifyAuthCode(params)

Verify an auth code and get Turnkey credentials.

const { turnKeyCredential } = await client.verifyAuthCode({
  userId: 'user-123',
  otpId: 'otp-id',
  otpCode: '123456',
  targetPublicKey: 'public-key',
})

client.getPkId()

Get the private key ID for the authenticated key.

const { pkId } = await client.getPkId()

Viem Integration

createBroadcasterWallet(config)

Creates a viem WalletClient that broadcasts transactions via the Signer's Smart Account.

import { createBroadcasterWallet } from '@hightop/signer'
import { createPublicClient, http, parseEther } from 'viem'
import { base } from 'viem/chains'

const publicClient = createPublicClient({
  chain: base,
  transport: http(),
})

const wallet = await createBroadcasterWallet({
  url: 'https://signer.example.com',
  keyId: 'your-key-id',
  keySecret: 'your-key-secret',
  chain: base,
  publicClient,
  index: 0n, // optional, defaults to 0n
})

// Send a transaction
const txHash = await wallet.sendTransaction({
  to: '0x...',
  value: parseEther('0.1'),
})

// Write to a contract
const txHash = await wallet.writeContract({
  address: '0x...',
  abi: contractAbi,
  functionName: 'transfer',
  args: [recipient, amount],
})

createSignerAccount(config)

Creates a viem-compatible Account that signs messages via the Signer API.

import { createSignerAccount } from '@hightop/signer'
import { createWalletClient, http } from 'viem'
import { base } from 'viem/chains'

const account = createSignerAccount({
  url: 'https://signer.example.com',
  keyId: 'your-key-id',
  keySecret: 'your-key-secret',
  address: '0x...', // The wallet address
})

// Use with a wallet client
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
})

// Sign a message
const signature = await walletClient.signMessage({
  message: 'Hello, world!',
})

Error Handling

The SDK throws SignerClientError for API errors:

import { SignerClientError } from '@hightop/signer'

try {
  await client.sign({ hash: '0x...' })
} catch (error) {
  if (error instanceof SignerClientError) {
    console.log(error.message) // Error message
    console.log(error.status) // HTTP status code (e.g., 401, 500)
  }
}

Types

All request and response types are exported:

import type {
  SignerClientConfig,
  SignRequest,
  SignResponse,
  BroadcastRequest,
  BroadcastResponse,
  BroadcastAddressRequest,
  BroadcastAddressResponse,
  BroadcastReceiptRequest,
  BroadcastReceiptResponse,
  BroadcastReceiptLog,
  SafeTransaction,
  SafeExecuteRequest,
  SafeExecuteResponse,
  SafeReceiptRequest,
  SafeReceiptResponse,
  WalletRequest,
  WalletResponse,
  AuthCodeSendRequest,
  AuthCodeSendResponse,
  AuthCodeVerifyRequest,
  AuthCodeVerifyResponse,
  PkResponse,
  ErrorResponse,
  BroadcasterWalletConfig,
  SignerAccountConfig,
} from '@hightop/signer'

License

MIT