Developers

API Reference

HookOS exposes a REST API for querying indexed on-chain data. The API is read-only — all write operations go through the SDK or direct contract calls.

Base URL: https://api.hookos.xyz/v1. All endpoints return JSON. Rate limit: 100 requests/minute per API key.

Authentication

Pass your API key in the x-api-key header.

bash

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.hookos.xyz/v1/tokens

Tokens

GET /tokens

List tokens with optional filters.

Param	Type	Description
`chain`	string	Filter by chain (ethereum, base, arbitrum)
`creator`	address	Filter by creator address
`sort`	string	Sort by: volume, marketCap, createdAt
`limit`	number	Results per page (max 100)
`offset`	number	Pagination offset

Response

{
  "tokens": [
    {
      "address": "0x1234...abcd",
      "name": "Momentum Token",
      "symbol": "MOM",
      "chain": "ethereum",
      "creator": "0xCreator...",
      "marketCap": "2450000",
      "volume24h": "180000",
      "hooks": ["afterSwap", "beforeSwap"],
      "createdAt": "2025-03-15T10:30:00Z"
    }
  ],
  "total": 1423,
  "limit": 20,
  "offset": 0
}

GET /tokens/:address

Get detailed information for a single token including attached hooks and price history.

Response

{
  "address": "0x1234...abcd",
  "name": "Momentum Token",
  "symbol": "MOM",
  "chain": "ethereum",
  "totalSupply": "10000000",
  "metadataURI": "ipfs://Qm.../metadata.json",
  "hooks": [
    {
      "hookId": "0xHook...",
      "name": "Burn on Sell",
      "hookPoint": "afterSwap",
      "gasLimit": 500000
    }
  ],
  "price": {
    "usd": "0.245",
    "change24h": 12.5
  }
}

Hooks

GET /hooks

Browse the hook marketplace.

Param	Type	Description
`category`	string	Filter by category (Trading, Reward, Security)
`verified`	boolean	Only show verified hooks
`sort`	string	Sort by: installs, rating, createdAt

GET /hooks/:id

Get hook details including install count, ratings, and revenue stats.

GET /hooks/:id/tokens

List all tokens using a specific hook.

Arena

GET /arena/battles

List battles with optional status filter.

Param	Type	Description
`status`	string	Filter: created, active, settled, cancelled
`token`	address	Filter battles involving a specific token

GET /arena/battles/:id

Get battle details including wagers, price snapshots, and result.

GET /arena/leaderboard

Top performers by win rate and total earnings.

Fees

GET /fees/summary

Get protocol fee summary: total collected, distributed, and pending.

GET /fees/:address

Get fee earnings and claim history for a specific address.

WebSocket

Real-time updates are available via WebSocket at wss://api.hookos.xyz/v1/ws.

typescript

const ws = new WebSocket("wss://api.hookos.xyz/v1/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({
    subscribe: ["tokens", "battles"],
    chain: "ethereum",
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // { type: "token.swap", token: "0x...", ... }
  // { type: "battle.settled", battleId: "...", ... }
};

Rate limits

Plan	Requests/min	WebSocket connections
Free	100	2
Builder	1,000	10
Enterprise	10,000	50

✓

Get your API key from the Developer Portal. Free tier includes 100 requests/minute.

SDK Reference

Smart Contracts