PrivySigner config is complex and underdocumented

[owizdom]

Issue

PrivySigner requires a PrivySignerConfig with 7 fields. The type definition doesn't explain the relationships between them or show a working example:

interface PrivySignerConfig {
  walletId: string;
  publicKey: string;
  serverUrl?: string;
  rawSign?: (hash: string) => Promise<string>;
  headers?: Record<string, string>;
  buildBody?: (hash: string) => Record<string, unknown>;
  requestTimeoutMs?: number;
}

Questions I had to answer by reading SDK source

• Do I provide serverUrl OR rawSign? (Answer: one or the other)
• What format does rawSign expect? Hex string? BigInt? (Answer: hex)
• Is publicKey the Stark key or the Privy wallet's key?
• What does the signing endpoint request/response look like?

Suggested fix

A cookbook example showing the full Next.js + Privy flow:

1. Frontend: usePrivy() login → get wallet ID
2. Backend: /api/wallet/sign endpoint that signs with Privy server SDK
3. SDK: onboard() with OnboardStrategy.Privy pointing to that endpoint

This would save every Privy integrator hours of trial-and-error.

Context

Found while building Zapp — email-native transfers using Privy for gasless claims. Full writeup: SDK_ISSUES.md

[0xLucqs]

I agree the privy integration is clunky. The web and mobile example were supposed to help but i guess they're too messy. What API would you have liked to have for privy ?