<!-- https://zunder-design-preview.pages.dev/docs/integrations/typescript-sdk · Markdown version of the page -->

# TypeScript SDK

Put Guard in front of the @nktkas/hyperliquid TypeScript SDK with the transport's apiUrl. The exact options.

:::note[Planned]
Guard 1.0 integration, not verified yet. Written from [`nktkas/hyperliquid`](https://github.com/nktkas/hyperliquid), `src/transport/http/mod.ts` and `README.md` on `main`, read 6 Oct 2026.
:::

Hyperliquid has no official TypeScript SDK. Its API docs list two community SDKs, [`nktkas/hyperliquid`](https://github.com/nktkas/hyperliquid) and [`nomeida/hyperliquid`](https://github.com/nomeida/hyperliquid). This guide covers the first (npm: `@nktkas/hyperliquid`). A guide for the second follows once it is tested.

## Before you change anything

- Read [the setup journey](https://zunder-design-preview.pages.dev/docs/deploy) and start Guard in paper mode.
- Keep your real account address. Give the bot a **Guard client key**, while the API wallet key stays inside Guard.
- Check the network and isolated-margin requirements in this guide. These integration instructions are planned and not verified against a released Guard yet.

## The smallest change

`HttpTransport` takes `apiUrl`: "Custom API URL for `info` and `exchange` requests".

```diff
-const transport = new HttpTransport();
+const transport = new HttpTransport({ apiUrl: "http://127.0.0.1:8547" });
-const wallet = privateKeyToAccount(API_WALLET_KEY);
+const wallet = privateKeyToAccount(GUARD_CLIENT_KEY);
```

## Full example

```ts

const transport = new HttpTransport({ apiUrl: "http://127.0.0.1:8547" });
const wallet = privateKeyToAccount("0x...");   // the client key Guard printed

const info = new InfoClient({ transport });
const exchange = new ExchangeClient({ transport, wallet });
```

## The options

| Option | Value | Default without Guard |
|---|---|---|
| `apiUrl` | Guard's URL | `https://api.hyperliquid.xyz` (mainnet), `https://api.hyperliquid-testnet.xyz` (testnet) |
| `isTestnet` | match Guard's network if you like; see below | `false` |
| `timeout` | leave at the default, or raise it a little | `10_000` ms |
| `wallet` | a viem account from the Guard client key | |

**Network in the signature.** The SDK signs for testnet when `isTestnet` is `true`, otherwise for mainnet. Guard is planned to accept either and to sign the real order for its own network ([why it is safe](https://zunder-design-preview.pages.dev/docs/integrations#one-thing-every-tool-does-differently-the-network-in-the-signature)).

**WebSocket.** The SDK's WebSocket transport is separate. Use it against Hyperliquid directly for market data, or wait for Guard's WebSocket pass-through.

## Read the response

The reply uses Hyperliquid’s response format. Check the returned status and order size rather than assuming the requested size was accepted. A refusal includes a readable reason and a [veto code](https://zunder-design-preview.pages.dev/docs/reference/veto-codes); a smaller accepted order reflects the rule that bound its size. Paper mode sends no venue order. Test this path before using testnet.