Approve agent keys and initialize HIP-4 auth

The auth adapter (hip4.auth) manages the agent key lifecycle for HIP-4 prediction trading. Rather than prompting the user to sign every individual order, HIP-4 uses an ephemeral agent keypair that you approve once via the user’s wallet. After approval, the agent key signs all orders and USDH spot trades silently on the user’s behalf. The adapter tracks the current auth state and exposes it synchronously so your UI can react to changes without awaiting async calls.

`HIP4Signer` interface

The signer argument you pass to initAuth must implement HIP4Signer:

interface HIP4Signer {
  getAddress(): string | Promise<string>;
  signTypedData(
    domain: Record<string, unknown>,
    types: Record<string, Array<{ name: string; type: string }>>,
    value: Record<string, unknown>,
  ): Promise<HLSignature | string>;
}

initAuth accepts:

viem PrivateKeyAccount (from privateKeyToAccount), which the SDK wraps to match HIP4Signer
ethers v6 Wallet or Signer, which has getAddress() and signTypedData()
Any other object with getAddress() and signTypedData() that returns a hex string or { r, s, v } object

Note that signer here is the agent key, not the user’s wallet. The agent has a different address from the user’s wallet by design.

Methods on `adapter.auth`

`initAuth(walletAddress, signer)`

Stores the agent signer for use by the trading and wallet adapters and sets the state to "ready". It doesn’t check that Hyperliquid has approved the agent; an unapproved agent’s orders are rejected by the exchange. Throws if signer isn’t an object with a signTypedData() method.

const state = await hip4.auth.initAuth(walletAddress, agentSigner);
// state.status === "ready"
// state.address === walletAddress

Parameter	Type	Description
`walletAddress`	`string`	The user’s wallet address (not the agent address)
`signer`	`HIP4Signer`	The agent keypair signer that will sign orders

Returns Promise<PredictionAuthState>.

`getAuthStatus()`

Returns the current auth state synchronously. Use this to gate UI elements or order flows.

const status = hip4.auth.getAuthStatus();
// { status: "disconnected" | "pending_approval" | "ready", address?: string }

Status	Meaning
`"disconnected"`	No agent signer stored (initial state, or after `clearAuth()`)
`"pending_approval"`	Part of the type, but `initAuth` moves straight to `"ready"`
`"ready"`	`initAuth` stored an agent signer; the SDK signs orders with it

`clearAuth()`

Resets the auth adapter to "disconnected" state. Call this on user logout or when the agent key is rotated.

hip4.auth.clearAuth();

Standalone functions

These functions are exported from @outcome.xyz/hip4 and are used to create and submit the one-time agent approval before calling initAuth.

`getAgentApprovalTypedData(agentAddress, agentName, nonce, isMainnet?)`

Builds the EIP-712 typed data object for the user to sign when approving an agent.

Parameter	Type	Description
`agentAddress`	`string`	The agent keypair’s public address
`agentName`	`string`	A human-readable label shown in the approval prompt
`nonce`	`number`	Timestamp (use `Date.now()`) to prevent replay
`isMainnet`	`boolean`	`true` (default) for mainnet, `false` for testnet. This default doesn’t follow the adapter, which targets testnet unless you pass `testnet: false`.

Returns an object with domain, types, primaryType, and message, ready for walletClient.signTypedData.

`submitAgentApproval(signature, agentAddress, agentName, nonce, isMainnet?, exchangeUrl?)`

Submits the signed agent approval to Hyperliquid. After this call succeeds, the agent can sign orders on the user’s behalf.

Parameter	Type	Description
`signature`	`string`	The EIP-712 signature from the user’s wallet
`agentAddress`	`string`	The agent keypair’s public address
`agentName`	`string`	Must match the value used in `getAgentApprovalTypedData`
`nonce`	`number`	Must match the value used in `getAgentApprovalTypedData`
`isMainnet`	`boolean`	`true` (default) for mainnet, `false` for testnet. Must match
`exchangeUrl`	`string`	Optional override for the Hyperliquid `/exchange` endpoint

Returns Promise<{ success: boolean; error?: string }>. It doesn’t throw: network errors come back as success: false. Check success before proceeding to initAuth.

Builder fee approval

Before orders can carry your builder fee, the user must approve a maximum fee rate for your builder address. The flow mirrors agent approval: build the typed data, have the user’s wallet sign it, then submit it. Hyperliquid lets one address approve up to 10 builders.

import {
  getBuilderFeeApprovalTypedData,
  submitBuilderFeeApproval,
} from "@outcome.xyz/hip4";

const nonce = Date.now();
const maxFeeRate = "0.1%"; // a percentage string; 0.1% = builderFee 100

const typedData = getBuilderFeeApprovalTypedData(
  "0xYourBuilderAddress",
  maxFeeRate,
  nonce,
  true, // isMainnet
);
const sig = await walletClient.signTypedData({
  account: userAccount,
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
});
const result = await submitBuilderFeeApproval(
  sig,
  "0xYourBuilderAddress",
  maxFeeRate,
  nonce,
  true, // isMainnet, must match
);

getBuilderFeeApprovalTypedData(builderAddress, maxFeeRate, nonce, isMainnet?) and submitBuilderFeeApproval(signature, builderAddress, maxFeeRate, nonce, isMainnet?, exchangeUrl?) take the same isMainnet flag (default true) as the agent functions. submitBuilderFeeApproval returns Promise<{ success: boolean; error?: string }>. To check an existing approval, call hip4.client.fetchMaxBuilderFee(user, builder), which returns the approved fee in tenths of a basis point (0 if none).

Full agent approval flow

The following example shows the complete setup using viem. You run this flow once for each new agent key.

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import {
  createHIP4Adapter,
  getAgentApprovalTypedData,
  submitAgentApproval,
} from "@outcome.xyz/hip4";

// 1. Generate an ephemeral agent keypair
const agentKey = generatePrivateKey();
const agent = privateKeyToAccount(agentKey);

// 2. Build the typed data for the user to sign
const nonce = Date.now();
const typedData = getAgentApprovalTypedData(
  agent.address,
  "My App",
  nonce,
  true, // isMainnet, matching testnet: false below
);

// 3. Ask the user's wallet to sign it
// (userAccount: the user's viem account; walletClient: a viem WalletClient)
const sig = await walletClient.signTypedData({
  account: userAccount,
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
});

// 4. Submit the approval to Hyperliquid
const approval = await submitAgentApproval(sig, agent.address, "My App", nonce, true);
if (!approval.success) {
  throw new Error(`Agent approval failed: ${approval.error}`);
}

// 5. Initialize the auth adapter with the agent signer
const hip4 = createHIP4Adapter({ testnet: false });
await hip4.initialize();
await hip4.auth.initAuth(userAccount.address, agent);

// Auth is now ready - place orders without prompting the user
console.log(hip4.auth.getAuthStatus());
// { status: "ready", address: "0xUserWalletAddress" }

The agent’s address differs from the user’s wallet address. The SDK does not validate that they match - this is intentional, since the agent signs on behalf of the user.

Get Started

Concepts

Adapters

Utilities

Rewards

Changelog

Approve agent keys and initialize HIP-4 auth

`HIP4Signer` interface

Methods on `adapter.auth`

`initAuth(walletAddress, signer)`

`getAuthStatus()`

`clearAuth()`

Standalone functions

`getAgentApprovalTypedData(agentAddress, agentName, nonce, isMainnet?)`

`submitAgentApproval(signature, agentAddress, agentName, nonce, isMainnet?, exchangeUrl?)`

Builder fee approval

Full agent approval flow

​HIP4Signer interface

​Methods on adapter.auth

​initAuth(walletAddress, signer)

​getAuthStatus()

​clearAuth()

​Standalone functions

​getAgentApprovalTypedData(agentAddress, agentName, nonce, isMainnet?)

​submitAgentApproval(signature, agentAddress, agentName, nonce, isMainnet?, exchangeUrl?)

​Builder fee approval

​Full agent approval flow

`HIP4Signer` interface

Methods on `adapter.auth`

`initAuth(walletAddress, signer)`

`getAuthStatus()`

`clearAuth()`

Standalone functions

`getAgentApprovalTypedData(agentAddress, agentName, nonce, isMainnet?)`

`submitAgentApproval(signature, agentAddress, agentName, nonce, isMainnet?, exchangeUrl?)`

Builder fee approval

Full agent approval flow