# Somnia Markets

> On-chain order books for spot, binary and perpetual markets on Somnia: one matching engine, settled and resolved on-chain, with a typed SDK.

Somnia Markets is a decentralized information and trading protocol on
[Somnia](https://somnia.network): one fully on-chain central limit order-book
engine runs every market family — **spot** pairs, **binary** information
markets, and **perps** — alongside a realtime on-chain index-price feed.
Everything is on-chain and permissionless: order matching, escrow, settlement,
market creation (per-venue), and resolution. The APIs below are conveniences
over the same public contracts — nothing they do is privileged.

**Spot markets** are plain base/quote order books (e.g. SOMI/USDC), each pool
pushing a smoothed on-chain mark price straight from its own book.

**Binary markets** are the information leg: a YES/NO question — such as an
asset above a strike at expiry — whose outcome shares trade on the book at
prices that *are* probabilities, so each book doubles as a live on-chain
forecast. Shares are ERC-6909 positions backed 1:1 by collateral: a complete
set (1 YES + 1 NO) always mints from and merges back to exactly one collateral
unit, the winning side redeems 1:1 at resolution, and resolution itself is
driven on-chain by the Prophecy oracle through Somnia's reactivity — no
operator in the loop. Each market carries an on-chain kind tag
(`marketType()`); future kinds (multi-outcome, dual-book) extend the same
protocol.

**Perps** are linear, collateral-settled perpetuals — cross-margin via the
MarginBank, on-chain funding and liquidations — live on testnet.

## Ways to integrate

**The TypeScript SDK — `@somnia-chain/markets-sdk`.** The fastest path for
apps and bots in a JS runtime: realtime order books, trades, candles, and
positions streamed with zero polling, plus a typed trader for placing orders,
managing margin, and minting/redeeming outcome shares. Start with
[The SDK](./typescript), then
[The exchange API](./typescript/exchange); the per-family guides —
[Spot markets](./typescript/spot),
[Binary markets](./typescript/binary),
[Perps](./typescript/perps) — cover what differs per kind, and
[Architecture](./typescript/architecture) explains how it works
under the hood. The generated
[API reference](https://prd.smk.somnia.host/docs/typescript/api) lists every
exported function, hook and type.

**Raw smart contracts — no SDK.** Any language, any runtime, nothing but an
RPC node and the ABIs: discover markets, place orders, and materialize a live
local order book straight from contract events.
[Raw Smart-Contract Integration](./contracts) is the end-to-end guide;
[Market Making](./market-making) covers what is venue-specific for
quoting operations — book encoding, escrow semantics, event caveats, market
lifecycle.

## Going deeper

- The [System page](https://explorer.somnia.network/markets/system) is the live deployment view: every protocol
  contract with its address, owner, and implementation, plus indexer health.
- The API reference in the sidebar is generated from the SDK source (TypeDoc).
- These docs are also served machine-readable at [`/llms.txt`](https://explorer.somnia.network/markets/llms.txt) and
  [`/llms-full.txt`](https://explorer.somnia.network/markets/llms-full.txt).

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.