Skip to main content
@totalis/hip4-client is the official TypeScript SDK for Totalis on Hyperliquid. It wraps every route with typed requests and responses, runs the taker and maker flows end to end, builds every signed message, and keeps a WebSocket in sync. It never holds a key: every signature goes to the signer you pass in.

Install

The package is public on npm under Apache-2.0. It is ESM and has no wallet dependency. viem (or ethers) is only there to turn a private key into a signer.
The package used to be @totalistrading/hip4-client, and versions up to 0.65.0 were published to GitHub Packages under that name. Change your imports to @totalis/hip4-client, and remove any @totalistrading:registry=https://npm.pkg.github.com line from your .npmrc.

Runtimes

On React Native, install react-native-get-random-values and import it once, before the SDK:
React Native has no secure random source of its own. The SDK needs one for request IDs, idempotency keys and signed nonces, and throws an error naming the package if it is missing. Most wallet libraries need it too. A partner server key (tpk_) is a secret, so createPartnerServer runs only on a server, never in a browser or an app.

Make a first call

Create a ttk_ API key for your account (Create, rotate, revoke), then read your account:
Every route in the API reference is on client, with its path, parameters and response typed. unwrap returns the body or throws an ApiError.

Pick a client

createTotalis and createMaker each carry a typed client and a stream too, so you rarely need more than one.

Environments

Staging runs on Hyperliquid testnet (Staging). To point at another origin, pass baseUrl. It serves the streams too unless you also set streamBaseUrl.

Options

Every client takes the same options. createMaker takes apiKey (the maker’s ttk_ key) and makerId in place of accessToken. A signer can be a viem account or wallet client, an EIP-1193 provider such as window.ethereum, or an ethers signer. toTotalisSigner, from .../signer, converts any of them yourself when you need to.

Conventions

  • Money is atomic USDC (6 decimals), as a bigint or a decimal string. 25_000_000n is 25 USDC.
  • Time comes from the venue. Deadlines such as accept_before and fund_by are judged on the venue clock, which stream.serverNow() gives you.
  • Commands are idempotent. Each one is built once with its Idempotency-Key and resent byte for byte, so a retry never trades twice.
  • Clean up. Call close() on createTotalis and createMaker when you are done, to stop their streams.

Entry points

Examples

The package ships runnable examples in node_modules/@totalis/hip4-client/examples. The SDK follows semver. What changed in each release is on the Changelog.