Market Rates

Overview

A trace that records a swap of 0.5 ETH tells you the size in tokens but not in dollars. Comparing that against a 1200 USDC trade, or alerting when a trade exceeds a dollar threshold, means knowing the rate at the moment the action happened — not the rate at the time you look. Mirador’s rate hint ties an asset symbol and quantity to a trace. The backend ratehint plugin resolves the USD spot rate and stamps both the rate and the resulting notional onto the trace:

RateHintAdded → RateTrackingStarted
RateAdded (the resolved rate and notional) or RateNotFound
RateTrackingFinished (terminal)

Unlike the transaction hints, this one resolves in one step and does not track an external state machine — it prices a quantity at the time the hint arrives.

Rate hints are emitted over OpenTelemetry only. There is no Web SDK method — no Web3Plugin, no trace.market.* namespace. Emit the reserved span event described below.

Recording a Rate Hint

Add the mirador.market.asset.ratehint event to the active span with a symbol and a quantity.

span.addEvent('mirador.market.asset.ratehint', {
  'asset.symbol': 'ETH',
  'asset.quantity': 0.5,
});

span.AddEvent("mirador.market.asset.ratehint", trace.WithAttributes(
    attribute.String("asset.symbol", "ETH"),
    attribute.Float64("asset.quantity", 0.5),
))

span.add_event("mirador.market.asset.ratehint", {
    "asset.symbol": "ETH",
    "asset.quantity": 0.5,
})

Attributes

Attribute	Type	Required	Description
`asset.symbol`	string	Yes	Crypto symbol (`ETH`, `USDC`) or ISO 4217 fiat code (`GBP`)
`asset.quantity`	double, integer, or numeric string	Yes	Order size in units of `asset.symbol`; must be positive
`asset.kind`	string	No	`crypto` or `fiat`; inferred from the symbol when omitted

asset.symbol is upper-cased server-side, so casing does not matter. asset.quantity keeps its fractional part and accepts a numeric string for SDKs that cannot express a double.

asset.kind is passed through as-is and lowercased. Any value other than crypto or fiat is treated as unspecified, and the market service falls back to inferring the kind from the symbol — an unrecognized value does not invalidate the hint. Prefer crypto, fiat, or nothing at all.

What Gets Stamped

On a successful resolution, RateAdded carries the rate and notional, and the following attribute bag is stamped inside the synthetic ratehint span:

Attribute	Type	Description
`mirador.market.rate.symbol`	string	Canonical symbol the market service returned
`mirador.market.rate.pair`	string	The quoted pair, e.g. `ETH/USD`
`mirador.market.rate.quantity`	double	The quantity you submitted
`mirador.market.rate.asset_kind`	string	`crypto`, `fiat`, or `unspecified`
`mirador.market.rate.usd_per_unit`	double	USD value of one unit of the symbol
`mirador.market.rate.usd_notional`	double	`quantity × usd_per_unit`

RateAdded also records rate_as_of for source freshness and the resolution source (cache, coingecko, or exchangerate).

These attributes are dotted and platform-namespaced specifically so automation rules and derived metrics can read them. Pricing slippage or trade size in dollars is a query over mirador.market.rate.usd_notional.

Terminal Statuses

RateTrackingFinished closes the lifecycle with one of:

Status	Meaning
`SUCCESS`	A rate was resolved and stamped
`UNAVAILABLE`	The rate source was unreachable, or no quote arrived in time
`UNSUPPORTED`	The symbol could not be resolved to a USD rate

UNAVAILABLE is transient and worth retrying on a later trace; UNSUPPORTED means the symbol will not resolve. Both emit RateNotFound before the terminal event, so a missing rate is always visible in the trace rather than silently absent.

End-to-End Example

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('trading');

await tracer.startActiveSpan('swap-flow', async (span) => {
  try {
    // 1. Price the input side of the swap in dollars
    span.addEvent('mirador.market.asset.ratehint', {
      'asset.symbol': 'ETH',
      'asset.quantity': 0.5,
      'asset.kind': 'crypto',
    });

    // 2. Execute the swap and hint the transaction as usual
    const tx = await executeSwap();
    span.addEvent('mirador.web3.evm.txhint', {
      'tx.hash': tx.hash,
      'chain.id': 8453,
    });
  } finally {
    span.end();
  }
});

The trace now carries both the onchain settlement and the dollar value of what was traded.

Pricing Both Sides

A rate hint prices one asset. Emit one per asset when you want both sides of a trade in dollars — one action per event is the rule for every hint.

span.addEvent('mirador.market.asset.ratehint', {
  'asset.symbol': 'ETH',
  'asset.quantity': 0.5,
});

span.addEvent('mirador.market.asset.ratehint', {
  'asset.symbol': 'USDC',
  'asset.quantity': 1200,
});

Next Steps

Enrichment Hints

The full reserved-event catalog and attribute contract

Stripe Payments

Track payments through charge and payout

Metrics over OTLP

Export metrics alongside your traces

Automation Rules

Alert on notional thresholds

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Overview

Recording a Rate Hint

Attributes

What Gets Stamped

Terminal Statuses

End-to-End Example

Pricing Both Sides

Next Steps

Enrichment Hints

Stripe Payments

Metrics over OTLP

Automation Rules

​Overview

​Recording a Rate Hint

​Attributes

​What Gets Stamped

​Terminal Statuses

​End-to-End Example

​Pricing Both Sides

​Next Steps

Enrichment Hints

Stripe Payments

Metrics over OTLP

Automation Rules

Overview

Recording a Rate Hint

Attributes

What Gets Stamped

Terminal Statuses

End-to-End Example

Pricing Both Sides

Next Steps