Support external/remote signing (KMS/HSM) without an in-process private key

[developerAkX]

Problem

Today the only way to authorize state-changing actions (orders, cancels, modify, withdraw, etc.) is WithPrivateKey, which loads a raw private key into the SDK process and signs in-process inside buildSignSend via Wallet.SignHash. If no key is set, requireWallet() panics.

This rules out setups where the key must never enter the application process — KMS/HSM-backed signing, or a dedicated remote signing service. In those architectures the application is the largest attack surface, and the security goal is that a compromise of that process cannot exfiltrate the key.

Use case

We run a separation-of-duties design: a hardened, minimal signing service holds the keys; our user-facing service must hold none. We still want to use this SDK for order construction/submission, signing each build-step hash via the remote signer.

Proposed solution

Add an external-signer seam alongside WithPrivateKey — a callback that receives the build-step hash and returns the existing Signature:

type Signer func(hashHex string) (*Signature, error)

func WithSigner(fn Signer) Option
func WithSignerAddress(addr string) Option // acting address when no in-process wallet

buildSignSend calls the signer when set, else falls back to Wallet.SignHash. Fully backward compatible — WithPrivateKey is unchanged when no signer is provided.

I have a small, additive implementation with tests and a README section ready and will open a PR referencing this issue. Happy to adjust the API (naming, signature shape) to your preferences.

[yaanakbr]

Hey @developerAkX thanks for this PR! We will review, and probably add it across the other languages to provide parity :) really appreciate the little feature here

[developerAkX]

You can just drop a comment after reviewing. I can add this feature to other languages too. No problem. I really appreciate your quick reply.

[yaanakbr]

@developerAkX LGTM! I really appreciate you adding the other languages! Let me know when its done and I can stamp it 😄

[developerAkX]

Hey @yaanakbr — the other-language work is done and pushed to #18, ready whenever you want to take a look 🙌

I want to be transparent about a few things I added on top of the original Go-only proposal. Because this signer seam is brand new and nobody depends on it yet, I used the chance — while we're still free to shape the API without breaking anyone — to round it out properly. The alternative is shipping the bare minimum now and being forced into breaking changes later once people build on it.

1. The same feature in all four SDKs (parity)
The external signer now works identically in Go, Python, Rust, and TypeScript:

• Go: WithSigner / WithSignerAddress
• Python: signer= / signer_address=
• Rust: a HyperliquidSigner trait, passed via .signer() on the builder
• TypeScript: signer / signerAddress options

2. A dedicated error for signer failures
Right now a signing problem surfaces as SignatureError, which means "the exchange rejected your signature." But with a remote signer, the failure could instead be "your KMS/HSM/remote service was unreachable or errored" — a completely different problem with a different fix. So I added a separate SignerError (code SIGNER_FAILED) for that case, with the original error attached underneath for inspection. Now you can immediately tell whether the venue rejected you or your own signer broke.

3. A timeout / cancellation for the signer call
A remote signer can hang (it's a network call to KMS/HSM). So each signer call is now bounded by a deadline and can be cancelled, using each language's native mechanism (Go context, Rust signer_deadline, TypeScript AbortSignal). This one in particular needs to land now: adding a deadline parameter to the callback later would change its signature and break everyone already using it.

4. Builder-fee auto-approval is skipped when a signer is used
Some background: normally, on startup the SDK automatically signs a one-time "builder fee" approval for you. That step needs a private key inside the process — which is the exact thing an external signer is designed to avoid. So when a signer is configured, the SDK simply doesn't attempt that automatic approval. If you want builder fees, you call approveBuilderFee() once yourself. This is documented in each README.

5. A small convenience in Go's PlaceOrder
This one is unrelated to signing — I just fixed it while I was in the file. PlaceOrder was ignoring a per-order slippage value that the builder already accepted; it now respects it, matching how the other order paths already behave. Happy to pull this out into its own PR if you'd prefer to keep this one strictly about signing.

None of this is a breaking change. Every addition is opt-in. If you don't pass a signer, the SDK behaves exactly as before — WithPrivateKey / private_key / the PRIVATE_KEY env path are untouched. Existing users notice no difference.

Tests and README sections are included for all four SDKs. Glad to rename, trim, or split anything to your preference — just say the word!