Developers

SDK Reference

The @hookos/sdk package provides a TypeScript client for interacting with all HookOS contracts. It wraps ethers.js and handles encoding, gas estimation, and event parsing.

Installation

bash

npm install @hookos/sdk ethers

Initialization

typescript

import { HookOS } from "@hookos/sdk";
import { ethers } from "ethers";

const hookos = new HookOS({
  signer: yourSigner,
  network: "ethereum", // or "sepolia", "base", "arbitrum"
});

All write methods require a signer. Read-only methods work with just a provider.

hookos.tokens

Methods for creating and querying tokens.

Method	Returns	Description
`create(opts)`	`TokenResult`	Deploy a new HookToken via TokenFactory
`get(address)`	`TokenInfo`	Get token details including attached hooks
`byCreator(address)`	`TokenInfo[]`	List all tokens created by an address
`search(query)`	`TokenInfo[]`	Search tokens by name, symbol, or attributes

tokens.create()

interface CreateTokenOptions {
  name: string;
  symbol: string;
  initialSupply: bigint;
  metadataURI?: string;
}

interface TokenResult {
  address: string;
  txHash: string;
  blockNumber: number;
}

hookos.hooks

Methods for registering, attaching, and querying hooks.

Method	Returns	Description
`register(opts)`	`string`	Register a hook on-chain, returns hook ID
`attach(opts)`	`TxResult`	Attach a hook to a token at a specific hook point
`detach(opts)`	`TxResult`	Remove a hook from a token
`list(token)`	`HookBinding[]`	List all hooks attached to a token
`get(hookId)`	`HookInfo`	Get hook metadata and stats
`browse(filters)`	`HookInfo[]`	Browse the hook marketplace

hooks.register()

interface RegisterHookOptions {
  name: string;
  category: string;
  implementation: string; // deployed contract address
  metadataURI: string;
}

interface HookBinding {
  hookId: string;
  hookPoint: HookPoint;
  gasLimit: number;
  active: boolean;
}

type HookPoint =
  | "beforeSwap"
  | "afterSwap"
  | "beforeAddLiquidity"
  | "afterAddLiquidity"
  | "beforeRemoveLiquidity"
  | "afterRemoveLiquidity";

hookos.arena

Methods for PvP battles and wagering.

Method	Returns	Description
`create(opts)`	`BattleResult`	Create a new battle between two tokens
`wager(opts)`	`TxResult`	Place a wager on a battle side
`settle(id)`	`TxResult`	Settle a completed battle
`claim(id)`	`bigint`	Claim winnings from a settled battle
`cancel(id)`	`TxResult`	Cancel a battle before it starts

hookos.fees

Methods for querying fee distributions.

Method	Returns	Description
`getShares()`	`FeeShares`	Get current fee split configuration
`pending(address)`	`bigint`	Check unclaimed fees for an address
`claim()`	`TxResult`	Claim pending fee rewards

Error handling

The SDK throws typed errors for common failure modes.

typescript

import { HookOSError, InsufficientGasError } from "@hookos/sdk";

try {
  await hookos.tokens.create({ ... });
} catch (err) {
  if (err instanceof InsufficientGasError) {
    console.error("Not enough gas:", err.required);
  } else if (err instanceof HookOSError) {
    console.error("HookOS error:", err.code, err.message);
  }
}

Events

Subscribe to on-chain events using the SDK event listener.

typescript

hookos.on("TokenCreated", (event) => {
  console.log("New token:", event.tokenAddress);
});

hookos.on("HookExecuted", (event) => {
  console.log("Hook fired:", event.hookId, event.success);
});

hookos.on("BattleSettled", (event) => {
  console.log("Winner:", event.winner);
});

Arena

API Reference