@somnia-chain/markets-sdk

@somnia-chain/markets-sdk / index / UnifiedTicker

Interface: UnifiedTicker

Defined in: packages/sdk/src/unified/structs.ts:373

A rolling 24h market snapshot (ccxt ticker shape), human units. Absent fields mean the window had no trades to derive them from.

Properties

symbol

symbol: string

Defined in: packages/sdk/src/unified/structs.ts:375

The tradable symbol the ticker describes.

chainId

chainId: number

Defined in: packages/sdk/src/unified/structs.ts:377

Numeric chain id the market lives on.

timestamp

timestamp: number

Defined in: packages/sdk/src/unified/structs.ts:379

When this snapshot was computed (ms, local clock).

datetime

datetime: string

Defined in: packages/sdk/src/unified/structs.ts:381

ISO-8601 of timestamp.

high?

optional high?: number

Defined in: packages/sdk/src/unified/structs.ts:383

Highest fill price in the window.

low?

optional low?: number

Defined in: packages/sdk/src/unified/structs.ts:385

Lowest fill price in the window.

open?

optional open?: number

Defined in: packages/sdk/src/unified/structs.ts:387

First fill price in the window.

last?

optional last?: number

Defined in: packages/sdk/src/unified/structs.ts:389

Most recent fill price (may predate the window on quiet markets).

lastSource?

optional lastSource?: object

Defined in: packages/sdk/src/unified/structs.ts:407

When the trade behind last happened (ms).

Present on BOTH paths that produce a last. A candle stamps its bucket start. The cached fallback — the market row's lifetime last price, used when the candle window is empty — stamps that row's lastTradeAt, which can be much older than the window. Compare the timestamp; do not read presence alone as a freshness signal.

ABSENCE IS MEANINGFUL, and narrower than it looks. No lastSource means either there is no last at all, or the cached fallback supplied last while the row carried no lastTradeAt. In both cases no provenance exists, so a consumer that needs a fresh print must treat last as stale.

Read it against statsAsOf, not against timestamp: timestamp is when this snapshot was assembled and says nothing about either half's age.

timestamp

timestamp: number

When the trade happened (ms).

statsAsOf?

optional statsAsOf?: number

Defined in: packages/sdk/src/unified/structs.ts:418

The end of the window the 24h statistics (open, high, low, change, percentage, baseVolume, quoteVolume) were folded over (ms).

This is the statistics' own as-of, derived from the candle window — NOT the response time. Absent when the window held no candles to fold.

change?

optional change?: number

Defined in: packages/sdk/src/unified/structs.ts:420

last − open, when both are known.

percentage?

optional percentage?: number

Defined in: packages/sdk/src/unified/structs.ts:422

change / open as a plain fraction (0.05 = +5%), when derivable.

baseVolume?

optional baseVolume?: number

Defined in: packages/sdk/src/unified/structs.ts:430

Σ base-asset volume over the window.

Absent when statsState is "unavailable" — there is no honest number to report then. A 0 means a successful read over a window with no fills, which is a true zero. Branch on statsState, not on absence.

quoteVolume?

optional quoteVolume?: number

Defined in: packages/sdk/src/unified/structs.ts:436

Σ quote-asset volume over the window.

Absent when statsState is "unavailable". See baseVolume.

statsState

statsState: "ok" | "unavailable"

Defined in: packages/sdk/src/unified/structs.ts:459

Whether the 24h statistics above were read, and WHY when they were not.

Two states, always one of them:

  • "ok" — the candle window was read. baseVolume and quoteVolume are present. They are 0 when the window held no fills, which is a true zero and not a missing value.
  • "unavailable" — the statistics could not be read. Either the candle request failed with an IndexerError, or the market is indexed: false and no candle request was sent. open, high, low, change, percentage, statsAsOf, baseVolume and quoteVolume are ALL absent, and info carries no fold.

The call still resolves in the "unavailable" state, and the perp chain fields below are still read. That is the point of the field: a candle outage must not take down mark price, index price, funding and open interest, which come from chain and would have worked.

last and lastSource are independent of this state. They still come from the cached market row when it carries them.

markPrice?

optional markPrice?: number

Defined in: packages/sdk/src/unified/structs.ts:468

PERP ONLY — mark price, human quote units.

Undefined on spot/binary, and undefined on a perp whose mark is unusable — either the feed reported stale, or the price is zero. A zero mark is never published: flattened to a number it reads as a real price, and downstream an unguarded markPrice - entryPrice becomes a 100% loss on every open position.

indexPrice?

optional indexPrice?: number

Defined in: packages/sdk/src/unified/structs.ts:470

PERP ONLY — oracle index price, human quote units. Undefined on spot/binary.

fundingRate?

optional fundingRate?: number

Defined in: packages/sdk/src/unified/structs.ts:482

PERP ONLY — funding rate per 8 HOURS as a plain fraction (0.0001 = 0.01%).

The same axis UnifiedFundingRate.fundingRate and fetchFundingRateHistory use, deliberately: a header reading one basis while the chart beside it reads another is a wrong number that looks right. NOT the amount charged per settlement — that is this divided by fundingWindowSec / fundingIntervalSec (8 on every live pool; it has been 96 at a 300s cadence), and info.perp carries both figures. On a historical catch-up row, multiply by that row's intervalsAccrued — one settlement can charge more than one interval's worth.

fundingTimestamp?

optional fundingTimestamp?: number

Defined in: packages/sdk/src/unified/structs.ts:487

PERP ONLY — when funding next settles (ms). Settlement is permissionless and lazy, so a past value means a settlement is DUE, not that anything is broken.

openInterest?

optional openInterest?: number

Defined in: packages/sdk/src/unified/structs.ts:494

PERP ONLY — total open interest in base units.

ONE counter, not a long/short pair: in a matched CLOB the short side is provably equal, so there is nothing to sum.

perpState

perpState: "ok" | "not-applicable" | "degraded"

Defined in: packages/sdk/src/unified/structs.ts:510

Whether the perp chain fields above are present, and WHY when they are not.

Three states, always one of them:

  • "not-applicable" — spot or binary. No perp fields exist to report.
  • "ok" — a perp, and its chain state was read. The perp fields are present.
  • "degraded" — a perp whose chain state read FAILED. The perp fields are absent and the 24h half below is still valid.

Without this, a missing markPrice is ambiguous: it reads the same on a spot market as on a perp whose oracle reverted. The degrade is deliberate — losing candle statistics to an oracle outage would be worse — but it must be visible, so branch on this rather than on the absence of a field.

info

info: unknown

Defined in: packages/sdk/src/unified/structs.ts:521

The raw fold this snapshot came from (raw-unit bigints). On a perp it also carries perp, the full on-chain state — including fundingWindowSec / fundingIntervalSec for re-basing the funding rate.

There is no fold to carry when statsState is "unavailable". This is then undefined on a spot or binary market, and carries only perp on a perp. Check statsState before reading a fold field off it; the type is unknown, so the compiler cannot warn you.