Halcyon docs

Halcyon is an options protocol for Solana and EVM chains. Writers lock collateral and sell options; market makers compete to buy them. Prices are agreed off-chain over a fast quote channel, and the trade is minted and settled on-chain in one transaction.

The SDK is in early development. Expect breaking changes between minor versions.

Packages

Package	What it does
`@halcyon/sdk`	Shared types, quote channel client, REST client
`@halcyon/solana`	Solana program client
`@halcyon/evm`	EVM contract client
`@halcyon/cli`	The `halcyon` command-line tool
`@halcyon/signers`	Cloud KMS signers for server-side keys

Getting started

Install the SDK and the client for your chain:

npm install @halcyon/sdk @halcyon/solana

Create a client. An API key is required, even for read-only calls.

import { Halcyon } from "@halcyon/sdk";
import { solana } from "@halcyon/solana";

const hx = await Halcyon.create({
  apiKey: process.env.HALCYON_KEY,
  chain: solana({ rpc: "https://api.mainnet-beta.solana.com" }),
  wallet,
});

// list supported assets
const assets = await hx.assets.list();

Core concepts

Collateral offer — posted by the writer. Says what is locked and on which terms.
Bid — posted by a market maker in reply. Names a premium the maker will pay.
Position — the on-chain option created when an offer and a bid are matched.
Deterministic IDs — offers and positions get a 32-byte ID hashed from their contents, so both sides can refer to the same thing before it exists on-chain.
Two keys — a chain key signs transactions; a session key signs quote messages so your main wallet stays cold.

Settlement modes

Mode	At expiry	Good for
Physical	The underlying asset changes hands at the strike	Covered calls on assets you're happy to sell
Cash	Only the in-the-money value is paid in stablecoin	Keeping your position while earning premium
Deferred	Maker settles from a credit line within a grace window	Institutional makers with prime accounts

Escrow

All protocol payments move through an on-chain escrow account tied to your wallet. Deposit before you trade; withdraw anything that isn't locked in an open position at any time.

await hx.escrow.deposit({ asset: "USDC", amount: "5000" });
await hx.escrow.authorize(sessionKey.publicKey);

Quote lifecycle

Writer posts a collateral offer on the quote channel.
Makers reply with signed bids within the quote window (default 10s).
Writer accepts the best bid; the SDK builds the match transaction.
The position is minted and premium is paid to the writer in the same transaction.
At expiry, anyone can call settle() to close the position.

const offer = await hx.rfq.offer({
  side: "call", asset: "SOL", strike: 240, expiry: "14d", size: 25,
});
const best = await offer.bestBid({ timeoutMs: 10_000 });
const position = await best.accept();

Build a quoter

Market makers listen for offers and answer with bids. A minimal quoter:

hx.rfq.onOffer(async (offer) => {
  const price = myPricingModel(offer);   // your own model
  if (price) await offer.bid({ premium: price });
});

The quote channel connects lazily on the first listener and reconnects on its own.

CLI

npm install -g @halcyon/cli

halcyon escrow deposit USDC 5000
halcyon offer call SOL --strike 240 --expiry 14d --size 25
halcyon positions list
halcyon quote --bs --vol 0.65      # built-in Black-Scholes quoter
halcyon escrow withdraw USDC 1000

SDK reference

Namespace	Main methods
`hx.assets`	`list()`, `get(symbol)`
`hx.escrow`	`deposit()`, `withdraw()`, `balance()`, `authorize()`
`hx.rfq`	`offer()`, `onOffer()`, `close()`
`hx.positions`	`list()`, `get(id)`, `settle(id)`
`hx.events`	`subscribe(filter)` for indexed protocol events