Core Concepts

Tokens

Every token on HookOS is an ERC-20 deployed through the TokenFactory contract. At deploy time, the factory registers the token on-chain and optionally attaches hooks from the HookRegistry. Tokens are fully standard ERC-20s with hook extension points.

Creating a token

Use the SDK or call the TokenFactory directly. The factory deploys a new HookToken contract, mints the initial supply to the creator, and emits a TokenCreated event.

src/create-token.ts

const token = await hookos.tokens.create({
  name: "Momentum Token",
  symbol: "MOM",
  initialSupply: ethers.parseEther("10000000"),
  metadataURI: "ipfs://QmYour.../metadata.json",
});

console.log("Address:", token.address);
console.log("Tx:", token.txHash);

Token metadata

Metadata is stored off-chain (IPFS or Arweave) and referenced by a URI on-chain. The metadata JSON follows a standard schema:

metadata.json

{
  "name": "Momentum Token",
  "symbol": "MOM",
  "description": "A deflationary token with MEV protection.",
  "image": "ipfs://QmImage.../logo.png",
  "external_url": "https://momentum.xyz",
  "attributes": {
    "category": "DeFi",
    "chain": "ethereum"
  }
}

Hook bindings

After deployment, tokens can have hooks attached or detached by the token owner. Each binding connects a hook to a specific hook point on that token.

typescript

// Attach a hook
await hookos.hooks.attach({
  token: token.address,
  hookId: "0x...",
  hookPoint: "afterSwap",
});

// Detach a hook
await hookos.hooks.detach({
  token: token.address,
  hookId: "0x...",
});

// List active hooks
const bindings = await hookos.hooks.list(token.address);

Tokens can have up to 8 hooks attached simultaneously. Hooks execute in the order they were attached.

Token lifecycle

Phase	Action	Who
Deploy	TokenFactory creates the ERC-20 and registers it	Creator
Configure	Attach hooks, set metadata, configure parameters	Creator
Launch	Add initial liquidity to the pool	Creator
Trade	Swaps trigger attached hooks at each hook point	Anyone
Manage	Attach/detach hooks, update metadata	Creator

Querying tokens

The SDK provides methods to query tokens by creator, chain, or metadata attributes.

typescript

// Get all tokens by a creator
const tokens = await hookos.tokens.byCreator(
  "0xCreatorAddress..."
);

// Get token details
const info = await hookos.tokens.get(tokenAddress);
console.log(info.name, info.symbol, info.hooks);

// Search tokens
const results = await hookos.tokens.search({
  query: "momentum",
  chain: "ethereum",
  limit: 20,
});

Fees

Token creation costs 0.005 ETH (configurable by admin). This launch fee is forwarded to the FeeRouter when set. Ongoing protocol fees are collected on every swap and distributed automatically:

50% — Protocol treasury
30% — Hook authors (proportional to usage)
20% — LP rewards

Swap fees are perpetual — they are collected on every trade for as long as the token is being traded. This is the core recurring revenue engine for hook authors.

Hooks

Arena