Skip to main content

Instruments

Overview​

SDS is the platform's canonical store for all instrument definitions. It accepts instruments from one or more external data providers, enriches them with a platform-assigned identifier, and re-publishes them as editable messages for all downstream consumers.

Supported instrument types:

InstrumentTypeDescription
BONDFixed Income Bond — zero coupon, fixed, floating, fixed-to-float
IR_SWAPInterest Rate Swap — convention-based or explicit pay/receive legs
IR_FUTUREInterest Rate Future
BOND_FUTUREBond Future

Instrument ID​

Every instrument stored in SDS is assigned a unique alpha-numeric instrumentId. The format encodes the instrument type and currency:

{typePrefix}{currency}{sequentialNumber}
TypePrefixExample
BondBBUSD00001, BGBP00042
IR SwapSSUSD00001
IR Future / Bond FutureFFUSD00001
note

instrumentId is immutable once assigned. It serves as the stable internal reference used by all platform services.

Identifiers​

SDS resolves instruments by any of the following identifiers. All lookups are case-insensitive.

Identifier TypeFieldNotes
STATIC_DATA_SERVERinstrumentIdPlatform-assigned, e.g. BUSD00001
ISINisinISO 6166
CUSIPcusipCUSIP 9-character
FIGIfigiBloomberg FIGI
ALIASaliasManaged via the alias table (see Aliases)
CUSTOM / VENUEadditionalInstrumentIdsEntrySource-specific or venue identifiers

When a new instrument arrives, SDS checks all known identifiers before creating a new record. If any identifier matches an existing instrument, it is treated as an update rather than a new addition.

SDS also publishes an InstrumentIdReverseMapping message for every identifier associated with an instrument. This allows consumers to resolve any identifier directly to a canonical instrumentId without querying SDS.

Data Providers​

SDS can be configured to source instruments from one or more external data providers via KS_SDS_INSTRUMENT_SOURCES. Each provider is a separate KeySquare application that publishes InstrumentDto messages which SDS subscribes to on a CACHED_AND_LIVE basis.

KS_SDS_INSTRUMENT_SOURCES=[
  {
    "name": "ION Data Provider",
    "topicSource": "ion-data-provider",
    "topicGroup": ""
  },
  {
    "name": "ANVIL Data Provider",
    "topicSource": "anvil-data-provider",
    "topicGroup": ""
  }
]

Multiple providers can coexist. An instrument arriving from one provider will not overwrite changes made by a different provider — SDS tracks the originTopicSource of each instrument and only applies updates from its original source.

See data provider for more details on how to setup a custom data provider.

Source Ownership​

Each instrument records its origin:

  • originTopicSource — the topicSource of the data provider that first created it
  • originTopicId — the topicId of the instrument at its origin

If an instrument was created manually (via MessageAdd) with no data provider, the originTopicSource field is blank. The first provider to subsequently publish a matching instrument will become its origin and take ownership.

Instrument Lifecycle​

Creating an Instrument​

An instrument can enter SDS in two ways:

  1. From a data provider — the provider publishes an InstrumentDto on its topic; SDS subscribes and ingests it automatically
  2. Manually via MessageAdd — a Key UI user or API client sends a MessageAdd with an InstrumentDto payload

In both cases, SDS validates the instrument (see Validation), assigns an instrumentId if new, and persists it.

Updating an Instrument​

When a source provider publishes an update, SDS computes a field-level diff between the incoming and stored versions. Only changed fields are applied. Fields that have been manually edited (tracked in modifiedFieldsEntry) are protected — a source update will not overwrite a field that a user has explicitly changed.

Edit-restricted fields can additionally be configured via KS_SDS_INSTRUMENT_EDIT_RESTRICTED to prevent even manual edits. By default, tradeRestrictionFlags.restricted and tradeRestrictionFlags.sanctioned are restricted.

Matured Bonds​

By default, SDS filters out bonds whose maturityDate is in the past (relative to the current business date for the instrument's currency). This keeps the active instrument set clean.

Set KS_SDS_INCLUDE_MATURED_BONDS=true to publish matured bonds to the platform. This is useful for historical analysis or back-office workflows.

Instrument Profile​

Each instrument belongs to exactly one Instrument Profile. Instrument Profile helps manage operational data as a group, rather than needing to update it per individual security. See instrument profiles for more detail.

Validation​

SDS enforces the following on every instrument before persisting:

All instruments:

  • currency must be set and supported (a business date must exist for that currency)
  • instrumentType must be BOND or IR_SWAP

Bonds additionally:

  • couponType must be set
  • couponFrequency must be set (unless couponType is ZERO)
  • maturityType must be set
  • maturityDate must be set (unless maturityType is PERPETUAL)

Swaps additionally:

  • Either endTenor or maturityDate must be set
  • Either swapConvention must be set, or both payLeg and receiveLeg must be provided

RPC Functions​

Static Data Servers exposes a set of remote procedure calls (RPCs) to provide request/response functionality to both key-ui and api users. Developers can test these functions by navigating to the Tools -> RPC section in the user interface.

The SearchInstrument RPC returns descriptors for instruments that match the requested criteria. Searches can filter by:

  • Free text — matches against description and all identifier fields
  • Currency — one or more currency filters
  • Instrument type — one or more type filters

Results are capped at 1,000 entries.

If no local results are found and searchExternalSources=true is set in the request, SDS forwards the search request to all configured data providers in parallel and aggregates their responses. Each external result is tagged with its source.

Get Instrument​

The GetInstrument RPC looks up an instrument by any identifier. If the instrument is not found locally and addToWishListIfMissing=true, SDS adds it to the wish list (see Wish List) and responds with ok=false.

Wish List​

The wish list tracks instrument identifiers that have been requested but not yet found locally. It is used to trigger data providers to push missing instruments.

When a provider subsequently publishes an instrument whose identifiers match a wish list entry, SDS removes that entry from the wish list automatically — the instrument is now available locally.

Wish list entries can be added:

  • Automatically on a GetInstrument call with addToWishListIfMissing=true
  • Explicitly via the AddInstrumentToWishList RPC

SDS publishes an InstrumentWishDto message for each wish list entry, allowing providers to subscribe and fulfil requests proactively.

Aliases​

An alias is a named shortcut that resolves to a canonical instrumentId. Aliases are stored in the InstrumentAlias table and are case-insensitive.

To set an alias:

  1. Use the SetInstrumentAlias RPC with an alias string and one or more candidate identifiers
  2. SDS resolves the identifiers to a known instrumentId and persists the mapping
  3. Going forward, any lookup using that alias string will resolve to the canonical instrument

Aliases are published as separate InstrumentAliasDto messages with their own topic.

note

The alias field on InstrumentDto cannot be modified directly. It is managed by static data server

Benchmark Instrument​

The SetBenchmarkInstrument RPC links one instrument as the benchmark for another by populating the benchmarkInstrumentId field. This is used by pricing services to identify the on-the-run benchmark for spread calculations.

Reset Operations​

Reset Field​

The ResetInstrumentField RPC resets a single editable field on an instrument back to its source-provided value. This removes the field from modifiedFieldsEntry, allowing subsequent source updates to overwrite it again.

Reset Origin​

The ResetInstrumentOrigin RPC clears the originTopicSource and originTopicId from an instrument. This is used when you want to re-link an instrument to a new data provider — the next provider to publish a matching instrument will take ownership.