Halo SDK

Everything you need to build trading addons for Hyperliquid and publish them to the Halo store. Addons inject directly into app.hyperliquid.xyz — full access to live market data, no CORS headaches, no setup for users.

Overview

ScarCity is a Chrome extension that injects a toolbar into Hyperliquid. Community builders can create addon panels that appear in that toolbar. Every addon is a self-contained HTML/JS file that uses the Halo SDK to access live HL data.

When a user installs your addon, they see it in the ScarCity toolbar. They can open your panel without leaving Hyperliquid. If you've set a tip address, they can voluntarily support your work.

How it works

• You write a panel using the HaloAddon class
• You submit it to ScarCity Labs for review
• After approval, it appears in the Community Store for all users
• Tips route directly to your confirmed EVM wallet — no middleman

Quick Start

The simplest possible addon — a panel that shows the current BTC funding rate:

const addon = new HaloAddon({
  name:        "FundingWatch",
  version:     "1.0.0",
  description: "Live funding rates for any HL perp",
  author:      "yourhandle",
  tip:         "0xYourWallet", // optional — any EVM address
  price:       0,
});

addon.addPanel({
  icon:  "",
  label: "FundingWatch",
  render: async (el, ctx) => {
    const mids = await addon.hl({ type: "allMids" });
    const [meta, ctxs] = await addon.hl({ type: "metaAndAssetCtxs" });

    el.innerHTML = meta.universe.map((m, i) => `
      <div class="rate-row">
        <span>${m.name}</span>
        <span>${(parseFloat(ctxs[i]?.funding) * 100).toFixed(4)}%</span>
      </div>
    `).join("");
  }
});

addon.register();

Addon Structure

An addon is a folder containing at minimum an index.js and an optional panel.html. Submit it as a zip file.

my-addon/
├── index.js       # required — addon logic + SDK usage
├── panel.html     # optional — custom HTML template
├── panel.css      # optional — panel styles
└── README.md      # recommended — describe what your addon does

HaloAddon

The main class. Instantiate once per addon with your configuration.

addPanel()

Registers a panel that appears in the ScarCity toolbar. You can call addPanel multiple times to add multiple panels to a single addon.

The render context (ctx)

The second argument to your render function gives you live context about what the user is doing:

ctx.coin      // "BTC" — coin currently viewed in HL
ctx.wallet    // "0x..." — connected wallet address (if any)
ctx.theme     // "dark" — user's current theme

hl()

Makes a CORS-proxied request to the Hyperliquid API. Use this for all HL data — do not call api.hyperliquid.xyz directly from your panel (CORS will block it).

Market Data Types

All mid prices

const mids = await addon.hl({ type: "allMids" });
// { "BTC": "94230.5", "ETH": "3201.1", ... }

Meta + asset contexts (funding, OI, volume)

const [meta, ctxs] = await addon.hl({ type: "metaAndAssetCtxs" });
// meta.universe[i].name  — coin name
// ctxs[i].funding        — current funding rate
// ctxs[i].openInterest   — open interest
// ctxs[i].dayNtlVlm      — 24h notional volume
// ctxs[i].prevDayPx      — previous day price

Order book (L2)

const book = await addon.hl({ type: "l2Book", coin: "BTC" });
// book.levels[0] — bids array: [{px, sz, n}, ...]
// book.levels[1] — asks array: [{px, sz, n}, ...]

Account Data Types

These require a wallet address — use ctx.wallet or ask the user to paste one.

Account state (balance, positions)

const state = await addon.hl({
  type: "clearinghouseState",
  user: ctx.wallet
});
// state.marginSummary.accountValue
// state.assetPositions[i].position.coin
// state.assetPositions[i].position.szi  — size
// state.assetPositions[i].position.entryPx

Trade history (fills)

const fills = await addon.hl({ type: "userFills", user: ctx.wallet });
// fills[i].coin, fills[i].px, fills[i].sz
// fills[i].side — "B" or "A"
// fills[i].time, fills[i].fee, fills[i].closedPnl

Candles

const candles = await addon.hl({
  type:        "candleSnapshot",
  req: {
    coin:      "BTC",
    interval:  "1h", // 1m 5m 15m 1h 4h 1d
    startTime: Date.now() - 86400000, // 24h ago
    endTime:   Date.now()
  }
});

// Each candle: [timestamp, open, high, low, close, volume]
candles.forEach(c => {
  const [t, o, h, l, close, vol] = c;
  console.log(close); //  correct
});

register()

Security Rules

Every addon is reviewed against these rules before going live. Violations result in rejection.

• No external JS imports. No <script src="https://...">, no CDN, no remote modules.
• No eval() or Function(). Dynamic code execution is not permitted.
• Allowed external API calls: api.hyperliquid.xyz (via addon.hl()), api.anthropic.com (if user provides key).
• No wallet access. Addons cannot request wallet signatures or access private keys.
• No order placement. Addons are read-only. They cannot place, modify, or cancel orders.
• No data exfiltration. User wallet addresses and account data must not be sent to third-party servers.
• Confirmed tip wallet required. You must verify ownership of your tip address before first listing.

Packaging

Submit your addon as a .zip file containing your source. The zip must include your index.js at the root.

# From inside your addon folder:
zip -r my-addon.zip index.js panel.html panel.css README.md

# Verify the structure:
unzip -l my-addon.zip

Review Process

Only ScarCity Labs approves and publishes addons to the store. No self-publishing. Here's what happens after you submit:

1. Submission received — you get a confirmation via the email you provide
2. Manual code review — a human reads your code against the security checklist
3. Static analysis — automated scan for eval(), obfuscated code, network calls to non-allowed domains
4. Identity verification — we confirm your X account and EVM tip wallet
5. Published or rejected — usually within 48 hours. Rejection includes specific feedback.