Hadal
Start trading
  • OverviewStart
  • QuickstartStart
  • What is sealed and what is seenStart
  • Sealed balancesConcepts
  • Sealed ordersConcepts
  • The book and the pool's midConcepts
  • DealsConcepts
  • SoundingsConcepts
Concepts

Soundings

A sounding puts a market's price, volume and protocol fees for one interval on chain, and is the only trading data Hadal makes public.

A sounding is the one moment a market's sealed book speaks. The cluster reads the pool, reveals five figures for the interval since the previous sounding, and starts the next interval. Every price and volume the app and the HTTP API show comes from soundings.

What a sounding reveals

FigureUnitMeaning
pricepriceThe pool's mid at the moment of the sounding.
crossedquote atomsThe volume that crossed in the interval.
sweptquote atomsThe volume that swept the pool's curve in the interval.
fee_basebase atomsProtocol fees accrued in the interval, in the base token.
fee_quotequote atomsProtocol fees accrued in the interval, in the quote token.

The program records them on the market's account and emits them in a Sounding event with the market, the sounding's index (counted from 1), its slot and its time in Unix seconds, UTC.

Nothing else leaves the book. The pool's reserves, the resting orders, each fill and which orders traded stay sealed. The four interval figures are reset to zero inside the book by the same computation, so each sounding covers its own interval and no other.

The interval

A sounding is taken once a minute. The interval is counted on chain in slots: 300 of them. The value in force is the sounding_interval of the program's Config account, served as soundingIntervalSlots by GET /v1/markets/:market/config.

Taking a sounding is the sound instruction, and any wallet may send it. The program refuses it in three cases.

Refused withWhen
TooEarlyFewer slots than the interval have passed since the market's last sounding.
MarketNotReadyThe market's pool is not open yet.
BusyAnother computation is in flight on the market's book. The sounding is sent again when it has landed.

The interval is counted from the slot in which the previous sounding landed, so two soundings of a market are never closer than the interval. A market's first sounding can be taken one interval after its pool opens.

The price

The price is the pool's mid: the pool's quote reserve divided by its base reserve, as a price in the program's unit (see Units). It is the same mid every cross in the book trades at, told in The book and the pool's mid.

It is read at the moment of the sounding. It is the pool's state after every order processed before it, and it is no average over the interval.

Volumes

Both volumes are counted in atoms of the market's quote token.

Crossed is the sum of:

  • every cross in the book during the interval: the size crossed, valued at the pool's mid at that moment. A cross has two sides and is counted once.
  • every deal closed during the interval: the quote traded by all of its fills. A deal enters the figures when it is closed, in one piece, whenever its answers traded. See Closing a deal.

Swept is the sum over every sweep in the interval of the quote that met the curve: what a buying order paid in, sweep fee included, or what a selling order received.

Protocol fees

The two fee figures are the protocol fees the interval's trading accrued: the cross fees, the deal fees of deals closed in the interval, and the protocol's share of sweep fees. A sweep fee is charged in the token the order pays in, so a selling order's share accrues in the base token and everything else in the quote token. The rates and the share are told in Fees.

Until a sounding reveals them, accrued protocol fees are a sealed figure inside the book. The sounding adds them to the market's public fees_owed_base and fees_owed_quote, and from that moment they are payable.

pay_fees pays everything owed in both tokens from the market's vaults to the token accounts of the fee recipient named in Config, sets both figures to zero and emits FeesPaid with the two amounts. Any wallet may send it. What the fees do next is told in The token.

A market's first price

A market's first price is public. The creator's first liquidity moves from the wallet to the market's vaults in the open, and its two amounts set the first price: the quote amount divided by the base amount. The program stores it as the market's first_price, emits it in MarketReady when the pool opens, and records it as the market's last price until the first sounding replaces it. A first price outside the program's price range is refused with PriceOutOfRange: see fund_market.

From then on the pool's reserves are sealed and the price is public only at each sounding. See Create a market.

Reading soundings

From the chain

The last sounding of a market is on its account.

ts
const m = await client.market(market)

const price = BigInt(m.lastPrice.toString())      // quote atoms per base atom, times 2^32
const crossed = BigInt(m.lastCrossed.toString())  // quote atoms
const swept = BigInt(m.lastSwept.toString())      // quote atoms
const slot = BigInt(m.lastSoundSlot.toString())
const taken = BigInt(m.soundings.toString())      // soundings taken so far

client is a HadalClient and market is the market's address. The history is the program's Sounding events: see Program.

From the HTTP API

The API serves every sounding and builds the rest from them.

RouteWhat it builds
GET /v1/soundings and GET /v1/markets/:market/soundingsEach sounding with its slot, time, price, volumes, fees and the signature of the transaction that put it on chain.
GET /v1/markets/:market/candlesCandles of 1m, 5m, 15m, 1h or 1d. Open, high, low and close are sounding prices, the volumes are sums of the soundings' volumes, and each candle says how many soundings it holds. A candle holds no individual fill.
GET /v1/marketsEach market's price at its last sounding with that sounding's time and slot, the crossed and swept volume of the last 24 hours, and the price change over them.
GET /v1/totalsVolume and protocol fees to date per quote mint, and the number of soundings taken.

In the app

  • Trade draws the chart from soundings: one price per sounding, held as a step until the next, with each sounding's volume under it.
  • Every figure the app computes from a price is an estimate at the last sounding and is labelled so: the estimate in the order ticket, which names that sounding's time in UTC, what a liquidity share returns on Pools, and the last sounding shown on Deals and Portfolio. What an order filled at is in its receipt.
  • Soundings is the public record: the totals to date, each market's soundings with time, slot, price, crossed, swept, fee and transaction, the last four hours as rings, and the public events beside them.

What the surface shows between two soundings, action by action, is in What is sealed and what is seen.