tapimo 0.5.2 → 0.6.0

package/src/apps/data/FundingQuoteProviders.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/mini'
 
 import * as FundingQuotes from '../../internal/FundingQuotes.js'
+import * as Store from '../../internal/Store.js'
 
 type Fetch = typeof globalThis.fetch
 
@@ -10,13 +11,23 @@ const defaultAcrossBaseUrl = 'https://app.across.to/api'
 const defaultRelayBaseUrl = 'https://api.relay.link'
 const defaultRhinoBaseUrl = 'https://api.rhino.fi/bridge'
 const defaultSquidBaseUrl = 'https://v2.api.squidrouter.com/v2'
+const defaultSymbiosisBaseUrl = 'https://api.symbiosis.finance/crosschain'
+// Keep one upstream slot free for deployment smoke tests and operational probes.
+const symbiosisRateLimit = 4
+const symbiosisRateLimitWindowMs = 1_000
 const providerOperations = {
   across: 'swap/approval',
   relay: 'quote/v2',
   rhino: 'quote/bridge-swap/public',
   squid: 'v2/route',
+  symbiosis: 'v2/quote',
 } as const
 
+/** Returns the stable upstream operation used by a funding quote provider. */
+export function providerOperation(provider: FundingQuotes.ProviderId) {
+  return providerOperations[provider]
+}
+
 namespace schema {
   const IntegerString = z.string().check(z.regex(/^\d+$/))
 
@@ -65,6 +76,30 @@ namespace schema {
       }),
     }),
   })
+
+  export const SymbiosisToken = z.object({
+    address: z.string(),
+    chainId: z.number().check(z.int(), z.nonnegative()),
+    decimals: z.number().check(z.int(), z.nonnegative()),
+  })
+
+  const SymbiosisTokenAmount = z.extend(SymbiosisToken, { amount: IntegerString })
+
+  export const SymbiosisQuote = z.object({
+    estimatedTime: z.optional(z.number().check(z.nonnegative())),
+    kind: z.union([z.literal('bridge'), z.literal('crosschain-swap'), z.literal('intent-swap')]),
+    routes: z
+      .array(
+        z.object({
+          tokens: z.array(SymbiosisToken).check(z.minLength(1)),
+        }),
+      )
+      .check(z.minLength(1)),
+    tokenAmountOut: SymbiosisTokenAmount,
+    tokenAmountOutMin: SymbiosisTokenAmount,
+    tx: z.object({ chainId: z.number().check(z.int(), z.nonnegative()) }),
+    type: z.union([z.literal('evm'), z.literal('tron')]),
+  })
 }
 
 /** Creates the live funding quote adapters configured for this deployment. */
@@ -74,6 +109,7 @@ export function createAdapters(options: createAdapters.Options = {}) {
     ...(options.relay ? { relay: relay(options.relay) } : {}),
     ...(options.rhino ? { rhino: rhino(options.rhino) } : {}),
     ...(options.squid ? { squid: squid(options.squid) } : {}),
+    ...(options.symbiosis ? { symbiosis: symbiosis(options.symbiosis) } : {}),
   } satisfies FundingQuotes.ProviderAdapters
 }
 
@@ -88,6 +124,8 @@ export declare namespace createAdapters {
     rhino?: rhino.Options | false | undefined
     /** Squid quote adapter options. */
     squid?: squid.Options | false | undefined
+    /** Symbiosis quote adapter options. */
+    symbiosis?: symbiosis.Options | false | undefined
   }
 }
 
@@ -137,6 +175,22 @@ export declare namespace configureSquid {
   }
 }
 
+/** Resolves Symbiosis deployment configuration. */
+export function configureSymbiosis(
+  options: configureSymbiosis.Options = {},
+): symbiosis.Options | undefined {
+  if (!options.userAddress) return undefined
+  return { userAddress: options.userAddress }
+}
+
+export declare namespace configureSymbiosis {
+  /** Optional deployment binding required to enable Symbiosis. */
+  type Options = {
+    /** Symbiosis quote-user binding. */
+    userAddress?: string | undefined
+  }
+}
+
 /** Creates an Across quote adapter backed by `/swap/approval`. */
 export function across(options: across.Options): FundingQuotes.ProviderAdapter {
   assertAcrossConfiguration(options)
@@ -397,9 +451,87 @@ export declare namespace squid {
   }
 }
 
+/** Creates a Symbiosis quote adapter backed by `/v2/quote`. */
+export function symbiosis(options: symbiosis.Options): FundingQuotes.ProviderAdapter {
+  assertUserAddress(options.userAddress)
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultSymbiosisBaseUrl)
+  const fetcher = options.fetch ?? defaultFetch
+  const now = options.now ?? (() => new Date())
+  const rateLimitStore = options.rateLimitStore ?? Store.memory()
+
+  return {
+    async probeQuote({ candidate }, signal) {
+      const fromChainId = Number(providerChainId(candidate.sourceChain, 'symbiosis'))
+      const fromToken = symbiosisSourceToken(candidate.sourceChain, candidate.sourceToken)
+      const toChainId = Number(eip155ChainId(candidate.destinationChain))
+
+      try {
+        await consumeSymbiosisQuota(rateLimitStore, now())
+        const quote = await requestJson(new URL(`${baseUrl}/v2/quote`), {
+          body: {
+            from: options.userAddress,
+            slippage: 100,
+            to: options.userAddress,
+            tokenAmountIn: {
+              address: fromToken,
+              amount: candidate.sourceAmount.amount,
+              chainId: fromChainId,
+              decimals: candidate.sourceToken.decimals,
+              symbol: candidate.sourceToken.symbol,
+            },
+            tokenOut: {
+              address: candidate.destinationToken.address,
+              chainId: toChainId,
+              decimals: candidate.destinationToken.decimals,
+              symbol: candidate.destinationToken.symbol,
+            },
+          },
+          fetcher,
+          headers: { 'x-partner-id': 'tempo' },
+          method: 'POST',
+          signal,
+        })
+        return formatSymbiosisResult(candidate, quote, now())
+      } catch (cause) {
+        const unavailable =
+          providerUnavailable(cause, [
+            'AMOUNT_TOO_LOW',
+            'NO_ROUTE',
+            'NO_ROUTE_FOUND',
+            'ROUTE_NOT_FOUND',
+            'UNSUPPORTED_ROUTE',
+          ]) ?? symbiosisUnavailable(cause)
+        if (!unavailable) throw cause
+        return unavailableResult({
+          detail: 'symbiosis:quote-v2',
+          message: unavailable,
+          now: now(),
+          source: 'providerQuote',
+        })
+      }
+    },
+  }
+}
+
+export declare namespace symbiosis {
+  /** Symbiosis quote adapter options. */
+  type Options = {
+    /** Override for tests or Symbiosis test environments. */
+    baseUrl?: string | undefined
+    /** Fetch implementation override for tests. */
+    fetch?: Fetch | undefined
+    /** Clock override for deterministic tests. */
+    now?: (() => Date) | undefined
+    /** Atomic store used to enforce the provider-wide quote quota. */
+    rateLimitStore?: Store.Store | undefined
+    /** Probe wallet address used as the Symbiosis sender and recipient. */
+    userAddress: string
+  }
+}
+
 /** Returns bounded provider failure details suitable for structured request logs. */
 export function providerFailure(options: providerFailure.Options): providerFailure.Result {
-  const operation = providerOperations[options.provider]
+  const operation = providerOperation(options.provider)
   if (
     options.cause instanceof FundingQuotes.ProviderAdapterTimeoutError ||
     (options.cause instanceof DOMException && options.cause.name === 'AbortError')
@@ -417,6 +549,8 @@ export function providerFailure(options: providerFailure.Options): providerFailu
   }
   if (options.cause instanceof ProviderPayloadError)
     return { failure: 'payload', id: options.provider, operation }
+  if (options.cause instanceof ProviderRateLimitError)
+    return { failure: 'rate_limit', id: options.provider, operation }
   if (options.cause instanceof TypeError)
     return { failure: 'network', id: options.provider, operation }
   return { failure: 'unknown', id: options.provider, operation }
@@ -431,7 +565,7 @@ export declare namespace providerFailure {
     /** Stable provider error code, when one is safe to retain. */
     code?: string | undefined
     /** Failure boundary that rejected the provider request. */
-    failure: 'http' | 'network' | 'payload' | 'timeout' | 'unknown'
+    failure: 'http' | 'network' | 'payload' | 'rate_limit' | 'timeout' | 'unknown'
     /** Provider identifier. */
     id: FundingQuotes.ProviderId
     /** Provider operation identifier. */
@@ -585,6 +719,68 @@ function formatSquidResult(
   }
 }
 
+function formatSymbiosisResult(
+  candidate: FundingQuotes.QuoteCandidate,
+  quote: unknown,
+  now: Date,
+): FundingQuotes.QuoteProbeResult {
+  const parsed = schema.SymbiosisQuote.safeParse(quote)
+  if (!parsed.success) throw new ProviderPayloadError()
+  const response = parsed.data
+  const sourceChainId = Number(providerChainId(candidate.sourceChain, 'symbiosis'))
+  const sourceToken = symbiosisSourceToken(candidate.sourceChain, candidate.sourceToken)
+  const firstToken = response.routes[0]!.tokens[0]!
+  const lastRoute = response.routes[response.routes.length - 1]!
+  const lastToken = lastRoute.tokens[lastRoute.tokens.length - 1]!
+  if (
+    response.tx.chainId !== sourceChainId ||
+    response.type !== candidate.sourceChain.kind ||
+    !matchesSymbiosisToken(firstToken, {
+      address: sourceToken,
+      chainId: sourceChainId,
+      decimals: candidate.sourceToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(lastToken, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(response.tokenAmountOut, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    !matchesSymbiosisToken(response.tokenAmountOutMin, {
+      address: candidate.destinationToken.address,
+      chainId: Number(eip155ChainId(candidate.destinationChain)),
+      decimals: candidate.destinationToken.decimals,
+    }) ||
+    BigInt(response.tokenAmountOut.amount) <= 0n ||
+    BigInt(response.tokenAmountOutMin.amount) <= 0n ||
+    BigInt(response.tokenAmountOutMin.amount) > BigInt(response.tokenAmountOut.amount)
+  )
+    throw new ProviderPayloadError()
+
+  return {
+    minimumOutputAmount: response.tokenAmountOutMin.amount,
+    outputAmount: response.tokenAmountOut.amount,
+    outputAmountFormatted: decimalFromBaseUnits(
+      response.tokenAmountOut.amount,
+      candidate.destinationToken.decimals,
+    ),
+    quality: {
+      ...(response.estimatedTime === undefined
+        ? {}
+        : { estimatedSeconds: Math.ceil(response.estimatedTime) }),
+      liquiditySource: 'providerQuote',
+      sourceDetail: 'symbiosis:quote-v2',
+      tier: 'liquid',
+    },
+    sampledAt: now.toISOString(),
+    status: 'available',
+  }
+}
+
 function unavailableResult(options: {
   detail: string
   message: string
@@ -664,6 +860,22 @@ function squidUnavailable(cause: unknown) {
   return undefined
 }
 
+function symbiosisUnavailable(cause: unknown) {
+  if (!(cause instanceof ProviderResponseError) || cause.status !== 400) return undefined
+  const body = record(cause.body)
+  if (body['message'] === 'Amount is too low to cover fees') return 'AMOUNT_TOO_LOW'
+  return undefined
+}
+
+async function consumeSymbiosisQuota(store: Store.Store, now: Date) {
+  const time = now.getTime()
+  const bucket = Math.floor(time / symbiosisRateLimitWindowMs)
+  const count = await Store.increment(store, `funding:symbiosis:quote:${bucket}`, {
+    ttl: symbiosisRateLimitWindowMs * 2,
+  })
+  if (count > symbiosisRateLimit) throw new ProviderRateLimitError()
+}
+
 function providerChainId(
   quoteChain: FundingQuotes.QuoteCandidate['sourceChain'],
   provider: string,
@@ -694,6 +906,16 @@ function rhinoToken(token: FundingQuotes.TokenRef) {
   return id
 }
 
+function symbiosisSourceToken(chain: FundingQuotes.ChainRef, token: FundingQuotes.TokenRef) {
+  if (chain.kind !== 'tron') return token.address
+  const tokens: Record<string, string> = {
+    TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: '0xa614f803b6fd780986a42c78ec9c7f77e6ded13c',
+  }
+  const id = tokens[token.address]
+  if (!id) throw new UnsupportedProviderTokenError()
+  return id
+}
+
 function matchesToken(
   token: z.output<typeof schema.AcrossQuote>['inputToken'],
   chain: FundingQuotes.ChainRef,
@@ -718,6 +940,29 @@ function matchesSquidToken(
   )
 }
 
+function matchesSymbiosisToken(
+  token: z.output<typeof schema.SymbiosisToken>,
+  options: matchesSymbiosisToken.Options,
+) {
+  return (
+    token.address.toLowerCase() === options.address.toLowerCase() &&
+    token.chainId === options.chainId &&
+    token.decimals === options.decimals
+  )
+}
+
+declare namespace matchesSymbiosisToken {
+  /** Expected provider token identity. */
+  type Options = {
+    /** Provider-specific token address. */
+    address: string
+    /** Provider-specific chain id. */
+    chainId: number
+    /** Token decimal precision. */
+    decimals: number
+  }
+}
+
 function eip155ChainId(chain: { id: string; kind: string }) {
   if (chain.kind !== 'evm') throw new UnsupportedProviderChainError()
   const match = /^eip155:(\d+)$/.exec(chain.id)
@@ -785,8 +1030,12 @@ function assertAcrossConfiguration(options: across.Options) {
 }
 
 function assertSquidConfiguration(options: squid.Options) {
-  if (options.integratorId.length === 0 || !/^0x[\da-fA-F]{40}$/.test(options.userAddress))
-    throw new ProviderConfigurationError()
+  if (options.integratorId.length === 0) throw new ProviderConfigurationError()
+  assertUserAddress(options.userAddress)
+}
+
+function assertUserAddress(userAddress: string) {
+  if (!/^0x[\da-fA-F]{40}$/.test(userAddress)) throw new ProviderConfigurationError()
 }
 
 class ProviderConfigurationError extends Error {
@@ -797,6 +1046,10 @@ class ProviderPayloadError extends Error {
   override name = 'FundingQuoteProviders.ProviderPayloadError'
 }
 
+class ProviderRateLimitError extends Error {
+  override name = 'FundingQuoteProviders.ProviderRateLimitError'
+}
+
 class ProviderResponseError extends Error {
   override name = 'FundingQuoteProviders.ProviderResponseError'
 

package/src/apps/data/FxOracle.test.ts

@@ -0,0 +1,118 @@
+import * as FxOracle from './FxOracle.js'
+
+const set = {
+  asOf: '2026-01-01',
+  base: 'EUR',
+  rates: { AUD: '1.6', USD: '1.25' },
+} satisfies FxOracle.RateSet
+
+function feedUrl(usd: string) {
+  const body = `<Envelope><Cube><Cube time="2026-01-01"><Cube currency="AUD" rate="1.6"/><Cube currency="USD" rate="${usd}"/></Cube></Cube></Envelope>`
+  return `data:application/xml,${encodeURIComponent(body)}`
+}
+
+describe('from', () => {
+  test('applies the default ttl and preserves overrides', () => {
+    const oracle = FxOracle.from({ name: 'test', rates: async () => set })
+    expect(oracle.name).toBe('test')
+    expect(oracle.ttl).toMatchInlineSnapshot(`3600000`)
+    expect(FxOracle.from({ name: 'test', rates: async () => set, ttl: 5 }).ttl).toBe(5)
+  })
+
+  test('resolves the definition rates', async () => {
+    const oracle = FxOracle.from({ name: 'test', rates: async () => set })
+    await expect(oracle.rates()).resolves.toEqual(set)
+  })
+
+  test('rethrows rates failures as RatesError', async () => {
+    const oracle = FxOracle.from({
+      name: 'test',
+      rates: async () => {
+        throw new Error('boom')
+      },
+    })
+    const error = await oracle.rates().catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect(error).toMatchInlineSnapshot(
+      `[FxOracle.RatesError: FX oracle "test" failed to produce rates]`,
+    )
+    expect((error as Error).cause).toMatchInlineSnapshot(`[Error: boom]`)
+  })
+})
+
+describe('ecb', () => {
+  test('fetches and parses the daily reference rates', async () => {
+    const rates = await FxOracle.ecb({ url: feedUrl('1.25') }).rates()
+    expect(rates).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-01-01",
+        "base": "EUR",
+        "rates": {
+          "AUD": "1.6",
+          "USD": "1.25",
+        },
+      }
+    `)
+  })
+
+  test.each(['', '-1.25', '1..25'])('rejects malformed rate %j', async (value) => {
+    const error = await FxOracle.ecb({ url: feedUrl(value) })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects non-positive rates', async () => {
+    const error = await FxOracle.ecb({ url: feedUrl('0.0') })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects rates below fixed-point precision', async () => {
+    const error = await FxOracle.ecb({ url: feedUrl('0.0000000000000000001') })
+      .rates()
+      .catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect((error as Error).cause).toMatchInlineSnapshot(
+      `[FxOracle.ParseError: Rate feed returned an unrecognized payload]`,
+    )
+  })
+
+  test('rejects with RatesError when the feed is unreachable', async () => {
+    const oracle = FxOracle.ecb({ url: 'http://127.0.0.1:1' })
+    const error = await oracle.rates().catch((error: unknown) => error)
+    expect(error).toBeInstanceOf(FxOracle.RatesError)
+    expect(error).toMatchInlineSnapshot(
+      `[FxOracle.RatesError: FX oracle "ecb" failed to produce rates]`,
+    )
+  })
+})
+
+describe('rate', () => {
+  test('derives cross rates through the base', () => {
+    expect(FxOracle.rate(set, { from: 'USD', to: 'AUD' })).toMatchInlineSnapshot(
+      `1280000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'EUR', to: 'USD' })).toMatchInlineSnapshot(
+      `1250000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'USD', to: 'EUR' })).toMatchInlineSnapshot(
+      `800000000000000000n`,
+    )
+    expect(FxOracle.rate(set, { from: 'USD', to: 'USD' })).toMatchInlineSnapshot(
+      `1000000000000000000n`,
+    )
+  })
+
+  test('returns undefined for currencies the set does not price', () => {
+    expect(FxOracle.rate(set, { from: 'BTC', to: 'USD' })).toBeUndefined()
+    expect(FxOracle.rate(set, { from: 'USD', to: 'XXX' })).toBeUndefined()
+  })
+})

package/src/apps/data/FxOracle.ts

@@ -0,0 +1,153 @@
+import { Value as core_Value } from 'ox'
+
+import * as Ttl from '../../internal/Ttl.js'
+
+/** A pluggable fiat FX rate oracle consumed by the valuation endpoint. */
+export type Oracle = {
+  /** Oracle identifier, surfaced as the valuation's `pricing.source` (e.g. `ecb`). */
+  name: string
+  /** Fetches the oracle's current rate set. */
+  rates: () => Promise<RateSet>
+  /** Cache lifetime for a fetched rate set, in milliseconds. */
+  ttl: number
+}
+
+/** One oracle-published set of exchange rates quoted against a base currency. */
+export type RateSet = {
+  /** Publication date of the rate set (e.g. `2026-07-20`). */
+  asOf: string
+  /** Currency the rates are quoted against (e.g. `EUR`). */
+  base: string
+  /** Currency code to units of that currency per one `base` unit, as decimal strings. */
+  rates: Record<string, string>
+}
+
+/** Fixed-point scale (decimal places) of cross rates returned by {@link rate}. */
+export const precision = 18
+
+/** Canonical ECB daily reference-rate feed (public, no key required). */
+export const ecbUrl = 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml'
+
+/**
+ * Normalizes an oracle definition into an {@link Oracle}: applies the default
+ * `ttl` and rethrows `rates()` failures as {@link RatesError}.
+ */
+export function from(oracle: from.Value): Oracle {
+  return {
+    name: oracle.name,
+    rates: async () => {
+      try {
+        return await oracle.rates()
+      } catch (cause) {
+        throw new RatesError(oracle.name, { cause })
+      }
+    },
+    ttl: oracle.ttl ?? Ttl.hours(1),
+  }
+}
+
+export declare namespace from {
+  /** Oracle definition accepted by {@link from}. */
+  type Value = Pick<Oracle, 'name' | 'rates'> & {
+    /** Cache lifetime for a fetched rate set, in milliseconds. @default `Ttl.hours(1)` */
+    ttl?: number | undefined
+  }
+}
+
+/**
+ * European Central Bank euro reference rates: one EUR-based set covering ~30
+ * currencies, published once per working day.
+ */
+export function ecb(options: ecb.Options = {}): Oracle {
+  const { fetch = globalThis.fetch, url = ecbUrl } = options
+  return from({
+    name: 'ecb',
+    rates: async () => {
+      const response = await fetch(url, {
+        headers: { accept: 'application/xml' },
+        signal: AbortSignal.timeout(10_000),
+      })
+      if (!response.ok) throw new ResponseError(response.status)
+      const text = await response.text()
+
+      // The daily file is a flat, stable XML shape; extract the `Cube`
+      // attributes directly rather than pulling in an XML parser.
+      const asOf = text.match(/<Cube time=['"](\d{4}-\d{2}-\d{2})['"]/)?.[1]
+      const rates: Record<string, string> = {}
+      for (const match of text.matchAll(
+        /<Cube currency=['"]([A-Z]{3})['"] rate=['"]([^'"]*)['"]/g,
+      )) {
+        const [, code, value] = match
+        if (
+          !code ||
+          !value ||
+          !/^\d+(?:\.\d+)?$/.test(value) ||
+          core_Value.from(value, precision) <= 0n
+        )
+          throw new ParseError()
+        rates[code] = value
+      }
+      if (!asOf || rates['USD'] === undefined) throw new ParseError()
+      return { asOf, base: 'EUR', rates }
+    },
+  })
+}
+
+export declare namespace ecb {
+  /** Options for the ECB oracle. */
+  type Options = {
+    /** Fetch implementation used to retrieve the feed. @default `globalThis.fetch` */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Feed URL. @default {@link ecbUrl} */
+    url?: string | undefined
+  }
+}
+
+/**
+ * Derives the cross rate from one currency to another through the set's base,
+ * scaled to {@link precision} decimal places. Returns `undefined` when the set
+ * prices neither leg of a currency.
+ */
+export function rate(set: RateSet, options: rate.Options): bigint | undefined {
+  const scaled = (code: string) => {
+    if (code === set.base) return 10n ** BigInt(precision)
+    const value = set.rates[code]
+    return value === undefined ? undefined : core_Value.from(value, precision)
+  }
+  const source = scaled(options.from)
+  const target = scaled(options.to)
+  if (source === undefined || target === undefined || source === 0n) return undefined
+  return (target * 10n ** BigInt(precision)) / source
+}
+
+export declare namespace rate {
+  /** Options for deriving a cross rate. */
+  type Options = {
+    /** Currency code to convert from. */
+    from: string
+    /** Currency code to convert to. */
+    to: string
+  }
+}
+
+/** Thrown when an oracle fails to produce its rate set. */
+export class RatesError extends Error {
+  override name = 'FxOracle.RatesError'
+  constructor(oracle: string, options: { cause: unknown }) {
+    super(`FX oracle "${oracle}" failed to produce rates`, options)
+  }
+}
+
+class ParseError extends Error {
+  override name = 'FxOracle.ParseError'
+  constructor() {
+    super('Rate feed returned an unrecognized payload')
+  }
+}
+
+class ResponseError extends Error {
+  override name = 'FxOracle.ResponseError'
+  constructor(status: number) {
+    super(`Rate feed request failed with status ${status}`)
+  }
+}

package/src/apps/data/index.ts

@@ -1,3 +1,4 @@
 export { data } from './App.js'
 export * as FundingQuoteProviders from './FundingQuoteProviders.js'
+export * as FxOracle from './FxOracle.js'
 export * as Sponsorships from '../relay/Sponsorships.js'