Enrichment Hints

Mirador enrichment hints connect an OpenTelemetry trace to actions that happen outside your process. Emit a reserved mirador.* event on the active user-flow span, and Mirador follows the action and stitches its outcome into that same trace. Supported actions include EVM, Solana, Canton, Safe, and Relay transactions, Stripe payments, and market rate resolution.

The canonical machine-readable contract is published at otel.mirador.org/llms.txt. Use it when generating integrations or prompting a coding agent.

Event catalog

Event name	Tracks	Required identity
`mirador.web3.evm.txhint`	EVM transaction through receipt	`tx.hash` + EVM chain
`mirador.web3.solana.txhint`	Solana transaction	`tx.signature`
`mirador.web3.canton.txhint`	Canton transaction	`tx.update_id`
`mirador.web3.safe.txhint`	Safe multisig confirmation through execution	`safe.tx_hash` + EVM chain
`mirador.web3.safe.msghint`	Safe EIP-712 message signing	`safe.message_hash` + EVM chain
`mirador.web3.relay.requesthint`	Relay bridge deposit through fill	`relay.request_id`
`mirador.payment.stripe.intenthint`	Stripe PaymentIntent through payout	`stripe.payment_intent_id`
`mirador.market.asset.ratehint`	Asset spot rate and USD notional	`asset.symbol` + `asset.quantity`

An EVM chain is identified by chain.id, chain.name, or both when they agree. Only the EVM and Safe hints take a chain; every other hint is chain-agnostic or implies its chain from the event name.

Naming convention

Every hint follows mirador.<domain>.<subject>.<kind>hint:

Segment	Meaning	Values
`domain`	Industry bucket	`web3`, `payment`, `market`
`subject`	Chain, protocol, provider, or resource	`evm`, `solana`, `canton`, `safe`, `relay`, `stripe`, `asset`
`kind`	The object you hold the ID for	`tx`, `msg`, `request`, `intent`, `rate`

Attribute reference

Attribute	Type	Required for	Example
`tx.hash`	string	EVM transaction	`0x` + 64 hexadecimal characters
`chain.id`	integer, decimal string, or integral double	EVM and Safe hints, unless `chain.name` is present	`8453`
`chain.name`	string	EVM and Safe hints, unless `chain.id` is present	`base`
`tx.signature`	string	Solana transaction	Base58 transaction signature
`tx.update_id`	string	Canton transaction	Canton update ID
`canton.party_id`	string	Optional Canton read-as context	`Alice::1220…`
`safe.tx_hash`	string	Safe transaction	SafeTxHash, not the executing transaction hash
`safe.message_hash`	string	Safe message	Safe message hash
`relay.request_id`	string	Relay	Request ID returned by the quote
`stripe.payment_intent_id`	string	Stripe	`pi_…`
`stripe.account_id`	string	Optional Stripe Connect routing	`acct_…`
`asset.symbol`	string	Market rate	`ETH`, `USDC`, `GBP`
`asset.quantity`	double, integer, or numeric string	Market rate	`0.5`
`asset.kind`	string	Optional market rate hint	`crypto` or `fiat`

Extra attributes are preserved as context but do not control tracking. Notes on individual attributes:

safe.tx_hash is the SafeTxHash of the multisig proposal, not the hash of the transaction that executes it.
relay.request_id is the Relay request ID from the quote. Relay is chain-agnostic at hint time, so no chain attribute is needed; chain IDs and transaction hashes are resolved server-side from Relay’s status feed.
stripe.account_id routes calls to a Stripe Connect connected account. Omit it when observing your own account.
asset.symbol accepts a crypto symbol or an ISO 4217 fiat code and is upper-cased server-side, so casing does not matter.
asset.quantity must be positive. Mirador stamps usd_notional = quantity × usd_per_unit.
asset.kind is optional because the market service infers it from the symbol. It is passed through as-is; any value other than crypto or fiat is treated as unspecified and the market service still infers from the symbol. An unrecognized value does not reject the hint.

Attribute keys are literal flat strings. Emit 'tx.hash'; do not send a nested object such as { tx: { hash: value } }.

Emit a hint

Add the event only after the external system returns its identity.

span.addEvent('mirador.web3.evm.txhint', {
  'tx.hash': transactionHash,
  'chain.id': 8453, // or 'base'
  'checkout.step': 'submit',
});

span.addEvent('mirador.payment.stripe.intenthint', {
  'stripe.payment_intent_id': paymentIntent.id,
  'stripe.account_id': connectedAccountId,
});

span.addEvent('mirador.web3.relay.requesthint', {
  'relay.request_id': quote.requestId,
});

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

span.AddEvent("mirador.web3.evm.txhint", trace.WithAttributes(
    attribute.String("tx.hash", transactionHash),
    attribute.Int64("chain.id", 8453),
    attribute.String("checkout.step", "submit"),
))

span.AddEvent("mirador.payment.stripe.intenthint", trace.WithAttributes(
    attribute.String("stripe.payment_intent_id", paymentIntentID),
))

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

span.add_event("mirador.web3.solana.txhint", {
    "tx.signature": signature,
})

span.add_event("mirador.web3.canton.txhint", {
    "tx.update_id": update_id,
    "canton.party_id": party_id,
})

Rules that must hold

Emit an event, not a child span. Add the reserved event to the active user-flow span.
Use the exact event name. Names are case-sensitive.
Emit one event per action. Two transactions require two events; do not use an array of hashes.
Use flat attribute keys. Dots are part of the key name.
Wait for the identity. Do not emit before the transaction, intent, or payment ID is known.
Keep the span sampled. A sampled-out span cannot carry a hint to Mirador.
Flush before exit. Allow the batch exporter to drain or explicitly shut down the provider.
mirador.trace.* is the exception to rule 1. Those keys are attributes, not events. See Reserved keys that are not events.

Chain resolution

The EVM and Safe hints accept these forms:

Input	Result
`chain.id: 8453`	Accepted
`chain.id: "8453"`	Accepted
`chain.name: " Base "`	Accepted; normalized and resolved to Base
`chain.id: 1` with `chain.name: "base"`	Invalid because the values contradict
`chain.name: "unknown"` without an ID	Invalid
`chain.id: 0` or `"0x2105"`	Invalid

Known IDs include Ethereum 1, Optimism 10, BNB Smart Chain 56, Polygon 137, HyperEVM 999, Base 8453, and Arbitrum 42161.

Invalid hints are preserved

A reserved event that is missing a required attribute or fails validation becomes a normal span event. Mirador preserves it instead of dropping it, but enrichment tracking does not start. This happens when:

A required attribute is missing or empty.
chain.id is 0, chain.name is unknown without an ID, or the two contradict each other.
asset.quantity is zero, negative, or not a number.

This fallback makes typos visible in the trace while preventing Mirador from following the wrong external action.

Reserved keys that are not events

The mirador.trace.* namespace works the other way round. These are attributes, not events, and they shape the whole trace rather than tracking an external action.

Attribute	Set on	Type	Effect
`mirador.trace.tags`	Root span, or the Resource	String array, or comma-separated string	Labels the trace
`mirador.trace.attribute.<key>`	Any span or span event	String, boolean, integer, or double	Promotes `<key>` into the trace’s attribute bag

This namespace was previously mirador.tags. The old key is no longer recognized and now lands as an ordinary span attribute, so a trace set up the old way silently loses its tags. Rename it to mirador.trace.tags.

An event named mirador.trace.* is not a thing and lands as a plain event. It is the attribute key that matters, not the event name.

Trace tags

rootSpan.setAttribute('mirador.trace.tags', ['checkout', 'eu-west']);

The array form is canonical. A plain string is comma-split so string-only configuration surfaces can reach this too, most importantly OTEL_RESOURCE_ATTRIBUTES=mirador.trace.tags=checkout,eu-west, which cannot express an array at all.

Set it on the Resource to tag every trace from a service. On the root span the span value wins outright rather than merging with the Resource value.
Only the root span is read. The same key on a child span stays an ordinary span attribute.
Non-string array elements render as their scalar text, so [1, true] tags as "1" and "true".
Values are trimmed; empties and duplicates drop, and first-seen order is preserved.
Capped at 32 tags of 128 characters. An over-cap tag is dropped whole, never truncated.

Trace attribute promotion

By default a span attribute stays on its span. mirador.trace.attribute.<key> is the opt-in way to make one a fact about the whole trace:

span.setAttribute('mirador.trace.attribute.tier', 'gold'); // becomes trace attribute "tier"

The prefix is stripped, so tier=gold joins the trace attribute bag. From there it is searchable through GET /v1/traces?filter=…, readable in automation-rule and derived-metric CEL as trace.attributes["tier"], and declarable as a derived-metric dimension.

Set it anywhere. The marker is honored on any span’s attributes and on any span event’s attributes, so trace facts do not have to be hoisted to the root span. When the same stripped key is set more than once, the last one applied wins.
It copies, not moves. The original mirador.trace.attribute.tier stays where you set it.
Scalars only. Arrays and maps are ignored, because CEL never binds them.
Explicit wins. A promoted value outranks a same-named resource attribute or vendor default.
Reserved targets are ignored: service.name (set that on the Resource), any key beginning __, and the mirador.trace.* namespace itself.

A bad marker is skipped rather than fatal, so one malformed key never rejects the span.

Event severity

OTLP span events have no native severity, so Mirador stores them neutral by default: they never affect a trace’s info, warn, or error counts. Span failure comes from the OTLP span status, not from its events, so recording an exception event does not by itself mark a trace failed. To give one event a severity, set the reserved attribute on that event:

Attribute	Set on	Values	Effect
`mirador.event.severity`	The span event	`info`, `warn`, or `error`, lowercase	Folds into the trace’s info, warn, and error counts

span.addEvent('payment.declined', {
  'mirador.event.severity': 'error',
});

span.AddEvent("payment.declined", trace.WithAttributes(
    attribute.String("mirador.event.severity", "error"),
))

An absent, empty, or unrecognized value means neutral. The value is case-sensitive, so use lowercase. The attribute is read before attribute capping and is left on the event’s attribute bag. This is what the severity filter on GET /v1/traces matches against, so an event you want to find later needs an explicit severity.

Next steps

Traces over OTLP

Configure trace export and understand span mapping

Transaction hints

Learn how Mirador follows and enriches transactions

Stripe payments

Track a PaymentIntent through charge and payout

Market rates

Resolve spot rates and stamp USD notionals

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Event catalog

Naming convention

Attribute reference

Emit a hint

Rules that must hold

Chain resolution

Invalid hints are preserved

Reserved keys that are not events

Trace tags

Trace attribute promotion

Event severity

Next steps

Traces over OTLP

Transaction hints

Stripe payments

Market rates

​Event catalog

​Naming convention

​Attribute reference

​Emit a hint

​Rules that must hold

​Chain resolution

​Invalid hints are preserved

​Reserved keys that are not events

​Trace tags

​Trace attribute promotion

​Event severity

​Next steps

Traces over OTLP

Transaction hints

Stripe payments

Market rates

Event catalog

Naming convention

Attribute reference

Emit a hint

Rules that must hold

Chain resolution

Invalid hints are preserved

Reserved keys that are not events

Trace tags

Trace attribute promotion

Event severity

Next steps