Skip to main content

Market Data Price v1 Service

Skip The Details?​

Overview​

The PriceService provides market data pricing information for token pairs on the Mesh platform. This service enables retrieval of current market prices to support:

  • Trading Decisions: Get real-time prices before executing trades
  • Portfolio Valuation: Calculate holdings value in your preferred quote currency
  • Price Discovery: Query mid-market prices for any supported token pair

The service provides a single operation:

  • GetCurrentPriceByTokenPair: Retrieve the current mid-market price for a specified base/quote token pair

Prices are returned as the mid-market price for a base token denominated in a quote token, along with a timestamp indicating when the price was observed.

Key Concepts​

Token Pairs​

Prices are always quoted as a pair of tokens:

  • Base Token: The token being priced (e.g., XAU, USD, STX40)
  • Quote Token: The currency in which the price is denominated (e.g., USD, ZAR)

For example, in an XAU/ZAR pair:

  • Base token: XAU (Gold)
  • Quote token: ZAR (South African Rand)
  • A price of 55,000 means 1 troy ounce of gold = 55,000 ZAR

Supported Token Types​

The service supports pricing for several categories of instruments:

CategoryExamplesQuote Currencies
CryptocurrenciesBTC, ETH, XLM, USDC, USDT, SOL, DOGE, ADA, DOTUSD, ZAR, other fiat
Precious MetalsXAU (Gold), XAG (Silver), XPT (Platinum), XPD (Palladium)USD, ZAR
Fiat CurrenciesUSD, EUR, GBP, JPY, ZAR, CHF, CAD, AUD, NZD, CNY, INR, BRLAny supported fiat
JSE EquitiesSTX40, STXRAF, STXWDM, STXEMG, STX500, BRNDZ, TITANSZAR
note

Certain pair combinations are not supported, such as precious metal to precious metal (e.g., XAU/XAG) or equity to equity (e.g., STX40/STXRAF). If needed, calculate these manually using a common currency.

note

When both base and quote tokens are the same (e.g., USD/USD), the service returns a price of 1.

Mid-Market Price​

The service returns mid-market prices, which provide a fair reference price that is:

  • Neutral between buyers and sellers
  • Suitable for portfolio valuation
  • A starting point for trade pricing

Cross-Rate Calculation​

For certain token pairs that don't have direct pricing sources, the service automatically calculates cross-rates. For example, to price XAG/ZAR (Silver in Rand), the service:

  1. Fetches XAG/USD (Silver in US Dollars)
  2. Fetches USD/ZAR (US Dollar to Rand exchange rate)
  3. Multiplies the two rates to derive XAG/ZAR

This is handled transparently - you simply request the token pair you need.

Quick Start​

  1. Configure your client with appropriate API credentials
  2. Identify your token pair - determine the base token (what you want priced) and quote token (currency to price it in)
  3. Verify support - ensure your token pair is in a supported category (see table above)
  4. Call GetCurrentPriceByTokenPair with both tokens specified using their standard codes

Common Workflows​

Get Current Price​

Use GetCurrentPriceByTokenPair to retrieve the current mid-market price for any supported token pair:

  • Specify the base token (the asset you want priced)
  • Specify the quote token (the currency to price it in)
  • Receive the current mid-market price with timestamp

The response includes:

  • The echoed base and quote tokens
  • The mid-market price as a decimal value
  • A timestamp indicating when the price was observed

Forex Conversion​

To convert between fiat currencies:

  1. Call GetCurrentPriceByTokenPair with the source currency as base and target currency as quote
  2. Multiply the amount by the returned price
  3. Example: Convert 100 USD to ZAR - get USD/ZAR price, multiply by 100

Cryptocurrency Pricing​

To get cryptocurrency prices:

  1. Call GetCurrentPriceByTokenPair with the crypto code (BTC, ETH, XLM, etc.) as base
  2. Use USD, ZAR, or another fiat currency as the quote token
  3. Crypto-to-crypto pairs (e.g., XLM/USDC) are also supported

Precious Metal Valuation​

To price precious metal holdings:

  1. Call GetCurrentPriceByTokenPair with the metal code (XAU, XAG, XPT, XPD) as base
  2. Use your preferred currency as the quote token (USD or ZAR)
  3. Multiply by quantity (prices are per troy ounce)

JSE Equity Pricing​

To get prices for JSE-listed instruments:

  1. Use the instrument ticker as the base token (e.g., STX40, BRNDZ)
  2. Use ZAR as the quote token (JSE equities are priced in ZAR)
  3. Prices are returned in Rand (the service handles any underlying cent-to-Rand conversions)

Portfolio Valuation​

To value a portfolio of mixed holdings:

  1. For each holding, call GetCurrentPriceByTokenPair with your holding as base and your reporting currency as quote
  2. Multiply each price by the holding quantity
  3. Sum for total portfolio value

Authentication & Authorization​

This service implements role-based access control:

Read Operations (GetCurrentPriceByTokenPair)​

  • Required Roles: ROLE_MARKET_DATA_ADMIN, ROLE_MARKET_DATA_VIEWER, ROLE_MARKET_DATA_PRICE_ADMIN, or ROLE_MARKET_DATA_PRICE_VIEWER
  • Method Type: METHOD_TYPE_READ

The service supports both domain-level roles (ROLE_MARKET_DATA_*) and service-specific roles (ROLE_MARKET_DATA_PRICE_*). Use service-specific roles for fine-grained access control when users should only access price data without broader market data permissions.

All operations are scoped to your authenticated context and require appropriate Market Data domain permissions.

Best Practices​

  1. Token Code Standards: Use ISO 4217 codes for fiat currencies (USD, EUR, ZAR) and standard commodity codes for precious metals (XAU, XAG, XPT, XPD)
  2. Error Handling: Unsupported token pairs return an error - verify your pair is in a supported category before calling
  3. Timestamp Awareness: Always check the returned timestamp to understand price freshness for time-sensitive operations
  4. Caching Strategy: For high-frequency access, consider caching prices with appropriate TTLs based on your use case requirements