Interface Instrument

All Known Implementing Classes:

DatedFutureInstrument, PerpetualInstrument, SpotInstrument

public sealed interface Instrument
permits SpotInstrument, PerpetualInstrument, DatedFutureInstrument

Normalised instrument identity in the CCXT unified format.

Three market kinds, one per implementation:

• SpotInstrument — BTC/USDT
• PerpetualInstrument — BTC/USDT:USDT (USDT-margined), BTC/USD:BTC (coin-margined)
• DatedFutureInstrument — BTC/USDT:USDT-240628, a delivery contract with a fixed expiry

The distinction matters for identity, not just display: two delivery contracts on the same pair with different expiries trade at different prices, so they must be unequal and usable as distinct map keys. A single record with an optional expiry field would also permit a spot instrument carrying one; this hierarchy makes that unrepresentable.

Construct through of(String, String) rather than the record constructors. Each overload names exactly one variant and accepts no absent component: no null, no blank string. A call site holding an optional settlement currency must therefore decide for itself what it means — the factory will not quietly turn a missing component into a simpler market kind, because that is how a derivative ends up recorded as spot.

symbol() is a persisted and transported format, not a display convenience: it is the QuestDB ins column, part of the NATS subject grammar, and the identity used by the cache and the signal stores. parse(String) is its exact inverse. Note that settle() is deliberately absent from this interface — it exists only on the variants that have one, so code composing a wire format out of an instrument's parts cannot silently omit the expiry.

Engine-owned, with no XChange dependency. XChange's own instrument types are confined to the exchange-adapter / order-execution boundary, where XChangeConvert (qtsurfer-engine-exchange) bridges the two.

Method Summary

Modifier and Type	Method	Description
String	base()	Base currency, e.g.
default boolean	isDated()	true only for a delivery contract with a fixed expiry.
default boolean	isDerivative()	true for any contract settled in a currency — perpetual or dated.
static SpotInstrument	of(String base, String quote)	A spot instrument.
static PerpetualInstrument	of(String base, String quote, String settle)	A perpetual contract.
static DatedFutureInstrument	of(String base, String quote, String settle, LocalDate expiry)	A dated delivery contract.
static Instrument	parse(String symbol)	Parses a CCXT symbol back into the variant it denotes.
String	quote()	Quote currency, e.g.
String	symbol()	CCXT-style canonical string.

Method Details

base

String base()

Base currency, e.g. "BTC".

quote

String quote()

Quote currency, e.g. "USDT".

symbol

String symbol()

CCXT-style canonical string. Inverse of parse(String).

isDerivative

default boolean isDerivative()

true for any contract settled in a currency — perpetual or dated.

isDated

default boolean isDated()

true only for a delivery contract with a fixed expiry.

of

static SpotInstrument of(String base,
 String quote)

A spot instrument.

Throws:

NullPointerException - if any argument is null

IllegalArgumentException - if any currency code is blank

of

static PerpetualInstrument of(String base,
 String quote,
 String settle)

A perpetual contract.

Throws:

NullPointerException - if any argument is null

IllegalArgumentException - if any currency code is blank

of

static DatedFutureInstrument of(String base,
 String quote,
 String settle,
 LocalDate expiry)

A dated delivery contract.

Throws:

NullPointerException - if any argument is null

IllegalArgumentException - if any currency code is blank

parse

static Instrument parse(String symbol)

Parses a CCXT symbol back into the variant it denotes.

The dated form is recognised only when the tail after the settlement currency is a hyphen followed by exactly six digits forming a valid date. Anything else stays part of the settlement currency, so every symbol written by an earlier release parses to what it parsed to before.