HIP-4 SDK quickstart: install, authenticate, and trade

pnpm add @outcome.xyz/hip4

import { createHIP4Adapter } from "@outcome.xyz/hip4";

const hip4 = createHIP4Adapter({ testnet: true });
await hip4.initialize();

import type { DefaultBinaryMarket } from "@outcome.xyz/hip4";

const markets = (await hip4.events.fetchMarkets({
  type: "defaultBinary",
})) as DefaultBinaryMarket[];

for (const market of markets) {
  console.log(market.underlying); // "BTC"
  console.log(market.targetPrice); // 69070
  console.log(market.expiry); // Date object
  console.log(market.period); // "1d"
  console.log(market.sides[0].coin); // "#5160"  (Yes side)
  console.log(market.sides[1].name); // "No"
}

import {
  getAgentApprovalTypedData,
  submitAgentApproval,
} from "@outcome.xyz/hip4";
import { createWalletClient, http } from "viem";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import { arbitrum } from "viem/chains";

// Your user's main wallet (from environment - never hardcode private keys)
const userAccount = privateKeyToAccount(
  process.env.PRIVATE_KEY as `0x${string}`,
);
const walletClient = createWalletClient({
  account: userAccount,
  chain: arbitrum,
  transport: http(),
});

// Generate a fresh ephemeral agent key
const agentPrivateKey = generatePrivateKey();
const agentAccount = privateKeyToAccount(agentPrivateKey);

// Build the EIP-712 approval payload and have the user sign it
const nonce = Date.now();
const typedData = getAgentApprovalTypedData(
  agentAccount.address,
  "My App",
  nonce,
  false, // false = testnet
);

const signature = await walletClient.signTypedData({
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
});

// Submit the approval to the Hyperliquid exchange
const approval = await submitAgentApproval(
  signature,
  agentAccount.address,
  "My App",
  nonce,
  false, // false = testnet
);

if (!approval.success) {
  throw new Error(`Agent approval failed: ${approval.error}`);
}

// Initialize the adapter with the approved agent
await hip4.auth.initAuth(userAccount.address, agentAccount);

console.log(hip4.auth.getAuthStatus().status); // "ready"

import { getMinShares } from "@outcome.xyz/hip4";
import type { DefaultBinaryMarket } from "@outcome.xyz/hip4";

// Pick a market (reusing the list from step 3)
const market = markets[0] as DefaultBinaryMarket;

// Fetch the current mid price for min-shares validation
const priceData = await hip4.marketData.fetchPrice(String(market.outcomeId));
const markPx = parseFloat(priceData.outcomes[0]?.midpoint ?? "0.5");

// Place a limit buy on the Yes side
const result = await hip4.trading.placeOrder({
  marketId: String(market.outcomeId),
  outcome: market.sides[0].coin, // Yes side coin, e.g. "#5160"
  side: "buy",
  type: "limit",
  price: String(markPx),
  amount: String(getMinShares(markPx)), // minimum shares for 10 USDC notional
  markPx, // enables pre-submission min-shares check
});

if (result.success) {
  console.log("Order status:", result.status);
  if (result.orderId) console.log("Order ID:", result.orderId);
  if (result.shares) console.log("Filled shares:", result.shares);
} else {
  console.error("Order rejected:", result.error);
}