skills/docs/money/finance/currency-provider-kraken/src/symbols/symbols.md

symbols — Kraken symbol-mapping table

(no submodules)

Purpose

The Kraken public ticker addresses pairs by non-standard names — XXBTZUSD for BTC/USD, XETHZUSD for ETH/USD, XDGUSD for DOGE/USD — using the asset-prefix convention (X for native crypto assets, Z for fiat) inherited from its early-2014 instrument schema. Every consumer of the KrakenProvider wants to address rates by the Suaveplan-standard symbol (BTC, ETH, DOGE), so the provider needs a stable bidirectional lookup table that normalises both directions in O(1).

This module owns that table. It exports the frozen forward map (KRAKEN_SYMBOL_MAP), the derived frozen reverse map (KRAKEN_PAIR_TO_SYMBOL), and a mergeSymbolMap helper for callers who need to extend coverage without forking the package.

Features

• 12 canonical Suaveplan symbols mapped to their Kraken pair names: BTC, ETH, SOL, USDT, DOT, ADA, LINK, AVAX, ATOM, LTC, DOGE, XRP
• Forward + reverse maps both Object.freeze-d for identity stability and cheap memoised lookups in the hot path
• mergeSymbolMap(extras) for caller-supplied extensions — returns a fresh forward + reverse pair without mutating the canonical maps
• Zero runtime dependencies, universal

Usage: Basic

import {
 KRAKEN_PAIR_TO_SYMBOL,
 KRAKEN_SYMBOL_MAP,
} from "@suaveplan/currency-provider-kraken/symbols/symbols";

console.log(KRAKEN_SYMBOL_MAP.BTC); // "XXBTZUSD"
console.log(KRAKEN_PAIR_TO_SYMBOL.XXBTZUSD); // "BTC"

Usage: Advanced

import { mergeSymbolMap } from "@suaveplan/currency-provider-kraken/symbols/symbols";

// Extend with a pair Kraken added after this release shipped.
const { forward, reverse } = mergeSymbolMap({
 MATIC: "MATICUSD",
 APT: "APTUSD",
});

console.log(forward.MATIC); // "MATICUSD"
console.log(reverse.MATICUSD); // "MATIC"

// Original maps are unchanged — `mergeSymbolMap` never mutates them.
console.log("MATIC" in KRAKEN_SYMBOL_MAP); // false

API Reference

Export	Kind	Description
KRAKEN_SYMBOL_MAP	Readonly<Record<string, string>>	Frozen forward map: 12 Suaveplan symbols → Kraken pair name.
KRAKEN_PAIR_TO_SYMBOL	Readonly<Record<string, string>>	Frozen reverse map derived at module load from the forward map.
MergedSymbolMaps	interface	Shape returned by mergeSymbolMap — { forward, reverse }, both Readonly<Record<string, string>>.
mergeSymbolMap(extras?)	(Readonly<Record<string, string>> | undefined) => MergedSymbolMaps	Returns the canonical maps when extras is empty/undefined; otherwise returns fresh forward + reverse maps with the extras merged on top.

Implementation Notes

• The Kraken instrument schema mixes legacy X<base>Z<quote> pairs (XXBTZUSD) with flat <base>USD pairs (SOLUSD, DOTUSD) added after the schema redesign. The map captures both forms so callers don't have to.
• The forward map is intentionally small. Kraken lists hundreds of pairs; the 12 included here are the high-volume subset that match the upstream 9-provider bundle's coverage. Callers needing more symbols use the extraSymbols constructor field on KrakenProvider (which calls mergeSymbolMap internally) or call mergeSymbolMap directly when they want the maps for their own logic.
• mergeSymbolMap is a hot-path-aware fast path: when extras is empty or undefined, it returns the canonical maps by reference without allocating.
• Both canonical maps are frozen, so Object.assign(KRAKEN_SYMBOL_MAP, …) silently fails in non-strict mode and throws in strict mode — making accidental mutation impossible.
• Determinism: iteration order of Object.entries(KRAKEN_SYMBOL_MAP) is property-insertion order per the ES2015 spec, so derived structures (including the reverse map and merged outputs) have deterministic ordering for golden-file tests.