npm package: @hightop/signer
Description: TypeScript SDK for Hightop Signer API
Latest version: 0.1.1

# @hightop/signer

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

## Installation

```bash
npm install @hightop/signer viem
```

## Quick Start

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

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

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

##### `client.broadcast(params)`

Broadcast a transaction via the Smart Account.

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

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

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

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

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

```typescript
const { wallet } = await client.getWallet({
  userId: 'user-123',
  email: 'user@example.com',
})
```

##### `client.sendAuthCode(params)`

Send an auth code to a user's email.

```typescript
const { otpId } = await client.sendAuthCode({
  userId: 'user-123',
  email: 'user@example.com',
})
```

##### `client.verifyAuthCode(params)`

Verify an auth code and get Turnkey credentials.

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

```typescript
const { pkId } = await client.getPkId()
```

## Viem Integration

### `createBroadcasterWallet(config)`

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

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

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

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

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