halon-sdk

TypeScript SDK for HALON — on-chain insurance for autonomous agents.

Quote a premium, read the policy book, inspect executor reliability, and drive the ProofOfWork milestone escrows. Every call is a direct contract read or write through viem.

There is no API key. There is no HALON server in the path — nothing to sign up for, nothing to rate-limit you. If you can reach an RPC endpoint, you can use this SDK. Reads need no wallet at all.

npm install halon-sdk viem

viem is a peer dependency, so you control the version and only one copy ends up in your bundle.

Quick start

import { createHalon, toUsdc, fromUsdc } from "halon-sdk";

// Defaults to Robinhood Chain testnet (46630) with the live deployment baked in.
const halon = createHalon();

// Price $250 of cover on an executor with a 82% reliability index, 12h tenor.
const quote = await halon.getQuote({
  reliabilityBps: 8200,
  coverage: toUsdc(250),
  tenorHours: 12,
});

if (!quote.insurable) {
  console.log("declined:", quote.decline); // e.g. "BelowFloor"
} else {
  console.log("premium:", fromUsdc(quote.premium));
  console.log("rate:", Number(quote.rateBps) / 100, "%");
  console.log("ceded to layer 2:", Number(quote.cededShareBps) / 100, "%");
}

The premium comes from the same RiskEngine the pool binds against, so what you are quoted is what the pool will charge.

Reading the book

const pool = await halon.getPool();
// { totalCapital, lockedCapital, freeCapital, premiumsEarned,
//   claimsPaid, recoveredTotal, utilizationBps, policiesWritten, underReserved }

const policies = await halon.listPolicies();
const mine = await halon.policiesOf("0xYourWallet…");

inForce is not status === "Armed"

A policy stays Armed after expiresAt until somebody pays gas to settle() it. Reading the status enum alone therefore reports lapsed cover as live. Every Policy carries a derived inForce that is status and time:

const live = policies.filter((p) => p.inForce);

Executors

Reliability is the input the premium is priced off, and it lives on-chain:

const agents = await halon.getAgents();
for (const a of agents) {
  console.log(a.handle, a.reliabilityBps / 100 + "%");
}

const quote = await halon.getQuote({
  reliabilityBps: (await halon.getAgent("0xExecutor…"))!.reliabilityBps,
  coverage: toUsdc(1000),
  tenorHours: 24,
});

Cover below a 60% reliability floor is declined — insurable: false, decline: "BelowFloor".

Escrows (ProofOfWork)

const projects = await halon.projectsOf("0xYourWallet…");

for (const p of projects) {
  for (const m of p.milestones) {
    if (m.claimable) console.log("ready to claim:", m.description);
  }
}

claimable means both the AI reviewer and the client have signed off and the money has not moved yet.

Price feeds: check isLiveFeed

Where a network has no real Chainlink feed for an asset, the deployment uses a stub. The stub answers a fixed price forever. This SDK will not pretend otherwise:

const feed = await halon.getPriceFeed();
if (!feed.isLiveFeed) {
  // Static reference value — do NOT present it as a market quote or size with it.
}

The check is real: production aggregators implement description(), the stub does not.

Collateral valuation deliberately reverts on a stale feed rather than returning a stale number:

try {
  const usd = await halon.getCollateralValueUSD(project);
} catch {
  // Feed is stale. Surface "unpriced" — do not substitute a guess.
}

Writing

Pass a walletClient to enable writes. Without one, write methods throw with a clear message instead of failing deep inside a transaction.

import { createWalletClient, custom } from "viem";
import { createHalon, robinhoodTestnet, toUsdc } from "halon-sdk";

const walletClient = createWalletClient({
  chain: robinhoodTestnet,
  transport: custom(window.ethereum),
  account: "0xYourWallet…",
});

const halon = createHalon({ walletClient });

// Fund a milestone escrow
await halon.approve(usdgAddress, halon.addresses.escrowFactory!, toUsdc(5000));
await halon.createProject({
  freelancer: "0xFreelancer…",
  collateralToken: usdgAddress,
  totalAmount: 5000n * 10n ** 18n,
  // omit priceOracle for stablecoin collateral — valued 1:1, no feed involved
});

Permissions are real

Some writes are role-gated on-chain and will revert without the role. The SDK does not hide this:

| Method | Who can call it | | --- | --- | | depositCapital | CAPITAL_ROLE only — capital is permissioned, there are no LP shares | | settle | anyone, but only once the claim window has closed | | createProject / addMilestone / approveMilestone | the project's client | | releaseMilestone | anyone, once both approvals are in |

Binding a policy (bindDirect) requires UNDERWRITER_ROLE and is not exposed here — pools bind their own cover.

Units

Pool money is a 6-decimal token; every money field is a bigint in base units. Floats never touch an on-chain amount.

toUsdc(1.25);       // 1250000n
fromUsdc(1250000n); // 1.25  — display only

Custom deployments

import { createHalon, robinhoodTestnet } from "halon-sdk";

const halon = createHalon({
  chain: robinhoodTestnet,
  rpcUrl: "https://your-rpc",
  addresses: { policyPool: "0x…", usdc: "0x…" },
});

Addresses for a known chain are filled in automatically and can be overridden field by field.

Status

The bundled addresses are a testnet deployment on Robinhood Chain (46630). Tokens there are freely mintable and the price feed is a stub, so no balance represents value. The API is pre-1.0 and may change.

License

MIT