tapimo 0.3.0 → 0.4.1

package/src/apps/data/routes/funding.ts

@@ -187,6 +187,12 @@ export namespace schema {
           z.describe('Explainable route score from 0 to 100, when enough signals are available.'),
           z.meta({ examples: [91] }),
         ),
+      sourceDetail: z
+        .nullable(z.string())
+        .check(
+          z.describe('Provider-specific source or endpoint detail for the quality signal.'),
+          z.meta({ examples: ['providerEndpoint'] }),
+        ),
       tier: z
         .enum(['liquid', 'thin', 'unknown', 'unavailable', 'error'])
         .check(
@@ -194,7 +200,72 @@ export namespace schema {
           z.meta({ examples: ['unknown'] }),
         ),
     }),
-    'Machine-readable liquidity, fee, and freshness signals for a route candidate.',
+    'Machine-readable liquidity, fee, and source signals for a route candidate.',
+  )
+
+  /** Provider-derived quote data for a route candidate. */
+  export const RouteQuote = Schema.describe(
+    z.object({
+      expiresAt: z
+        .nullable(z.iso.datetime())
+        .check(
+          z.describe('Provider quote expiry timestamp.'),
+          z.meta({ examples: ['2026-01-01T00:00:30Z'] }),
+        ),
+      inputAmount: Schema.DecimalString.check(
+        z.describe('Source amount sent to the provider in base units.'),
+        z.meta({ examples: ['1000000'] }),
+      ),
+      limits: z
+        .nullable(
+          z.object({
+            instantSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported instant source amount capacity.'),
+                z.meta({ examples: ['12453940000'] }),
+              ),
+            maxSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported maximum source amount.'),
+                z.meta({ examples: ['1114274433200'] }),
+              ),
+            minSourceAmount: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Provider-reported minimum source amount.'),
+                z.meta({ examples: ['500063'] }),
+              ),
+          }),
+        )
+        .check(z.describe('Provider limits expressed in source base units.')),
+      minimumOutputAmount: z
+        .nullable(Schema.DecimalString)
+        .check(
+          z.describe('Slippage-adjusted minimum destination amount in base units.'),
+          z.meta({ examples: ['988000'] }),
+        ),
+      outputAmount: z
+        .nullable(Schema.DecimalString)
+        .check(
+          z.describe('Expected destination amount in base units.'),
+          z.meta({ examples: ['989102'] }),
+        ),
+      outputAmountFormatted: z
+        .nullable(z.string())
+        .check(
+          z.describe('Expected destination amount rendered with destination token decimals.'),
+          z.meta({ examples: ['0.989102'] }),
+        ),
+      sampledAt: z.iso
+        .datetime()
+        .check(
+          z.describe('Timestamp for the live quote or route probe.'),
+          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
+        ),
+    }),
+    'Provider-derived quote, limit, and freshness data for a route candidate.',
   )
 
   /** Static or live funding route candidate. */
@@ -202,6 +273,12 @@ export namespace schema {
     z.object({
       destinationChain: Chain.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
       destinationToken: Token.check(z.describe('Tempo token expected from this route.')),
+      errorCode: z
+        .nullable(z.string())
+        .check(
+          z.describe('Stable route error code, when status is `error`.'),
+          z.meta({ examples: ['provider_timeout'] }),
+        ),
       id: z
         .string()
         .check(
@@ -210,6 +287,9 @@ export namespace schema {
         ),
       provider: ProviderRef,
       quality: Quality,
+      quote: z
+        .nullable(RouteQuote)
+        .check(z.describe('Provider-derived quote data, when a live route probe succeeds.')),
       sourceAmount: TokenAmount,
       sourceChain: Chain.check(z.describe('Chain where the caller currently holds funds.')),
       sourceToken: Token.check(z.describe('Token the caller currently holds.')),
@@ -278,6 +358,12 @@ export namespace schema {
             ),
             z.meta({ examples: ['USDC.e'] }),
           ),
+        include: z
+          .optional(z.string())
+          .check(
+            z.describe('Comma-separated response expansions. V1 accepts `quotes`.'),
+            z.meta({ examples: ['quotes'] }),
+          ),
         limit: Schema.Limit,
         provider: z
           .optional(z.string())
@@ -380,7 +466,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=base&sourceToken=USDC&sourceAmount=1000000&provider=across`',
     summary: 'Base USDC',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'across',
         sourceAmount: '1000000',
@@ -395,7 +481,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=solana&sourceToken=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&sourceAmount=1000000&provider=bridge`',
     summary: 'Solana USDC',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'bridge',
         sourceAmount: '1000000',
@@ -410,7 +496,7 @@ const fundingRouteResponseExamples = {
       '`GET /v1/funding/routes?sourceChain=tron&sourceToken=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t&sourceAmount=1000000&provider=bridge`',
     summary: 'Tron USDT',
     value: {
-      data: FundingRoutes.listRoutes({
+      data: FundingRoutes.listStaticRoutes({
         limit: 10,
         provider: 'bridge',
         sourceAmount: '1000000',
@@ -433,7 +519,7 @@ const providersResponseExample = {
 } satisfies z.output<typeof schema.listProviders.Response>
 
 /** Mounts funding route discovery and generic provider inventory endpoints. */
-export function funding() {
+export function funding(options: funding.Options = {}) {
   return new Hono<App.Environment>()
     .get(
       '/v1/funding/routes',
@@ -444,7 +530,7 @@ export function funding() {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists provider-specific route candidates for moving a source stablecoin amount into Tempo. This endpoint is discovery-only: it does not execute a bridge, reserve liquidity, guarantee settlement, or return live quotes. Static inventory candidates use `status: unknown` and `quality.liquiditySource: staticInventory`.',
+          'Lists provider-specific route candidates for moving a source stablecoin amount into Tempo. This endpoint is discovery-only: it does not execute a bridge, reserve liquidity, or guarantee settlement. Static inventory candidates use `status: unknown`; provider adapters may add best-effort live quote fields.',
         operationId: 'listFundingRoutes',
         responses: OpenApi.responses({
           errors: { 400: { codes: ['query_invalid'] } },
@@ -473,10 +559,15 @@ export function funding() {
 
         const query = c.req.valid('query')
         try {
+          const include = FundingRoutes.parseInclude(query.include)
           return c.json(
             Response.validated(schema.listFundingRoutes.Response, {
-              data: FundingRoutes.listRoutes({
+              data: await FundingRoutes.listRoutes({
+                adapters: options.adapters,
+                adapterTimeoutMs: options.adapterTimeoutMs,
+                cache: { bypass: cacheBypass(c.req.raw) },
                 destinationToken: query.destinationToken,
+                include,
                 limit: query.limit,
                 provider: query.provider,
                 sourceAmount: query.sourceAmount,
@@ -564,7 +655,10 @@ export function funding() {
         const query = c.req.valid('query')
         return c.json(
           Response.validated(schema.listProviders.Response, {
-            data: FundingRoutes.listProviders({ capability: query.capability }),
+            data: FundingRoutes.listProviders({
+              adapters: options.adapters,
+              capability: query.capability,
+            }),
           }),
           200,
         )
@@ -572,9 +666,20 @@ export function funding() {
     )
 }
 
+export declare namespace funding {
+  /** Options for funding route discovery. */
+  type Options = {
+    /** Provider adapters used to enrich static inventory with live data. */
+    adapters?: FundingRoutes.ProviderAdapters | undefined
+    /** Per-provider quote timeout in milliseconds. */
+    adapterTimeoutMs?: number | undefined
+  }
+}
+
 // Maps caller-input errors to a specific 400 message; anything else rethrows.
 function requestErrorMessage(cause: unknown) {
   if (cause instanceof FundingRoutes.InvalidAmountError) return 'Invalid `sourceAmount`.'
+  if (cause instanceof FundingRoutes.UnsupportedIncludeError) return 'Unsupported `include`.'
   if (cause instanceof FundingRoutes.UnsupportedDestinationTokenError)
     return 'Unsupported `destinationToken`.'
   if (cause instanceof FundingRoutes.UnsupportedProviderError) return 'Unsupported `provider`.'
@@ -582,3 +687,12 @@ function requestErrorMessage(cause: unknown) {
     return 'Unsupported `sourceChain`.'
   return undefined
 }
+
+function cacheBypass(request: Request) {
+  const directives = (
+    request.headers.get('Cache-Control') ??
+    request.headers.get('Pragma') ??
+    ''
+  ).toLowerCase()
+  return directives.includes('no-cache') || directives.includes('no-store')
+}

package/src/apps/data/routes/rpc.test.ts

@@ -338,6 +338,39 @@ describe('POST /rpc', () => {
       fetch.restore()
     }
   })
+
+  test('uses the RPC path for sandbox chain checks', async () => {
+    const app = TestApp.create({
+      auth: {
+        keys: [
+          {
+            environment: 'sandbox',
+            id: 'key_sandbox',
+            orgId: 'org_test',
+            scopes: ['data:read'],
+            token: 'secret_sandbox_key',
+          },
+        ],
+      },
+      defaultChainId: 4217,
+    })
+    const request = (path: string) =>
+      app.fetch(
+        new Request(`http://tempo-api.test${path}`, {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          headers: { 'tempo-api-key': 'secret_sandbox_key' },
+          method: 'POST',
+        }),
+      )
+
+    const rejected = await request('/rpc/4217?chainId=42431')
+    const rejectedDefault = await request('/rpc?chainId=42431')
+    const rejectedTrailing = await request('/rpc/?chainId=42431')
+
+    expect(rejected.status).toMatchInlineSnapshot(`403`)
+    expect(rejectedDefault.status).toMatchInlineSnapshot(`403`)
+    expect(rejectedTrailing.status).toMatchInlineSnapshot(`404`)
+  })
 })
 
 describe('POST /rpc/relay', () => {

package/src/apps/docs/App.ts

@@ -10,7 +10,7 @@ import * as Metadata from '../metadata.js'
  *
  * ```ts
  * import { docs } from 'tapimo/docs'
- * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * App.create(options).route('/', data()).route('/', management()).route('/', docs())
  * ```
  *
  * The group registers no routes itself: it carries a reference factory (via

package/src/apps/index.ts

@@ -1,4 +1,4 @@
-export { data } from './data/index.js'
+export { data, FundingRouteProviders } from './data/index.js'
+export { management } from './management/index.js'
 export { mcp } from './mcp.js'
-export { platform } from './platform/index.js'
 export { relay } from './relay/index.js'

package/src/apps/{platform → management}/App.ts

@@ -22,7 +22,7 @@ import { usage } from './routes/usage.js'
 export type Email = {
   /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
   consoleUrl?: string | undefined
-  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  /** Sender address for management emails (e.g. `noreply@tempo.xyz`). */
   from: string
   /** Sends one message. */
   send: (message: Email.Message) => Promise<unknown>
@@ -69,32 +69,32 @@ export type Billing = {
 }
 
 /**
- * Request environment for platform routes: the shared app environment plus the
+ * Request environment for management routes: the shared app environment plus the
  * capabilities this group publishes on context (`billing`, `email`). Owned
- * here, not in core `App.Environment`, since these are platform concerns.
+ * here, not in core `App.Environment`, since these are management concerns.
  */
 export type Environment = {
   Variables: App.Environment['Variables'] & {
     /** Stripe billing capability; undefined when billing is unconfigured. */
     billing: Billing | undefined
-    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    /** Transactional email sender for management emails; undefined when dispatch is disabled. */
     email: Email | undefined
   }
 }
 
 /**
- * The tenant-platform route group: the current user, orgs, projects, members,
+ * The management route group: the current user, orgs, projects, members,
  * invitations, and API-key management. Every route reads its dependencies from
  * request context set by {@link App.create}.
  *
  * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
- * {@link App.create}, so platform routes gate on a session without owning it.
+ * {@link App.create}, so management routes gate on a session without owning it.
  *
  * ```ts
- * App.create(options).route('/', platform())
+ * App.create(options).route('/', management())
  * ```
  */
-export function platform(options: platform.Options = {}) {
+export function management(options: management.Options = {}) {
   const app = new Hono<Environment>()
     // Publish this group's capabilities for handlers; undefined disables each.
     .use('*', async (c, next) => {
@@ -114,21 +114,21 @@ export function platform(options: platform.Options = {}) {
   return Metadata.attach(app, openapi)
 }
 
-export declare namespace platform {
-  /** Options for the platform route group. */
+export declare namespace management {
+  /** Options for the management route group. */
   type Options = {
     /** Expose the API-key management routes in the OpenAPI document. @default true */
     apiKeys?: boolean | undefined
     /** Stripe billing capability; omit to disable billing routes (501) and keep production sponsorship closed. */
     billing?: Billing | undefined
-    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    /** Transactional email sender for management emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
     email?: Email | undefined
   }
 }
 
 /**
- * The OpenAPI metadata this group owns: platform operation tags and the
- * `session` security scheme. Tagged onto the {@link platform} instance so
+ * The OpenAPI metadata this group owns: management operation tags and the
+ * `session` security scheme. Tagged onto the {@link management} instance so
  * `App.create` collects it.
  */
 const openapi = {
@@ -152,7 +152,7 @@ const openapi = {
   ],
   'x-tagGroups': [
     {
-      name: 'Platform API',
+      name: 'Management API',
       tags: [
         'API Keys',
         'Authentication',

package/src/apps/{platform → management}/index.ts

@@ -1,2 +1,2 @@
-export { platform } from './App.js'
+export { management } from './App.js'
 export * as Billing from './Billing.js'

package/src/apps/{platform → management}/routes/api-keys.ts

@@ -494,7 +494,7 @@ export declare namespace apiKeys {
   }
 }
 
-/** Projects a persisted record onto the platform key shape (no rate limits, no token). */
+/** Projects a persisted record onto the management key shape (no rate limits, no token). */
 function serializeKey(record: ApiKeys.Record) {
   return {
     createdAt: record.createdAt,

package/src/apps/{platform → management}/routes/invitations.ts

@@ -206,7 +206,7 @@ export namespace schema {
  * Mounts the invitations surface: org-scoped management
  * (`/orgs/:orgId/invitations`, admins and owners) plus the invitee's side
  * (`/invitations`, matched against the session's verified email). Invitation
- * emails dispatch through the sender the platform group publishes on context
+ * emails dispatch through the sender the management group publishes on context
  * (`c.get('email')`), best-effort.
  */
 export function invitations() {

package/src/apps/mcp.test.ts

@@ -114,7 +114,7 @@ test('scopes tools to the data domain', async () => {
   expect(tools).toContain('docs_search')
   // RPC is part of the data domain tag group.
   expect(tools.some((name) => name.startsWith('rpc'))).toBe(true)
-  // Out of domain: CoinGecko mirrors, session auth, platform, relay.
+  // Out of domain: CoinGecko mirrors, session auth, management, relay.
   expect(tools.some((name) => name.startsWith('gecko_'))).toBe(false)
   expect(tools.some((name) => name.startsWith('v1_auth_'))).toBe(false)
   expect(tools.some((name) => name.startsWith('v1_orgs'))).toBe(false)

package/src/apps/mcp.ts

@@ -201,7 +201,7 @@ const methods: readonly string[] = ['delete', 'get', 'head', 'options', 'patch',
 
 /**
  * Narrows the document to the data domain: operations tagged inside the
- * `Data API` tag group, minus excluded tags. Platform, relay, and session
+ * `Data API` tag group, minus excluded tags. Management, relay, and session
  * operations never surface as tools.
  */
 function scope(document: Document): Openapi.OpenAPISpec {

package/src/apps/relay/App.test.ts

@@ -16,7 +16,7 @@ import * as Fees from '../../internal/Fees.js'
 import * as Organizations from '../../db/tables/organizations.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
-import * as core_Billing from '../platform/Billing.js'
+import * as core_Billing from '../management/Billing.js'
 import * as RequestListener from '../../handlers/internal/requestListener.js'
 import * as Viem from '../../internal/Viem.js'
 import * as Sponsorships from './Sponsorships.js'

package/src/apps/relay/App.ts

@@ -8,7 +8,7 @@ import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
-import * as Billing from '../platform/Billing.js'
+import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
 import * as OpenApi from '../../internal/OpenApi.js'

package/src/handlers/relay.test-d.ts

@@ -0,0 +1,8 @@
+import { Handler } from 'tapimo'
+
+describe('Handler.relay', () => {
+  test('accepts Tempo API defaults', () => {
+    expectTypeOf(Handler.relay()).toEqualTypeOf<Handler.Handler>()
+    expectTypeOf(Handler.relay({ apiKey: 'secret_api_key' })).toEqualTypeOf<Handler.Handler>()
+  })
+})

package/src/handlers/relay.test.ts

@@ -16,8 +16,8 @@ const recipient = Relay.accounts[7]!
 
 /**
  * Tokens the relay handler probes for fee-token resolution. The default
- * `resolveTokens` fetches `tokenlist.tempo.xyz`, which doesn't know about
- * the localnet chain — so tests inject this list explicitly.
+ * `resolveTokens` uses the Tempo API for mainnet and testnet, so localnet
+ * tests inject this list explicitly.
  */
 const localnetTokens = [
   {

package/src/handlers/relay.ts

@@ -16,8 +16,10 @@ import {
 import type { LocalAccount } from 'viem/accounts'
 import { simulateCalls } from 'viem/actions'
 import { Abis, Actions, Addresses, Capabilities, VirtualAddress } from 'viem/tempo'
+import { tempoMainnet, tempoTestnet } from 'viem/tempo/chains'
 
 import * as ExecutionError from './internal/executionError.js'
+import * as TempoApi from '../Client.js'
 import type * as RpcSchema from '../internal/RpcSchema.js'
 import { type Handler, from } from '../Handler.js'
 import * as Store from '../internal/Store.js'
@@ -25,6 +27,8 @@ import * as Multisig from './internal/multisig.js'
 import * as Sponsorship from './internal/sponsorship.js'
 import * as Utils from './internal/utils.js'
 
+const defaultChains = [tempoMainnet, tempoTestnet] as const
+
 /**
  * Instantiates a relay handler that proxies `eth_fillTransaction`
  * with wallet-aware enrichment (fee token resolution, simulation,
@@ -32,9 +36,9 @@ import * as Utils from './internal/utils.js'
  *
  * @example
  * ```ts
- * import { Handler } from 'tempo-api/server'
+ * import { Handler } from 'tapimo'
  *
- * const handler = Handler.relay({ getClient })
+ * const handler = Handler.relay({ apiKey: process.env.TEMPO_API_KEY })
  *
  * // Plug handler into your server framework of choice:
  * createServer(handler.listener)              // Node.js
@@ -51,10 +55,9 @@ import * as Utils from './internal/utils.js'
  *
  * ```ts
  * import { privateKeyToAccount } from 'viem/accounts'
- * import { Handler } from 'tempo-api/server'
+ * import { Handler } from 'tapimo'
  *
  * const handler = Handler.relay({
- *   getClient,
  *   feePayer: {
  *     account: privateKeyToAccount('0x...'),
  *   },
@@ -64,26 +67,26 @@ import * as Utils from './internal/utils.js'
  * @param options - Options.
  * @returns Request handler.
  */
-export function relay(options: relay.Options): Handler {
+export function relay(options: relay.Options = {}): Handler {
   const {
-    getClient,
+    apiKey,
+    getClient: getClient_,
     internal_allowUnsafeUrls = false,
     onRequest,
     path = '/',
-    resolveTokens,
+    resolveTokens: resolveTokens_,
     ...rest
   } = options
+  const getClient = getClient_ ?? defaultGetClient({ apiKey })
+  const resolveTokens = resolveTokens_ ?? defaultResolveTokens({ apiKey })
   const feePayerOptions = options.feePayer
   // Adapt the state store into the multisig operation store once, up front.
   const multisigOptions = options.multisig
     ? { ...options.multisig, store: Multisig.fromStore(options.multisig.store) }
     : undefined
 
-  // Resolves the chain's fee-token candidates through the caller-provided
-  // resolver. An unconfigured resolver (or a chain it has no list for) yields
-  // an empty candidate set.
   const getTokens = async (chainId: number | undefined): Promise<readonly Address[]> => {
-    if (!resolveTokens || chainId === undefined) return []
+    if (chainId === undefined) return []
     return await resolveTokens(chainId)
   }
 
@@ -94,7 +97,7 @@ export function relay(options: relay.Options): Handler {
 
   const features = {
     autoSwap: options.autoSwap ?? options.features === 'all',
-    feeTokenResolution: options.features === 'all' || Boolean(resolveTokens),
+    feeTokenResolution: options.features === 'all' || Boolean(resolveTokens_),
     simulate: options.features === 'all',
   }
 
@@ -175,6 +178,7 @@ export function relay(options: relay.Options): Handler {
           let filled: Awaited<ReturnType<typeof fill>>
           let sponsored = false
           let feeToken = sponsoredFeeToken
+          const tokens = getTokens(chainId)
 
           // Lazily resolve a swap source token when autoSwap needs one.
           const resolveFeeTokenForSwap = from
@@ -183,7 +187,7 @@ export function relay(options: relay.Options): Handler {
                   account: from,
                   feeToken: undefined,
                   store,
-                  tokens: (await getTokens(chainId)).filter(
+                  tokens: (await tokens).filter(
                     (t) => t.toLowerCase() !== insufficientToken.toLowerCase(),
                   ),
                 })
@@ -194,7 +198,7 @@ export function relay(options: relay.Options): Handler {
           // the transaction is calling — typically the token being
           // transferred — so a user transferring USDC.e can pay gas in
           // USDC.e even when the configured list defaults to pathUSD.
-          const configuredTokens = await getTokens(chainId)
+          const configuredTokens = await tokens
           const unsponsoredTokens = [
             ...configuredTokens,
             ...callTargetTokens(baseTx).filter(
@@ -221,7 +225,7 @@ export function relay(options: relay.Options): Handler {
             //     `validate` only governs the wallet's own fee payer).
             // Default to the chain's first token so the broadcast envelope
             // always carries a feeToken the chain can charge.
-            if (!feeToken) feeToken = (await getTokens(chainId))[0]
+            if (!feeToken) feeToken = configuredTokens[0]
             const transaction = {
               ...baseTx,
               feePayer: true,
@@ -334,8 +338,7 @@ export function relay(options: relay.Options): Handler {
           const transaction_filled = filled.transaction
           const swap = 'swap' in filled ? filled.swap : undefined
           if (!feeToken)
-            feeToken =
-              (transaction_filled.feeToken as Address | undefined) ?? (await getTokens(chainId))[0]
+            feeToken = (transaction_filled.feeToken as Address | undefined) ?? configuredTokens[0]
 
           // Parallelize: simulate, fee payer signing, and autoSwap metadata.
           const alreadySigned =
@@ -648,8 +651,46 @@ export function relay(options: relay.Options): Handler {
   return router
 }
 
+function defaultGetClient(options: { apiKey?: string | undefined }) {
+  const clients = new Map<number, Client>()
+  for (const chain of defaultChains) {
+    const transport = options.apiKey
+      ? http(new URL(`/rpc/${chain.id}`, TempoApi.defaultUrl).toString(), {
+          fetchOptions: { headers: { 'tempo-api-key': options.apiKey } },
+        })
+      : http()
+    clients.set(
+      chain.id,
+      createClient({ batch: { multicall: { deployless: true } }, chain, transport }),
+    )
+  }
+
+  return (chainId: number = tempoMainnet.id): Client => {
+    const client = clients.get(chainId)
+    if (!client) throw new Error(`Chain ${chainId} not configured`)
+    return client
+  }
+}
+
+function defaultResolveTokens(options: { apiKey?: string | undefined }) {
+  const client = TempoApi.create({ apiKey: options.apiKey })
+
+  return async (chainId: number): Promise<readonly Address[]> => {
+    if (!defaultChains.some((chain) => chain.id === chainId)) return []
+    const response = await client.v1.tokenlist.$get({ query: { chainId: String(chainId) } })
+    if (response.status !== 200) return []
+    const { tokens } = await response.json()
+    return tokens.map((token) => token.address)
+  }
+}
+
 export namespace relay {
   export type Options = from.Options & {
+    /**
+     * Tempo API key used by the default RPC clients and token resolver. When
+     * omitted, RPC clients use each chain's default transport.
+     */
+    apiKey?: string | undefined
     /**
      * Auto-swap options.
      */
@@ -663,9 +704,9 @@ export namespace relay {
     /**
      * Resolves a viem client for a chain id. The handler resolves the client
      * from the `chainId` in the incoming transaction (falling back to the
-     * client's default chain). Called with no argument for the default client.
+     * client's default chain). Defaults to Tempo mainnet and testnet clients.
      */
-    getClient: (chainId?: number) => Client
+    getClient?: ((chainId?: number) => Client) | undefined
     /**
      * Fee payer / sponsor configuration. When provided, the relay will
      * sign `feePayerSignature` on the filled transaction.
@@ -721,9 +762,8 @@ export namespace relay {
     /** Path to use for the handler. @default "/" */
     path?: string | undefined
     /**
-     * Resolves the known fee-token candidates for a chain. The relay checks
-     * the caller's balance for each candidate and picks the highest during
-     * fee-token resolution. Omit to disable fee-token resolution.
+     * Resolves the known fee-token candidates for a chain. Defaults to the
+     * Tempo API verified token list for mainnet and testnet.
      */
     resolveTokens?:
       | ((chainId: number) => readonly Address[] | Promise<readonly Address[]>)

package/src/internal/Auth.ts

@@ -882,7 +882,7 @@ export function install(options: install.Options) {
       }),
     )
     return Object.assign(
-      // The tag joins the `Platform API` group at `platform()`'s chosen slot;
+      // The tag joins the `Management API` group at `management()`'s chosen slot;
       // group listings filter to defined tags, so it drops out when unmounted.
       Metadata.attach(app.route('/v1/auth/siwe', handler), {
         tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],