tapimo 0.13.0 → 0.15.0

package/src/apps/routes/routes/transfers.test.ts

@@ -0,0 +1,2876 @@
+import { AbiFunction, Hex, Value } from 'ox'
+import { decodeFunctionData, erc20Abi, maxUint256 } from 'viem'
+import { base } from 'viem/chains'
+import { tempoMainnet } from 'viem/tempo/chains'
+
+import * as Anvil from '../../../../test/Anvil.js'
+import * as TestApp from '../../../../test/App.js'
+import * as TestRoutes from '../../../../test/Routes.js'
+import * as RoutesIdempotencyTable from '../../../db/tables/routesIdempotency.js'
+import * as Organizations from '../../../db/tables/organizations.js'
+import * as RoutesSubsidies from '../../../db/tables/routesSubsidies.js'
+import * as StripeCustomers from '../../../db/tables/stripeCustomers.js'
+import * as Cache from '../../../internal/Cache.js'
+import type * as RoutesAction from '../../../internal/routes/Action.js'
+import * as RoutesCatalog from '../../../internal/routes/Catalog.js'
+import * as RoutesChain from '../../../internal/routes/Chain.js'
+import type * as RoutesObservability from '../../../internal/routes/Observability.js'
+import * as RoutesProvider from '../../../internal/routes/Provider.js'
+import * as RoutesTransfer from '../../../internal/routes/Transfer.js'
+import * as RoutesTransferReconciliation from '../../../internal/routes/TransferReconciliation.js'
+import * as RoutesTransferSubsidy from '../../../internal/routes/TransferSubsidy.js'
+import * as Idempotency from '../../../internal/Idempotency.js'
+import type * as Log from '../../../internal/Log.js'
+import * as Relay from '../../../internal/routes/providers/relay.js'
+import * as Stargate from '../../../internal/routes/providers/stargate.js'
+import * as Webhooks from '../../../internal/Webhooks.js'
+import * as Routes from './transfers.js'
+
+const db = TestApp.database()
+const destinationTransactionHash =
+  '0x3dfaba0a78b8f4bc09e55e05211c8120729e7b6879efe32613883befbca666da'
+
+/** Providers exercised against executable calls on a forked source chain. */
+const executableProviders = [
+  {
+    create: (_sender: string) =>
+      Relay.relay(process.env.RELAY_API_KEY ? { apiKey: process.env.RELAY_API_KEY } : {}),
+    destinationToken: 'pathusd',
+    id: 'relay',
+  },
+  {
+    create: (_sender: string) => Stargate.stargate(),
+    destinationToken: 'usdce',
+    id: 'stargate',
+  },
+] as const
+const stargateConfiguration = TestRoutes.snapshot.routesByProvider
+  .get('stargate')!
+  .find((candidate) => candidate.route.source.chain.id === 'eip155:8453')!.configuration!
+
+beforeAll(() => TestRoutes.publish(db))
+
+function create(options: TestApp.create.Options = {}) {
+  return TestApp.create({ ...options, db: options.db ?? db })
+}
+
+type ContractResponse = {
+  $ref?: string | undefined
+  content?: Record<string, { schema: unknown }> | undefined
+}
+
+type JsonSchema = {
+  $ref?: string | undefined
+  additionalProperties?: boolean | undefined
+  description?: string | undefined
+  examples?: readonly unknown[] | undefined
+  properties?: Record<string, JsonSchema> | undefined
+  required?: readonly string[] | undefined
+}
+
+type ComponentSpec = {
+  components: { schemas: Record<string, JsonSchema> }
+}
+
+function dereference(spec: ComponentSpec, schema: JsonSchema): JsonSchema {
+  if (!schema.$ref) return schema
+  const name = schema.$ref.split('/').at(-1)!
+  return spec.components.schemas[name]!
+}
+
+describe('GET /routes/transfers', () => {
+  test('requires the routes:read scope', async () => {
+    const app = transfersApp()
+    expect((await app.request('/v1/routes/transfers')).status).toBe(401)
+    const forbidden = await app.request('/v1/routes/transfers', as(TestApp.key))
+    expect(forbidden.status).toBe(403)
+  })
+
+  test('pages own transfers newest-first', async () => {
+    const app = transfersApp()
+    const first = await seedTransfer()
+    const second = await seedTransfer()
+    const third = await seedTransfer()
+    await seedTransfer({ orgId: routesForeign.orgId })
+
+    const response = await app.request('/v1/routes/transfers?limit=5', {
+      headers: { 'tempo-api-key': routesReader.token },
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe(Cache.policies.feed)
+    const etag = response.headers.get('etag') ?? ''
+    expect(etag).not.toBe('')
+    expect(response.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+    const body = await TestApp.json(response, Routes.schema.listRoutesTransfers.Response)
+    expect(body.data.map((transfer) => transfer.id)).toEqual([third.id, second.id, first.id])
+    expect(body.nextCursor).toBeNull()
+    expect(body.meta).toBeUndefined()
+
+    const unchanged = await app.request('/v1/routes/transfers?limit=5', {
+      headers: { 'if-none-match': etag, 'tempo-api-key': routesReader.token },
+    })
+    expect(unchanged.status).toBe(304)
+    expect(unchanged.headers.get('cache-control')).toBe(Cache.policies.feed)
+    expect(unchanged.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+
+    const paged = await TestApp.json(
+      await app.request(`/v1/routes/transfers?limit=5&cursor=${second.id}`, as(routesReader)),
+      Routes.schema.listRoutesTransfers.Response,
+    )
+    expect(paged.data.map((transfer) => transfer.id)).toEqual([first.id])
+  })
+
+  test('filters by status and embeds the capped count on request', async () => {
+    const app = transfersApp()
+    const expired = await seedTransfer()
+    await RoutesTransfer.transition(db, {
+      expectedVersion: 1,
+      id: expired.id,
+      status: 'expired',
+    })
+
+    const response = await app.request(
+      '/v1/routes/transfers?status=expired&include=totalCount',
+      as(routesReader),
+    )
+    const body = await TestApp.json(response, Routes.schema.listRoutesTransfers.Response)
+    expect(body.data.map((transfer) => transfer.id)).toEqual([expired.id])
+    expect(body.data[0]?.status).toBe('expired')
+    expect(body.meta).toEqual({ totalCount: 1, totalCountCapped: false })
+  })
+
+  test('narrows project-attributed keys to their project', async () => {
+    const app = transfersApp()
+    const scoped = await seedTransfer({ projectId: routesProjectReader.projectId })
+
+    const body = await TestApp.json(
+      await app.request('/v1/routes/transfers?limit=200', as(routesProjectReader)),
+      Routes.schema.listRoutesTransfers.Response,
+    )
+    expect(body.data.map((transfer) => transfer.id)).toEqual([scoped.id])
+
+    // The organization-attributed key sees the project row too.
+    const orgBody = await TestApp.json(
+      await app.request('/v1/routes/transfers?limit=200', as(routesReader)),
+      Routes.schema.listRoutesTransfers.Response,
+    )
+    expect(orgBody.data.map((transfer) => transfer.id)).toContain(scoped.id)
+  })
+
+  test('rejects invalid query parameters', async () => {
+    const app = transfersApp()
+    const response = await app.request('/v1/routes/transfers?status=bogus', as(routesReader))
+    expect(response.status).toBe(400)
+  })
+})
+
+describe('GET /routes/transfers/:id', () => {
+  test('returns the owned transfer directly, without an action', async () => {
+    const app = transfersApp()
+    const record = await seedTransfer()
+    const response = await app.request(`/v1/routes/transfers/${record.id}`, {
+      headers: { 'tempo-api-key': routesReader.token },
+    })
+    expect(response.status).toBe(200)
+    expect({
+      cacheControl: response.headers.get('cache-control'),
+      etag: response.headers.get('etag'),
+    }).toMatchInlineSnapshot(`
+      {
+        "cacheControl": "no-store",
+        "etag": null,
+      }
+    `)
+    expect(response.headers.get('vary')).toBe(
+      'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key',
+    )
+    const body = await TestApp.json(response, Routes.schema.getRoutesTransfer.Response)
+    expect(body).toEqual(RoutesTransfer.toPublic(record))
+    expect('action' in body).toBe(false)
+
+    const repeated = await app.request(`/v1/routes/transfers/${record.id}`, {
+      headers: { 'if-none-match': '"stale"', 'tempo-api-key': routesReader.token },
+    })
+    expect({
+      cacheControl: repeated.headers.get('cache-control'),
+      etag: repeated.headers.get('etag'),
+      status: repeated.status,
+    }).toMatchInlineSnapshot(`
+      {
+        "cacheControl": "no-store",
+        "etag": null,
+        "status": 200,
+      }
+    `)
+  })
+
+  test('hides foreign and absent transfers behind the same 404', async () => {
+    const app = transfersApp()
+    const record = await seedTransfer()
+
+    const foreign = await app.request(`/v1/routes/transfers/${record.id}`, as(routesForeign))
+    expect(foreign.status).toBe(404)
+    expect(((await foreign.json()) as { error: { code: string } }).error.code).toBe(
+      'routes_transfer_not_found',
+    )
+
+    const project = await app.request(`/v1/routes/transfers/${record.id}`, as(routesProjectReader))
+    expect(project.status).toBe(404)
+
+    const absent = await app.request(
+      '/v1/routes/transfers/rtr_000000000000000_000000000000000000000000',
+      as(routesReader),
+    )
+    expect(absent.status).toBe(404)
+  })
+})
+
+describe('POST /routes/transfers/:id/source-transactions', () => {
+  test('requires routes write access and validates the transaction hash array', async () => {
+    const app = transfersApp()
+    const transfer = await seedTransfer()
+    const path = `/v1/routes/transfers/${transfer.id}/source-transactions`
+    expect((await app.request(path, { method: 'POST' })).status).toBe(401)
+    expect((await app.request(path, { ...as(routesReader), method: 'POST' })).status).toBe(403)
+    for (const body of [
+      { transactionHashes: [] },
+      { transactionHashes: ['0xinvalid'] },
+      {
+        transactionHashes: Array.from(
+          { length: 11 },
+          (_, index) => `0x${index.toString(16).padStart(64, '0')}`,
+        ),
+      },
+    ])
+      expect(
+        (
+          await app.request(path, {
+            body: JSON.stringify(body),
+            headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+            method: 'POST',
+          })
+        ).status,
+      ).toBe(400)
+  })
+
+  test('accepts singular and plural requests before reporting missing reconciliation', async () => {
+    const app = transfersApp()
+    const transfer = await seedTransfer()
+    const transactionHash = `0x${'aa'.repeat(32)}`
+    for (const body of [{ transactionHash }, { transactionHashes: [transactionHash] }]) {
+      const response = await app.request(
+        `/v1/routes/transfers/${transfer.id}/source-transactions`,
+        {
+          body: JSON.stringify(body),
+          headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+          method: 'POST',
+        },
+      )
+      expect(response.status).toBe(501)
+    }
+  })
+
+  test('records source routes and dispatches reconciliation once', async () => {
+    const database = TestApp.databaseFactory()
+    const setup = database()
+    await TestRoutes.publish(setup)
+    const firstVerified = Promise.withResolvers<void>()
+    const intervals: RoutesObservability.LifecycleInterval[] = []
+    const messages: RoutesTransferReconciliation.Message[] = []
+    const releaseFirst = Promise.withResolvers<void>()
+    const secondVerified = Promise.withResolvers<void>()
+    let verifications = 0
+    const provider = RoutesProvider.from({
+      ...Stargate.stargate(),
+      async verifySourceTransaction({ transactionHash }) {
+        verifications++
+        if (verifications === 1) {
+          firstVerified.resolve()
+          await releaseFirst.promise
+        } else secondVerified.resolve()
+        return {
+          destinationAmount: '980000',
+          providerState: {},
+          transactionHash,
+          type: 'verified',
+        }
+      },
+    })
+    const app = transfersApp({
+      db: database,
+      routes: {
+        async dispatchTransferReconciliation(message) {
+          messages.push(message)
+        },
+        async recordLifecycleInterval(interval) {
+          intervals.push(interval)
+        },
+      },
+      providers: [provider],
+    })
+    const transfer = await RoutesTransfer.create(setup, {
+      apiKeyId: routesReader.id,
+      environment: 'production',
+      id: RoutesTransfer.generateId(new Date(Date.UTC(2026, 0, 2, 0, 0, seedSecond++))),
+      orgId: routesReader.orgId,
+      snapshot: TestRoutes.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+    })
+    const request = {
+      body: JSON.stringify({ transactionHashes: [`0x${'aa'.repeat(32)}`] }),
+      headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+      method: 'POST',
+    } as const
+    const path = `/v1/routes/transfers/${transfer.id}/source-transactions`
+
+    const first = app.request(path, request)
+    await firstVerified.promise
+    const second = app.request(path, request)
+    await secondVerified.promise
+    releaseFirst.resolve()
+    const [response, replay] = await Promise.all([first, second])
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchObject({ destinationAmount: { baseUnits: '980000' } })
+    expect(replay.status).toBe(200)
+    expect(intervals).toEqual([
+      expect.objectContaining({
+        routesEnvironment: 'production',
+        method: 'transaction',
+        provider: 'stargate',
+        resourceId: transfer.id,
+        stage: 'source_routes',
+      }),
+    ])
+    expect(messages).toEqual([{ transferId: transfer.id, type: 'routes:transfer:reconcile' }])
+  })
+
+  test('does not expose a transfer owned by another organization', async () => {
+    const tracker = RoutesTransferReconciliation.createTracker({
+      db,
+      providers: [Stargate.stargate()],
+    })
+    const app = transfersApp({
+      routes: {
+        async dispatchTransferReconciliation(message) {
+          await tracker.reconcile(message)
+        },
+      },
+    })
+    const transfer = await seedTransfer()
+    const response = await app.request(`/v1/routes/transfers/${transfer.id}/source-transactions`, {
+      body: JSON.stringify({ transactionHashes: [`0x${'aa'.repeat(32)}`] }),
+      headers: { ...as(routesForeign).headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+    expect(response.status).toBe(404)
+  })
+
+  test('waits for every source verification before reporting provider attempts', async () => {
+    const entries: Log.Entry[] = []
+    const transactionHashes = [`0x${'aa'.repeat(32)}`, `0x${'bb'.repeat(32)}`]
+    const provider = RoutesProvider.from({
+      ...Stargate.stargate(),
+      async verifySourceTransaction({ transactionHash }) {
+        if (transactionHash === transactionHashes[0]) throw new Error('upstream unavailable')
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        return { type: 'pending' }
+      },
+    })
+    const app = transfersApp({
+      routes: { async dispatchTransferReconciliation() {} },
+      logger: (entry) => void entries.push(entry),
+      providers: [provider],
+    })
+    const transfer = await seedTransfer({
+      snapshot: TestRoutes.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+    })
+
+    const response = await app.request(`/v1/routes/transfers/${transfer.id}/source-transactions`, {
+      body: JSON.stringify({ transactionHashes }),
+      headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(502)
+    expect(
+      entries[0]?.routesProviderAttempts?.map(({ operation, outcome }) => ({
+        operation,
+        outcome,
+      })),
+    ).toEqual([
+      { operation: 'verifySourceTransaction', outcome: 'failed' },
+      { operation: 'verifySourceTransaction', outcome: 'success' },
+    ])
+  })
+})
+
+const createBody = {
+  amount: '1000000',
+  destinationToken: '0x20c0000000000000000000000000000000000000',
+  mode: 'exactSource',
+  recipient: `0x${'11'.repeat(20)}`,
+  sender: `0x${'22'.repeat(20)}`,
+  slippageBps: 300,
+  sourceChain: 'base',
+  sourceToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+}
+
+const vaultTransferBody = {
+  amount: createBody.amount,
+  mode: createBody.mode,
+  recipient: createBody.recipient,
+  sender: createBody.sender,
+  slippageBps: createBody.slippageBps,
+  sourceChain: createBody.sourceChain,
+  sourceToken: createBody.sourceToken,
+  vaultAddress: `0x${'f4'.repeat(20)}`,
+}
+
+const zoneTransferBody = {
+  amount: createBody.amount,
+  destinationChain: 'eip155:421700001',
+  destinationToken: createBody.destinationToken,
+  mode: createBody.mode,
+  recipient: createBody.recipient,
+  recipientFallback: `0x${'33'.repeat(20)}`,
+  sender: createBody.sender,
+  slippageBps: createBody.slippageBps,
+  sourceChain: createBody.sourceChain,
+  sourceToken: createBody.sourceToken,
+}
+
+function postTransfer(
+  app: ReturnType<typeof create>,
+  options: { body?: unknown; idempotencyKey?: string | undefined; key?: { token: string } } = {},
+) {
+  return app.request('/v1/routes/transfers', {
+    body: JSON.stringify(options.body ?? createBody),
+    headers: {
+      authorization: `Bearer ${(options.key ?? routesWriter).token}`,
+      'content-type': 'application/json',
+      ...(options.idempotencyKey === undefined
+        ? {}
+        : { 'idempotency-key': options.idempotencyKey }),
+    },
+    method: 'POST',
+  })
+}
+
+describe('POST /routes/transfers', () => {
+  function providerResponse(
+    options: { sourceToken?: string | undefined } = {},
+  ): RoutesProvider.prepareTransfer.ReturnType {
+    const spender = `0x${'44'.repeat(20)}`
+    return {
+      action: {
+        calls: [
+          {
+            data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${(1_000_000).toString(16).padStart(64, '0')}`,
+            to: options.sourceToken ?? createBody.sourceToken,
+            value: '0x0',
+          },
+          { data: '0xe8017952', to: spender, value: '0x0' },
+        ],
+        type: 'evm:calls',
+      },
+      correlation: { requestId: `0x${'ab'.repeat(32)}` },
+      fees: [{ amount: '21050', side: 'source' }],
+      destinationAmountMin: '980000',
+      destinationAmount: '990000',
+      quality: {
+        estimatedSeconds: 4,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'relay:quote-v2',
+        tier: 'liquid',
+      },
+      sampledAt: '2099-01-01T00:00:00.000Z',
+    }
+  }
+
+  function provider(
+    prepareTransfer: NonNullable<RoutesProvider.Provider['prepareTransfer']> = async () =>
+      providerResponse(),
+  ) {
+    return RoutesProvider.from({
+      ...Relay.relay(),
+      prepareTransfer,
+    })
+  }
+
+  let idempotencySequence = 0
+  function nextIdempotencyKey() {
+    return `routes_test_${idempotencySequence++}`
+  }
+
+  test('requires routes:write and an Idempotency-Key', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const forbidden = await postTransfer(app, {
+      idempotencyKey: nextIdempotencyKey(),
+      key: routesReader,
+    })
+    expect(forbidden.status).toBe(403)
+
+    const missing = await postTransfer(app)
+    expect(missing.status).toBe(400)
+    expect(((await missing.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_key_required',
+    )
+  })
+
+  test('creates a transfer with the selected executable quote', async () => {
+    const inputs: RoutesProvider.prepareTransfer.Parameters[] = []
+    const app = transfersApp({
+      providers: [
+        provider(async (input) => {
+          inputs.push(input)
+          return providerResponse()
+        }),
+      ],
+    })
+    const response = await postTransfer(app, {
+      body: { ...createBody, destinationToken: 'pathusd', sourceToken: 'usdc' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    const body = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+
+    expect(inputs[0]).toMatchObject({
+      method: 'transaction',
+      mode: 'exactSource',
+      recipient: createBody.recipient,
+      sender: createBody.sender,
+      slippageBps: 300,
+    })
+    expect(body).toMatchObject({
+      action: { type: 'evm:calls' },
+      destinationAmountMin: { baseUnits: '980000' },
+      method: 'transaction',
+      mode: 'exactSource',
+      provider: { id: 'relay' },
+      // The provider returned no expiry, so the default validity window applies.
+      quote: { expiresAt: '2099-01-01T00:01:00.000Z', sampledAt: '2099-01-01T00:00:00.000Z' },
+      sourceAmount: { baseUnits: '1000000' },
+      status: 'awaiting-source',
+      version: 1,
+    })
+    expect(body.fees[0]).toMatchObject({ side: 'source', token: { symbol: 'USDC' } })
+
+    // Reads return the same transfer without the action; the private
+    // correlation never leaves the row.
+    const read = await app.request(`/v1/routes/transfers/${body.id}`, as(routesWriter))
+    const readBody = await TestApp.json(read, Routes.schema.getRoutesTransfer.Response)
+    expect('action' in readBody).toBe(false)
+    expect(JSON.stringify(readBody)).not.toContain('ab'.repeat(32))
+    const row = await db.kysely
+      .selectFrom('routes_transfers')
+      .select(['providerState'])
+      .where('id', '=', body.id)
+      .executeTakeFirstOrThrow()
+    expect(row.providerState).toEqual({ requestId: `0x${'ab'.repeat(32)}` })
+  })
+
+  test('rejects completion when the owner is deleted after the initial claim', async () => {
+    const suffix = nextIdempotencyKey()
+    const key = {
+      id: `key_${suffix}`,
+      orgId: `org_${suffix}`,
+      scopes: ['routes:write'],
+      token: `secret_${suffix}`,
+    } satisfies TestApp.kvStore.Key
+    await Organizations.create(db, { id: key.orgId, name: 'Transfer deletion race' })
+    const entered = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const app = create({
+      auth: { keys: [key] },
+      defaultChainId: tempoMainnet.id,
+      providers: [
+        provider(async () => {
+          entered.resolve()
+          await release.promise
+          return providerResponse()
+        }),
+      ],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const creation = postTransfer(app, { idempotencyKey, key })
+    await entered.promise
+
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select('status')
+        .where('apiKeyId', '=', key.id)
+        .where('keyHash', '=', Idempotency.inputHash(idempotencyKey))
+        .executeTakeFirstOrThrow(),
+    ).resolves.toEqual({ status: 'pending' })
+    expect(await Organizations.deleteOrganization(db, key.orgId)).toBe(true)
+    release.resolve()
+    const response = await creation
+
+    expect(response.status).toBe(403)
+    await expect(response.json()).resolves.toMatchObject({
+      error: {
+        code: 'api_key_forbidden',
+        message: 'API key organization no longer exists.',
+      },
+    })
+    await expect(
+      db.kysely
+        .selectFrom('routes_transfers')
+        .select('id')
+        .where('orgId', '=', key.orgId)
+        .execute(),
+    ).resolves.toEqual([])
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['response', 'status', 'transferId'])
+        .where('apiKeyId', '=', key.id)
+        .where('keyHash', '=', Idempotency.inputHash(idempotencyKey))
+        .execute(),
+    ).resolves.toEqual([])
+  })
+
+  test('requires configuration and records normalized subsidy terms', async () => {
+    const request = {
+      ...createBody,
+      destinationChain: 'base',
+      destinationToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+      sourceChain: 'tempo',
+      sourceToken: '0x20c000000000000000000000b9537d11c60e8b50',
+      subsidize: true,
+    }
+    const outbound = RoutesProvider.from({
+      ...Relay.relay(),
+      id: 'stargate',
+      name: 'Stargate',
+      async prepareTransfer() {
+        return providerResponse({ sourceToken: request.sourceToken })
+      },
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const unavailable = await postTransfer(transfersApp({ providers: [outbound] }), {
+      body: request,
+      idempotencyKey,
+    })
+    expect(unavailable.status).toBe(501)
+
+    await Organizations.create(db, { id: routesWriter.orgId, name: routesWriter.orgId })
+    await RoutesSubsidies.upsertOrganization(db, {
+      frequency: 'tx',
+      maxAmount: '5',
+      orgId: routesWriter.orgId,
+    })
+    await StripeCustomers.create(db, {
+      orgId: routesWriter.orgId,
+      stripeCustomerId: 'cus_routes_transfer_subsidy',
+    })
+    await StripeCustomers.setStatus(db, routesWriter.orgId, 'active')
+    const upstream = await postTransfer(
+      transfersApp({
+        providers: [outbound],
+        routes: {
+          transferSubsidy: {
+            account: `0x${'77'.repeat(20)}`,
+            async check() {
+              throw new RoutesTransferSubsidy.InventoryUpstreamError(
+                new Error('Destination RPC unavailable.'),
+              )
+            },
+            policy: { maxAmount: '5' },
+          },
+        },
+      }),
+      { body: request, idempotencyKey: nextIdempotencyKey() },
+    )
+    expect(upstream.status).toBe(502)
+    await expect(upstream.json()).resolves.toMatchObject({ error: { code: 'upstream_error' } })
+    const limited = await postTransfer(
+      transfersApp({
+        providers: [outbound],
+        routes: { transferSubsidy: transferSubsidy('0.015') },
+      }),
+      { body: request, idempotencyKey: nextIdempotencyKey() },
+    )
+    expect(limited.status).toBe(403)
+    await expect(limited.json()).resolves.toMatchObject({
+      error: { code: 'routes_subsidy_limit_exceeded' },
+    })
+    const response = await postTransfer(
+      transfersApp({
+        providers: [outbound],
+        routes: { transferSubsidy: transferSubsidy('5') },
+      }),
+      {
+        body: request,
+        idempotencyKey,
+      },
+    )
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+    expect(body).toMatchObject({
+      destinationAmount: { baseUnits: '990000' },
+      destinationAmountRequired: { baseUnits: '1000000' },
+      subsidize: true,
+    })
+    const row = await db.kysely
+      .selectFrom('routes_transfers')
+      .select([
+        'providerState',
+        'subsidyAccount',
+        'subsidyChainId',
+        'subsidyCommitmentAmount',
+        'subsidyNativeAmount',
+        'subsidyTokenAddress',
+      ])
+      .where('id', '=', body.id)
+      .executeTakeFirstOrThrow()
+    expect(row.providerState).not.toHaveProperty('transferSubsidyPolicy')
+    expect(row).toMatchObject({
+      subsidyAccount: `0x${'77'.repeat(20)}`,
+      subsidyChainId: 'eip155:8453',
+      subsidyCommitmentAmount: { baseUnits: '20000' },
+      subsidyNativeAmount: '100',
+      subsidyTokenAddress: request.destinationToken,
+    })
+    const replay = await postTransfer(transfersApp({ providers: [outbound] }), {
+      body: request,
+      idempotencyKey,
+    })
+    expect(replay.status).toBe(200)
+    await expect(replay.json()).resolves.toMatchObject({ id: body.id })
+    const mismatch = await postTransfer(transfersApp({ providers: [outbound] }), {
+      body: { ...request, amount: '2000000' },
+      idempotencyKey,
+    })
+    expect(mismatch.status).toBe(409)
+    await expect(mismatch.json()).resolves.toMatchObject({
+      error: { code: 'idempotency_conflict' },
+    })
+
+    await RoutesCatalog.publish(db, {
+      ...TestRoutes.data,
+      tokens: TestRoutes.data.tokens.map((token) =>
+        token.id === 'usdce' ? { ...token, currency: 'EUR' } : token,
+      ),
+    })
+    try {
+      const incompatible = await postTransfer(
+        transfersApp({
+          providers: [outbound],
+          routes: { transferSubsidy: transferSubsidy('5') },
+        }),
+        { body: request, idempotencyKey: nextIdempotencyKey() },
+      )
+      expect(incompatible.status).toBe(400)
+      await expect(incompatible.json()).resolves.toMatchObject({
+        error: { code: 'body_invalid' },
+      })
+    } finally {
+      await TestRoutes.publish(db)
+    }
+  })
+
+  test('dispatches staged webhook updates after creation commits', async () => {
+    const subscription = await Webhooks.createSubscription(db, {
+      chainId: tempoMainnet.id,
+      destination: { type: 'url', url: 'https://example.com/webhooks/routes-transfers' },
+      environment: 'production',
+      eventType: 'routes:transfer.updated',
+      filters: { status: 'awaiting-source' },
+      owner: { orgId: routesWriter.orgId, type: 'api_key' },
+    })
+    const references: Webhooks.QueueReference[] = []
+    const app = transfersApp({
+      routes: {
+        async dispatchTransferUpdates(staged) {
+          const reference = staged[0]!
+          const queued = await db.kysely
+            .selectFrom('webhook_queue_events')
+            .select('eventId')
+            .where('eventId', '=', reference.eventId)
+            .where('subscriptionId', '=', reference.subscriptionId)
+            .executeTakeFirst()
+          expect(queued).toBeDefined()
+          references.push(...staged)
+          return staged.length
+        },
+      },
+      providers: [provider()],
+    })
+
+    const response = await postTransfer(app, { idempotencyKey: nextIdempotencyKey() })
+
+    expect(response.status).toBe(200)
+    expect(references).toEqual([{ eventId: expect.any(String), subscriptionId: subscription.id }])
+  })
+
+  test('creates a transfer with the requested provider', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const response = await postTransfer(app, {
+      body: { ...createBody, provider: 'relay' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+    expect(body.provider.id).toBe('relay')
+  })
+
+  test('rejects an unsupported provider', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const response = await postTransfer(app, {
+      body: { ...createBody, provider: 'bridge' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+
+    expect(response.status).toBe(400)
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('body_invalid')
+  })
+
+  test('preserves a provider-specified native fee token', async () => {
+    const app = transfersApp({
+      providers: [
+        provider(async () => ({
+          ...providerResponse(),
+          fees: [
+            {
+              amount: '1000000000000000',
+              side: 'source',
+              token: {
+                address: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+                currency: 'ETH',
+                decimals: 18,
+                name: 'Ether',
+                standard: 'native',
+                symbol: 'ETH',
+                tokenKey: 'eip155:8453/slip44:60',
+                verified: true,
+              },
+            },
+          ],
+        })),
+      ],
+    })
+    const response = await postTransfer(app, {
+      body: { ...createBody, destinationToken: 'pathusd', sourceToken: 'usdc' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+
+    expect(body.fees).toMatchObject([
+      {
+        amount: { baseUnits: '1000000000000000', formatted: '0.001' },
+        side: 'source',
+        token: { standard: 'native', symbol: 'ETH' },
+      },
+    ])
+  })
+
+  test('resolves token identifiers through the composed route', async () => {
+    const app = transfersApp({ providers: [provider()] })
+    const identifiers = [
+      { destinationToken: 'pathusd', name: 'alias', sourceToken: 'usdc' },
+      {
+        destinationToken: createBody.destinationToken,
+        name: 'address',
+        sourceToken: createBody.sourceToken,
+      },
+      {
+        destinationToken: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+        name: 'token key',
+        sourceToken: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+      },
+    ] as const
+    const results = []
+    for (const identifier of identifiers) {
+      const response = await postTransfer(app, {
+        body: {
+          ...createBody,
+          destinationToken: identifier.destinationToken,
+          sourceToken: identifier.sourceToken,
+        },
+        idempotencyKey: nextIdempotencyKey(),
+      })
+      const body = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+      results.push({
+        destinationToken: body.destinationToken.symbol,
+        name: identifier.name,
+        sourceToken: body.sourceToken.symbol,
+        status: response.status,
+      })
+    }
+
+    expect(results).toMatchInlineSnapshot(`
+      [
+        {
+          "destinationToken": "pathUSD",
+          "name": "alias",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+        {
+          "destinationToken": "pathUSD",
+          "name": "address",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+        {
+          "destinationToken": "pathUSD",
+          "name": "token key",
+          "sourceToken": "USDC",
+          "status": 200,
+        },
+      ]
+    `)
+  })
+
+  test('replays the exact response for the same key and body', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const first = await postTransfer(app, { idempotencyKey })
+    const second = await postTransfer(app, { idempotencyKey })
+    expect(second.status).toBe(200)
+    expect(await second.json()).toEqual(await first.json())
+  })
+
+  test('rejects a reused key with different input', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    await postTransfer(app, { idempotencyKey })
+    const conflict = await postTransfer(app, {
+      body: { ...createBody, amount: '2000000' },
+      idempotencyKey,
+    })
+    expect(conflict.status).toBe(409)
+    expect(((await conflict.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_conflict',
+    )
+  })
+
+  test('rejects an equivalent request while the first is running', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    await RoutesIdempotencyTable.claim(db, {
+      apiKeyId: routesWriter.id,
+      irrevocable: false,
+      keyHash: Idempotency.inputHash(idempotencyKey),
+      operation: RoutesIdempotencyTable.operations.transfer,
+      orgId: routesWriter.orgId,
+      requestHash: Idempotency.inputHash(createBody),
+      ttlMs: 60_000,
+    })
+    const pending = await postTransfer(app, { idempotencyKey })
+    expect(pending.status).toBe(409)
+    expect(((await pending.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_in_progress',
+    )
+  })
+
+  test('rolls back creation after losing the idempotency lease', async () => {
+    const idempotencyKey = nextIdempotencyKey()
+    const keyHash = Idempotency.inputHash(idempotencyKey)
+    const before = await db.kysely
+      .selectFrom('routes_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    const app = transfersApp({
+      providers: [
+        provider(async () => {
+          await db.kysely
+            .updateTable('routes_idempotency_requests')
+            .set({ expiresAt: new Date(0).toISOString() })
+            .where('apiKeyId', '=', routesWriter.id)
+            .where('keyHash', '=', keyHash)
+            .execute()
+          await RoutesIdempotencyTable.claim(db, {
+            apiKeyId: routesWriter.id,
+            irrevocable: false,
+            keyHash,
+            operation: RoutesIdempotencyTable.operations.transfer,
+            orgId: routesWriter.orgId,
+            requestHash: Idempotency.inputHash(createBody),
+            ttlMs: 60_000,
+          })
+          return providerResponse()
+        }),
+      ],
+    })
+
+    const response = await postTransfer(app, { idempotencyKey })
+    expect(response.status).toBe(500)
+    const after = await db.kysely
+      .selectFrom('routes_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    expect(after.count).toBe(before.count)
+  })
+
+  test('rejects non-account fields and gates disabled corridors and methods', async () => {
+    const app = transfersApp({
+      providers: [provider()],
+    })
+
+    const ignoredRefund = await postTransfer(app, {
+      body: { ...createBody, refundAddress: createBody.sender },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(ignoredRefund.status).toBe(400)
+    expect(((await ignoredRefund.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+
+    const unsupportedDestination = await postTransfer(app, {
+      body: { ...createBody, destinationVault: `0x${'f4'.repeat(20)}`, type: 'vault' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(unsupportedDestination.status).toBe(400)
+    expect(((await unsupportedDestination.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+
+    const unknownToken = await postTransfer(app, {
+      body: { ...createBody, destinationToken: `0x${'99'.repeat(20)}` },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(unknownToken.status).toBe(404)
+
+    const unknownChain = await postTransfer(app, {
+      body: { ...createBody, destinationChain: 'bitcoin' },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+    expect(unknownChain.status).toBe(404)
+  })
+
+  test.each([
+    ['recipient', { recipient: 'invalid' }],
+    ['sender', { sender: 'invalid' }],
+  ] as const)('rejects a route-invalid %s before calling the provider', async (_field, body) => {
+    let calls = 0
+    const app = transfersApp({
+      providers: [
+        provider(async () => {
+          calls++
+          return providerResponse()
+        }),
+      ],
+    })
+    const response = await postTransfer(app, {
+      body: { ...createBody, ...body },
+      idempotencyKey: nextIdempotencyKey(),
+    })
+
+    expect(response.status).toBe(400)
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('body_invalid')
+    expect(calls).toBe(0)
+  })
+
+  test('releases the claim after a provider failure', async () => {
+    const failing = transfersApp({
+      providers: [
+        provider(async () => {
+          throw new Error('upstream unavailable')
+        }),
+      ],
+    })
+    const idempotencyKey = nextIdempotencyKey()
+    const failed = await postTransfer(failing, { idempotencyKey })
+    expect(failed.status).toBe(502)
+    expect(((await failed.json()) as { error: { code: string } }).error.code).toBe('upstream_error')
+
+    // The key was released, so the same request retries successfully.
+    const working = transfersApp({
+      providers: [provider()],
+    })
+    expect((await postTransfer(working, { idempotencyKey })).status).toBe(200)
+  })
+
+  test('rejects preparations with unbounded approvals', async () => {
+    const app = transfersApp({
+      providers: [
+        provider(async () => {
+          const result = providerResponse()
+          const spender = `0x${'44'.repeat(20)}`
+          return {
+            ...result,
+            action: {
+              calls: [
+                {
+                  data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${'f'.repeat(64)}`,
+                  to: createBody.sourceToken,
+                  value: '0x0',
+                },
+              ],
+              type: 'evm:calls',
+            },
+          }
+        }),
+      ],
+    })
+    const response = await postTransfer(app, { idempotencyKey: nextIdempotencyKey() })
+    expect(response.status).toBe(502)
+  })
+})
+
+describe.skipIf(!Anvil.available)('POST /routes/transfers (forked localnet)', () => {
+  /**
+   * Storage slot of Circle FiatToken's `balanceAndBlacklistStates` mapping.
+   * `anvil_dealERC20` cannot probe it because balances pack a blacklist bit,
+   * so the fork suite writes the slot directly. Every curated USDC is a
+   * FiatToken.
+   */
+  const fiatTokenBalanceSlot = 9n
+
+  for (const executable of executableProviders) {
+    describe(executable.id, () => {
+      const route = TestRoutes.snapshot.routes.find(
+        (entry) =>
+          entry.route.source.chain.id === `eip155:${base.id}` &&
+          entry.route.source.symbol === 'USDC' &&
+          entry.route.destination.slug === executable.destinationToken,
+      )!
+      const usdc = route.route.source
+      const amount = Value.from('10', usdc.decimals)
+      const sender = Anvil.getAccount(0)
+
+      let anvil: Anvil.start.ReturnType
+
+      beforeAll(async () => {
+        anvil = await Anvil.start({ chain: base, forkUrl: base.rpcUrls.default.http[0]! })
+      })
+
+      afterAll(async () => {
+        await anvil?.stop()
+      })
+
+      function createTransfer(idempotencyKey: string) {
+        const app = transfersApp({ providers: [executable.create(sender.address)] })
+        return postTransfer(app, {
+          body: {
+            ...createBody,
+            amount: amount.toString(),
+            destinationToken: executable.destinationToken,
+            sender: sender.address,
+          },
+          idempotencyKey,
+        })
+      }
+
+      test('executes the prepared calls and returns successful receipts', async () => {
+        const { client } = anvil
+        await Anvil.setErc20Balance(client, {
+          address: sender.address,
+          amount,
+          slot: fiatTokenBalanceSlot,
+          token: usdc.address as `0x${string}`,
+        })
+
+        const response = await createTransfer(`bridge_${executable.id}_${sender.address}`)
+        expect(response.status).toBe(200)
+        const transfer = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+        expect(transfer.action.type).toBe('evm:calls')
+        if (transfer.action.type !== 'evm:calls') return
+        expect(transfer.action.calls.length).toBeGreaterThan(0)
+        if (executable.id === 'stargate') {
+          expect(transfer.fees).toMatchObject([
+            {
+              amount: { baseUnits: BigInt(transfer.action.calls.at(-1)!.value).toString() },
+              side: 'source',
+              token: { standard: 'native', symbol: 'ETH' },
+            },
+          ])
+          const row = await db.kysely
+            .selectFrom('routes_transfers')
+            .select('providerState')
+            .where('id', '=', transfer.id)
+            .executeTakeFirstOrThrow()
+          expect(row.providerState).toEqual({
+            destinationBlockNumber: expect.stringMatching(/^\d+$/),
+            routeConfiguration: stargateConfiguration,
+          })
+        }
+
+        const receipts = []
+        for (const call of transfer.action.calls) {
+          receipts.push(
+            await client.sendTransactionSync({
+              account: sender,
+              data: call.data as `0x${string}`,
+              to: call.to as `0x${string}`,
+              value: BigInt(call.value),
+            }),
+          )
+        }
+
+        expect(receipts.map((receipt) => receipt.status)).toEqual(
+          transfer.action.calls.map(() => 'success'),
+        )
+        // The deposit is the last call and must emit; an approval alone proves nothing.
+        expect(receipts.at(-1)!.logs.length).toBeGreaterThan(0)
+        if (executable.id === 'stargate') {
+          const receipt = receipts.at(-1)!
+          const finalized = await client.getBlock({ blockTag: 'finalized' })
+          expect(receipt.blockNumber).toBeGreaterThan(finalized.number)
+          await expect(
+            Stargate.verifySourceTransaction({
+              configuration: stargateConfiguration,
+              destinationAmountMin: transfer.destinationAmountMin!.baseUnits,
+              destinationChain: RoutesChain.from({
+                id: 'eip155:4217',
+                name: 'Tempo',
+                rpcUrls: [tempoMainnet.rpcUrls.default.http[0]!],
+                slug: 'tempo',
+              }),
+              destinationTokenAddress: transfer.destinationToken.address,
+              recipient: transfer.recipient,
+              sender: sender.address,
+              sourceAmount: transfer.sourceAmount.baseUnits,
+              sourceChain: RoutesChain.from({
+                id: 'eip155:8453',
+                name: 'Base',
+                rpcUrls: [anvil.rpcUrl],
+                slug: 'base',
+              }),
+              sourceTokenAddress: transfer.sourceToken.address,
+              transactionHash: receipt.transactionHash,
+              validAfter: transfer.quote.sampledAt,
+            }),
+          ).resolves.toMatchObject({ type: 'verified' })
+        }
+      })
+
+      if (executable.id === 'stargate')
+        test('registers non-atomic calls and reopens them after an execution reorg', async () => {
+          await Anvil.setErc20Balance(anvil.client, {
+            address: sender.address,
+            amount,
+            slot: fiatTokenBalanceSlot,
+            token: usdc.address as `0x${string}`,
+          })
+          const response = await createTransfer(`bridge_reorg_${sender.address}`)
+          expect(response.status).toBe(200)
+          const transfer = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+          expect(transfer.action.type).toBe('evm:calls')
+          if (transfer.action.type !== 'evm:calls') return
+
+          const checkpoint = await anvil.client.snapshot()
+          // Anvil increments fork timestamps instead of following wall time between tests.
+          const block = await anvil.client.getBlock()
+          const sampledAt = BigInt(Math.floor(Date.parse(transfer.quote.sampledAt) / 1_000))
+          if (block.timestamp < sampledAt)
+            await anvil.client.setNextBlockTimestamp({ timestamp: sampledAt })
+          let reverted = false
+          try {
+            const receipts = []
+            for (const call of transfer.action.calls)
+              receipts.push(
+                await anvil.client.sendTransactionSync({
+                  account: sender,
+                  data: call.data as `0x${string}`,
+                  to: call.to as `0x${string}`,
+                  value: BigInt(call.value),
+                }),
+              )
+            const sourceReceipt = receipts.at(-1)!
+            const transactionHash = sourceReceipt.transactionHash
+            await RoutesCatalog.publish(db, {
+              ...TestRoutes.data,
+              chains: TestRoutes.data.chains.map((chain) =>
+                chain.id === 'eip155:8453' ? { ...chain, rpcUrls: [anvil.rpcUrl] } : chain,
+              ),
+            })
+            const messages: RoutesTransferReconciliation.Message[] = []
+            const app = transfersApp({
+              routes: {
+                async dispatchTransferReconciliation(message) {
+                  messages.push(message)
+                },
+              },
+              providers: [Stargate.stargate()],
+            })
+            const registered = await app.request(
+              `/v1/routes/transfers/${transfer.id}/source-transactions`,
+              {
+                body: JSON.stringify({
+                  transactionHashes: receipts.map((receipt) => receipt.transactionHash),
+                }),
+                headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+                method: 'POST',
+              },
+            )
+            expect(registered.status).toBe(200)
+            expect(messages).toEqual([
+              { transferId: transfer.id, type: 'routes:transfer:reconcile' },
+            ])
+
+            await anvil.client.revert({ id: checkpoint })
+            reverted = true
+            const tracker = RoutesTransferReconciliation.createTracker({
+              db,
+              async dispatch(message) {
+                messages.push(message)
+              },
+              providers: [Stargate.stargate()],
+            })
+            await expect(tracker.reconcile(messages[0]!)).resolves.toEqual({ type: 'pending' })
+            expect(messages[1]).toEqual({
+              attempt: 1,
+              transferId: transfer.id,
+              type: 'routes:transfer:reconcile',
+            })
+
+            const pending = await db.kysely
+              .selectFrom('routes_transfers')
+              .select(['snapshot', 'status', 'version'])
+              .where('id', '=', transfer.id)
+              .executeTakeFirstOrThrow()
+            expect({
+              sourceTransactionHashes: pending.snapshot.sourceTransactionHashes,
+              status: pending.status,
+              version: pending.version,
+            }).toEqual({
+              sourceTransactionHashes: [transactionHash, receipts[0]!.transactionHash],
+              status: 'processing',
+              version: 2,
+            })
+
+            await anvil.client.mine({ blocks: 128 })
+            const finalized = await anvil.client.getBlock({ blockTag: 'finalized' })
+            expect(finalized.number).toBeGreaterThanOrEqual(sourceReceipt.blockNumber)
+            await expect(tracker.reconcile(messages[1]!)).resolves.toEqual({ type: 'reopened' })
+
+            const record = await db.kysely
+              .selectFrom('routes_transfers')
+              .select(['snapshot', 'status', 'version'])
+              .where('id', '=', transfer.id)
+              .executeTakeFirstOrThrow()
+            expect({
+              sourceTransactionHashes: record.snapshot.sourceTransactionHashes,
+              status: record.status,
+              version: record.version,
+            }).toEqual({
+              sourceTransactionHashes: undefined,
+              status: 'awaiting-source',
+              version: 3,
+            })
+            expect(
+              await db.kysely
+                .selectFrom('routes_transfer_transactions')
+                .selectAll()
+                .where('transferId', '=', transfer.id)
+                .execute(),
+            ).toEqual([])
+          } finally {
+            if (!reverted) await anvil.client.revert({ id: checkpoint })
+            await TestRoutes.publish(db)
+          }
+        })
+
+      test('bounds the approval to the quoted source spend', async () => {
+        const response = await createTransfer(`bridge_bounds_${executable.id}_${sender.address}`)
+        expect(response.status).toBe(200)
+        const transfer = await TestApp.json(response, Routes.schema.createRoutesTransfer.Response)
+        if (transfer.action.type !== 'evm:calls') return
+
+        const approval = transfer.action.calls.find((call) =>
+          call.data.toLowerCase().startsWith('0x095ea7b3'),
+        )
+        expect(approval).toBeDefined()
+        if (!approval) return
+
+        // Decoded from the live action, so a provider that starts returning
+        // an unlimited allowance fails here.
+        const decoded = decodeFunctionData({ abi: erc20Abi, data: approval.data as `0x${string}` })
+        expect(decoded.functionName).toBe('approve')
+        if (decoded.functionName !== 'approve') return
+        const [, approved] = decoded.args
+        expect(approved).toBeLessThanOrEqual(BigInt(transfer.sourceAmount.baseUnits))
+        expect(approved).toBeLessThan(maxUint256)
+      })
+    })
+  }
+})
+
+describe.skipIf(!Anvil.available)(
+  'POST /routes/transfers/:id/source-transactions (forked localnet)',
+  () => {
+    const trackingDb = TestApp.database()
+    let destination: Anvil.start.ReturnType
+    let source: Anvil.start.ReturnType
+
+    beforeAll(async () => {
+      ;[destination, source] = await Promise.all([
+        Anvil.start({ chain: tempoMainnet, forkUrl: tempoMainnet.rpcUrls.default.http[0]! }),
+        Anvil.start({ chain: base, forkUrl: base.rpcUrls.default.http[0]! }),
+      ])
+      await RoutesCatalog.publish(trackingDb, {
+        ...TestRoutes.data,
+        chains: TestRoutes.data.chains.map((chain) => {
+          if (chain.id === 'eip155:4217') return { ...chain, rpcUrls: [destination.rpcUrl] }
+          if (chain.id === 'eip155:8453') return { ...chain, rpcUrls: [source.rpcUrl] }
+          return chain
+        }),
+      })
+    })
+
+    afterAll(async () => {
+      await Promise.all([destination?.stop(), source?.stop()])
+    })
+
+    test('backfills legacy state and completes despite a foreign source claim', async () => {
+      const destinationReceipt = await destination.client.getTransactionReceipt({
+        hash: destinationTransactionHash,
+      })
+      const sourceTransactionHash =
+        '0xfd71359adf5095f2ab512a19e0a2df6c8cc0db14ac8a52286d61287daabdccd4'
+      const sourceReceipt = await source.client.getTransactionReceipt({
+        hash: sourceTransactionHash,
+      })
+      const sourceBlock = await source.client.getBlock({ blockNumber: sourceReceipt.blockNumber })
+      const sampledAt = new Date(Number(sourceBlock.timestamp - 1n) * 1_000).toISOString()
+      const amount = {
+        baseUnits: '200000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '0.2',
+      } as const
+      const snapshot = {
+        ...TestRoutes.transferSnapshot({
+          destinationAmount: amount,
+          destinationAmountMin: amount,
+          provider: { id: 'stargate', name: 'Stargate' },
+          recipient: '0x7212623e4cff9ad010d28aa065fad2bf58578783',
+          sender: '0x52b650a62e384f68880d0a1dc2b84dfed47d5660',
+          sourceAmount: amount,
+        }),
+        quote: {
+          expiresAt: new Date(Date.parse(sampledAt) + 60_000).toISOString(),
+          sampledAt,
+        },
+      }
+      const subscriptions = await Promise.all(
+        [routesForeign, routesWriter].map((key) =>
+          Webhooks.createSubscription(trackingDb, {
+            chainId: 4217,
+            destination: { type: 'url', url: 'https://example.com/routes' },
+            environment: 'production',
+            eventType: 'routes:transfer.updated',
+            owner: { orgId: key.orgId, type: 'api_key' },
+          }),
+        ),
+      )
+      const transfer = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesWriter.id,
+        environment: 'production',
+        orgId: routesWriter.orgId,
+        snapshot,
+      })
+      const foreign = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesForeign.id,
+        environment: 'production',
+        orgId: routesForeign.orgId,
+        snapshot,
+      })
+      const tracker = RoutesTransferReconciliation.createTracker({
+        db: trackingDb,
+        providers: [Stargate.stargate()],
+      })
+      const messages: RoutesTransferReconciliation.Message[] = []
+      let dispatchEnabled = true
+      const app = TestApp.create({
+        auth: { keys: [routesForeign, routesWriter] },
+        db: trackingDb,
+        defaultChainId: tempoMainnet.id,
+        routes: {
+          async dispatchTransferReconciliation(message) {
+            if (!dispatchEnabled) throw new Error('reconciliation unavailable')
+            messages.push(message)
+          },
+        },
+        providers: [Stargate.stargate()],
+      })
+      const path = `/v1/routes/transfers/${transfer.id}/source-transactions`
+      const registration = {
+        body: JSON.stringify({
+          transactionHashes: [sourceTransactionHash],
+        }),
+        headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+        method: 'POST',
+      }
+      const foreignResponse = await app.request(
+        `/v1/routes/transfers/${foreign.id}/source-transactions`,
+        {
+          ...registration,
+          headers: { ...as(routesForeign).headers, 'content-type': 'application/json' },
+        },
+      )
+      expect(foreignResponse.status).toBe(200)
+      expect(
+        (await app.request(`/v1/routes/transfers/${foreign.id}`, as(routesWriter))).status,
+      ).toBe(404)
+      expect(await tracker.reconcile(messages[0]!)).toEqual({ type: 'completed' })
+
+      const response = await app.request(path, registration)
+      expect(response.status).toBe(200)
+      const registered = await TestApp.json(
+        response,
+        Routes.schema.registerRoutesTransferSourceTransaction.Response,
+      )
+      expect({
+        sourceTransactionHashes: registered.sourceTransactionHashes,
+        status: registered.status,
+        version: registered.version,
+      }).toEqual({
+        sourceTransactionHashes: [
+          '0xfd71359adf5095f2ab512a19e0a2df6c8cc0db14ac8a52286d61287daabdccd4',
+        ],
+        status: 'processing',
+        version: 2,
+      })
+      const stored = await trackingDb.kysely
+        .selectFrom('routes_transfers')
+        .select('providerState')
+        .where('id', '=', transfer.id)
+        .executeTakeFirstOrThrow()
+      expect(stored).toEqual({
+        providerState: {
+          destinationBlockNumber: expect.stringMatching(/^\d+$/),
+          routeConfiguration: stargateConfiguration,
+          stargate: {
+            guid: '0x5549d117c8b23f0ecdf05c2604ed989cf0034f378707bd81319e93834f2f85f2',
+            sourceBlock: {
+              hash: sourceReceipt.blockHash,
+              number: sourceReceipt.blockNumber.toString(),
+            },
+            sourceEid: 30_184,
+          },
+        },
+      })
+      const destinationBlockNumber = stored.providerState?.['destinationBlockNumber']
+      if (typeof destinationBlockNumber !== 'string')
+        throw new Error('Expected a backfilled destination block number.')
+      expect(BigInt(destinationBlockNumber)).toBeLessThanOrEqual(destinationReceipt.blockNumber)
+      expect(messages).toEqual([
+        { transferId: foreign.id, type: 'routes:transfer:reconcile' },
+        { transferId: transfer.id, type: 'routes:transfer:reconcile' },
+      ])
+      await tracker.reconcile(messages[1]!)
+
+      const completed = await TestApp.json(
+        await app.request(`/v1/routes/transfers/${transfer.id}`, as(routesWriter)),
+        Routes.schema.getRoutesTransfer.Response,
+      )
+      expect({
+        destinationTransactionHashes: completed.destinationTransactionHashes,
+        status: completed.status,
+        version: completed.version,
+      }).toEqual({
+        destinationTransactionHashes: [destinationTransactionHash],
+        status: 'completed',
+        version: 3,
+      })
+
+      const events = await trackingDb.kysely
+        .selectFrom('webhook_queue_events')
+        .select(['envelope', 'subscriptionId'])
+        .where(
+          'subscriptionId',
+          'in',
+          subscriptions.map(({ id }) => id),
+        )
+        .execute()
+      for (const [index, record] of [foreign, transfer].entries()) {
+        const own = events.filter(
+          ({ subscriptionId }) => subscriptionId === subscriptions[index]!.id,
+        )
+        expect(own.map(({ envelope }) => envelope.data)).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({ id: record.id, status: 'awaiting-source', version: 1 }),
+            expect.objectContaining({ id: record.id, status: 'processing', version: 2 }),
+            expect.objectContaining({ id: record.id, status: 'completed', version: 3 }),
+          ]),
+        )
+        expect(own).toHaveLength(3)
+      }
+
+      dispatchEnabled = false
+      const replayed = await TestApp.json(
+        await app.request(path, registration),
+        Routes.schema.registerRoutesTransferSourceTransaction.Response,
+      )
+      expect({ status: replayed.status, version: replayed.version }).toEqual({
+        status: 'completed',
+        version: 3,
+      })
+
+      const other = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesWriter.id,
+        environment: 'production',
+        orgId: routesWriter.orgId,
+        snapshot,
+      })
+      const conflict = await app.request(
+        `/v1/routes/transfers/${other.id}/source-transactions`,
+        registration,
+      )
+      expect(conflict.status).toBe(409)
+      expect(((await conflict.json()) as { error: { code: string } }).error.code).toBe(
+        'source_transaction_conflict',
+      )
+
+      const pending = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesWriter.id,
+        environment: 'production',
+        orgId: routesWriter.orgId,
+        snapshot,
+      })
+      const pendingResponse = await app.request(
+        `/v1/routes/transfers/${pending.id}/source-transactions`,
+        {
+          ...registration,
+          body: JSON.stringify({ transactionHashes: [`0x${'99'.repeat(32)}`] }),
+        },
+      )
+      expect(pendingResponse.status).toBe(409)
+      expect(((await pendingResponse.json()) as { error: { code: string } }).error.code).toBe(
+        'source_transaction_pending',
+      )
+    })
+
+    test('registers all five Tempo Stargate calls and rejects mismatched fee terms', async () => {
+      const sourceTransactionHashes = [
+        '0xec00883936af1eb22402c471cf05827ac161d78e832ea771ff3b936d4e5d7517',
+        '0x55e22e5308d6261bb3ef04233cf29d85f342b5bf7ab2db0e34382be52a029b7e',
+        '0x75761272e9a8365636b0f4038f9908f18461d4f7083c6aa610831b81db681812',
+        '0xe840e103cfe4d62f9de0439f14f1010bae8f455585797577cb85fef3a77bc56b',
+        '0x56c9ad54ea6213b2091434efa82dcc072a800876c85c1a2068d1202af18e73b6',
+      ]
+      const routeConfiguration = {
+        destinationPoolAddress: '0x27a16dc786820B16E5c9028b75B99F6f604b5d26',
+        poolAddress: '0x8c76e2F6C5ceDA9AA7772e7efF30280226c44392',
+      }
+      const amount = {
+        baseUnits: '200000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '0.2',
+      } as const
+      const fee = {
+        amount: { baseUnits: '500000', currency: 'USD', decimals: 6, formatted: '0.5' },
+        side: 'source',
+        token: {
+          address: '0x20c0000000000000000000000000000000000000',
+          currency: 'USD',
+          decimals: 6,
+          name: 'pathUSD',
+          standard: 'TIP-20',
+          symbol: 'pathUSD',
+          tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+          verified: true,
+        },
+        type: 'provider',
+      } as const
+      const snapshot = TestRoutes.transferSnapshot({
+        destinationAmount: {
+          baseUnits: '199979',
+          currency: 'USD',
+          decimals: 6,
+          formatted: '0.199979',
+        },
+        destinationAmountMin: {
+          baseUnits: '199979',
+          currency: 'USD',
+          decimals: 6,
+          formatted: '0.199979',
+        },
+        destinationChain: {
+          addressFormat: 'hex',
+          id: 'eip155:8453',
+          kind: 'evm',
+          name: 'Base',
+        },
+        destinationToken: {
+          address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+          currency: 'USD',
+          decimals: 6,
+          name: 'USD Coin',
+          standard: 'ERC-20',
+          symbol: 'USDC',
+          tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+          verified: true,
+        },
+        fees: [fee],
+        provider: { id: 'stargate', name: 'Stargate' },
+        quote: {
+          expiresAt: '2026-09-03T16:04:31.000Z',
+          sampledAt: '2026-09-03T16:03:31.000Z',
+        },
+        recipient: '0xa8a89a017cd431c31af421f7d829e9418a5016ba',
+        sender: '0x3063088c6f4ac4dd3f96a411d5fb68173d113def',
+        sourceAmount: amount,
+        sourceChain: {
+          addressFormat: 'hex',
+          id: 'eip155:4217',
+          kind: 'evm',
+          name: 'Tempo',
+        },
+        sourceToken: {
+          address: '0x20c000000000000000000000b9537d11c60e8b50',
+          currency: 'USD',
+          decimals: 6,
+          name: 'Bridged USDC (Stargate)',
+          standard: 'TIP-20',
+          symbol: 'USDC.e',
+          tokenKey: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+          verified: true,
+        },
+      })
+      const app = TestApp.create({
+        auth: { keys: [routesWriter] },
+        db: trackingDb,
+        defaultChainId: tempoMainnet.id,
+        providers: [
+          Stargate.stargate({
+            fetch(input, init) {
+              // Anvil cannot decode Tempo type-0x76 receipts, so immutable source evidence is read from production.
+              return globalThis.fetch(
+                typeof input === 'string' && input.startsWith(destination.rpcUrl)
+                  ? tempoMainnet.rpcUrls.default.http[0]!
+                  : input,
+                init,
+              )
+            },
+          }),
+        ],
+        routes: { async dispatchTransferReconciliation() {} },
+      })
+      const transfer = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesWriter.id,
+        environment: 'production',
+        orgId: routesWriter.orgId,
+        providerState: { destinationBlockNumber: '0', routeConfiguration },
+        snapshot,
+      })
+      const response = await app.request(
+        `/v1/routes/transfers/${transfer.id}/source-transactions`,
+        {
+          body: JSON.stringify({ transactionHashes: sourceTransactionHashes }),
+          headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+          method: 'POST',
+        },
+      )
+      expect(response.status).toBe(200)
+      const registered = await TestApp.json(
+        response,
+        Routes.schema.registerRoutesTransferSourceTransaction.Response,
+      )
+      expect(registered.sourceTransactionHashes).toEqual([
+        sourceTransactionHashes[4],
+        ...sourceTransactionHashes.slice(0, 4),
+      ])
+
+      const malformed = await RoutesTransfer.create(trackingDb, {
+        apiKeyId: routesWriter.id,
+        environment: 'production',
+        orgId: routesWriter.orgId,
+        providerState: { destinationBlockNumber: '0', routeConfiguration },
+        snapshot: {
+          ...snapshot,
+          fees: [
+            {
+              ...fee,
+              amount: { ...fee.amount, baseUnits: '500001', formatted: '0.500001' },
+            },
+          ],
+        },
+      })
+      const rejected = await app.request(
+        `/v1/routes/transfers/${malformed.id}/source-transactions`,
+        {
+          body: JSON.stringify({ transactionHashes: sourceTransactionHashes }),
+          headers: { ...as(routesWriter).headers, 'content-type': 'application/json' },
+          method: 'POST',
+        },
+      )
+      expect(rejected.status).toBe(400)
+      expect(((await rejected.json()) as { error: { code: string } }).error.code).toBe(
+        'source_transaction_invalid',
+      )
+    })
+  },
+)
+
+describe('POST /routes/transfers/{destination}', () => {
+  test.each([
+    { body: vaultTransferBody, destination: 'vault' },
+    { body: zoneTransferBody, destination: 'zone' },
+  ] as const)('validates and returns 501 for $destination transfers', async (options) => {
+    const app = transfersApp()
+    const before = await db.kysely
+      .selectFrom('routes_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    const response = await app.request(`/v1/routes/transfers/${options.destination}`, {
+      body: JSON.stringify(options.body),
+      headers: {
+        authorization: `Bearer ${routesWriter.token}`,
+        'content-type': 'application/json',
+        'idempotency-key': `routes_${options.destination}_unimplemented`,
+      },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(501)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe(
+      'not_implemented',
+    )
+    const after = await db.kysely
+      .selectFrom('routes_transfers')
+      .select(({ fn }) => fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+    expect(after.count).toBe(before.count)
+  })
+
+  test('requires the header and validates destination fields', async () => {
+    const app = transfersApp()
+    const missingHeader = await app.request('/v1/routes/transfers/vault', {
+      body: JSON.stringify(vaultTransferBody),
+      headers: {
+        authorization: `Bearer ${routesWriter.token}`,
+        'content-type': 'application/json',
+      },
+      method: 'POST',
+    })
+    expect(missingHeader.status).toBe(400)
+    expect(((await missingHeader.json()) as { error: { code: string } }).error.code).toBe(
+      'idempotency_key_required',
+    )
+
+    const invalidZone = await app.request('/v1/routes/transfers/zone', {
+      body: JSON.stringify({ ...zoneTransferBody, destinationChain: '421700001' }),
+      headers: {
+        authorization: `Bearer ${routesWriter.token}`,
+        'content-type': 'application/json',
+        'idempotency-key': 'routes_zone_invalid',
+      },
+      method: 'POST',
+    })
+    expect(invalidZone.status).toBe(400)
+    expect(((await invalidZone.json()) as { error: { code: string } }).error.code).toBe(
+      'body_invalid',
+    )
+  })
+})
+
+describe('route transfers OpenAPI', () => {
+  test('publishes generator-ready transfer contracts', async () => {
+    const spec = await (await create({ auth: false }).request('/openapi.json')).json()
+    const detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/routes/transfers/{') && !path.endsWith('/source-transactions'),
+    )!
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
+    )!
+    const operations = {
+      create: spec.paths['/v1/routes/transfers'].post,
+      createVault: spec.paths['/v1/routes/transfers/vault'].post,
+      createZone: spec.paths['/v1/routes/transfers/zone'].post,
+      get: spec.paths[detailPath].get,
+      list: spec.paths['/v1/routes/transfers'].get,
+      registerSourceTransaction: spec.paths[sourceTransactionPath].post,
+    }
+    const summarize = (operation: (typeof operations)[keyof typeof operations]) => ({
+      errors: Object.fromEntries(
+        (Object.entries(operation.responses) as [string, ContractResponse][])
+          .filter(([status]) => Number(status) >= 400)
+          .map(([status, response]) => [
+            status,
+            response.$ref ?? response.content?.['application/json']?.schema,
+          ]),
+      ),
+      operationId: operation.operationId,
+      request: operation.requestBody?.content['application/json'].schema,
+      response: operation.responses[200]?.content?.['application/json']?.schema,
+    })
+
+    expect({
+      components: [
+        'CreateRoutesTransferRequest',
+        'CreateRoutesTransferVaultRequest',
+        'CreateRoutesTransferZoneRequest',
+        'CreatedRoutesTransfer',
+        'RoutesAction',
+        'RoutesActionCall',
+        'RoutesEvmCallsAction',
+        'RoutesTransfer',
+        'RoutesTransferFee',
+        'RoutesTransferList',
+        'RoutesTransferQuote',
+        'RoutesTransferStatusReason',
+        'RegisterRoutesTransferSourceTransactionRequest',
+      ].filter((name) => spec.components.schemas[name]),
+      formats: {
+        createdAt: spec.components.schemas.RoutesTransfer.properties.createdAt.format,
+        quoteExpiresAt: spec.components.schemas.RoutesTransferQuote.properties.expiresAt.format,
+        quoteSampledAt: spec.components.schemas.RoutesTransferQuote.properties.sampledAt.format,
+        updatedAt: spec.components.schemas.RoutesTransfer.properties.updatedAt.format,
+      },
+      models: {
+        action: spec.components.schemas.RoutesAction.oneOf,
+        createdAction: spec.components.schemas.CreatedRoutesTransfer.properties.action,
+        evmCall: spec.components.schemas.RoutesEvmCallsAction.properties.calls.items,
+        feeToken: spec.components.schemas.RoutesTransferFee.properties.token,
+        list: spec.components.schemas.RoutesTransferList.properties.data.items,
+        quote: spec.components.schemas.RoutesTransfer.properties.quote,
+        statusReason: spec.components.schemas.RoutesTransfer.properties.statusReason,
+      },
+      operations: {
+        create: summarize(operations.create),
+        createVault: summarize(operations.createVault),
+        createZone: summarize(operations.createZone),
+        get: summarize(operations.get),
+        list: summarize(operations.list),
+        registerSourceTransaction: summarize(operations.registerSourceTransaction),
+      },
+      operationErrorCodes: {
+        createInvalid:
+          spec.components.schemas.ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError
+            .properties.error.properties.code.enum,
+        idempotencyConflict:
+          spec.components.schemas.IdempotencyConflictOrIdempotencyInProgressError.properties.error
+            .properties.code.enum,
+        notImplemented:
+          spec.components.schemas.NotImplemented501Error.properties.error.properties.code.enum,
+        parametersInvalid:
+          spec.components.schemas.ApiKeyMalformedOrParamInvalidError.properties.error.properties
+            .code.enum,
+        queryInvalid:
+          spec.components.schemas.ApiKeyMalformedOrQueryInvalidError.properties.error.properties
+            .code.enum,
+        quoteNotAvailable:
+          spec.components.schemas.QuoteNotAvailableError.properties.error.properties.code.enum,
+        transferNotFound:
+          spec.components.schemas.RoutesTransferNotFoundError.properties.error.properties.code.enum,
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "CreateRoutesTransferRequest",
+          "CreateRoutesTransferVaultRequest",
+          "CreateRoutesTransferZoneRequest",
+          "CreatedRoutesTransfer",
+          "RoutesAction",
+          "RoutesActionCall",
+          "RoutesEvmCallsAction",
+          "RoutesTransfer",
+          "RoutesTransferFee",
+          "RoutesTransferList",
+          "RoutesTransferQuote",
+          "RoutesTransferStatusReason",
+          "RegisterRoutesTransferSourceTransactionRequest",
+        ],
+        "formats": {
+          "createdAt": "date-time",
+          "quoteExpiresAt": "date-time",
+          "quoteSampledAt": "date-time",
+          "updatedAt": "date-time",
+        },
+        "models": {
+          "action": [
+            {
+              "$ref": "#/components/schemas/RoutesEvmCallsAction",
+            },
+          ],
+          "createdAction": {
+            "$ref": "#/components/schemas/RoutesAction",
+          },
+          "evmCall": {
+            "$ref": "#/components/schemas/RoutesActionCall",
+          },
+          "feeToken": {
+            "$ref": "#/components/schemas/RoutesToken",
+          },
+          "list": {
+            "$ref": "#/components/schemas/RoutesTransfer",
+          },
+          "quote": {
+            "$ref": "#/components/schemas/RoutesTransferQuote",
+          },
+          "statusReason": {
+            "$ref": "#/components/schemas/RoutesTransferStatusReason",
+          },
+        },
+        "operationErrorCodes": {
+          "createInvalid": [
+            "api_key_malformed",
+            "body_invalid",
+            "idempotency_key_required",
+          ],
+          "idempotencyConflict": [
+            "idempotency_conflict",
+            "idempotency_in_progress",
+          ],
+          "notImplemented": [
+            "not_implemented",
+          ],
+          "parametersInvalid": [
+            "api_key_malformed",
+            "param_invalid",
+          ],
+          "queryInvalid": [
+            "api_key_malformed",
+            "query_invalid",
+          ],
+          "quoteNotAvailable": [
+            "quote_not_available",
+          ],
+          "transferNotFound": [
+            "routes_transfer_not_found",
+          ],
+        },
+        "operations": {
+          "create": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ApiKeyForbiddenOrApiKeyIpForbiddenOrBillingPastDueOrBillingRequiredOrForbiddenOrRoutesSubsidyLimitExceededOrRoutesSubsidyNotEnabledError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/QuoteNotAvailableError",
+              },
+              "409": {
+                "$ref": "#/components/schemas/IdempotencyConflictOrIdempotencyInProgressError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "503": {
+                "$ref": "#/components/schemas/SubsidyInventoryUnavailableOrSubsidySignerUnavailableError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createRoutesTransfer",
+            "request": {
+              "$ref": "#/components/schemas/CreateRoutesTransferRequest",
+            },
+            "response": {
+              "$ref": "#/components/schemas/CreatedRoutesTransfer",
+            },
+          },
+          "createVault": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createRoutesTransferVault",
+            "request": {
+              "$ref": "#/components/schemas/CreateRoutesTransferVaultRequest",
+            },
+            "response": undefined,
+          },
+          "createZone": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrIdempotencyKeyRequiredError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "createRoutesTransferZone",
+            "request": {
+              "$ref": "#/components/schemas/CreateRoutesTransferZoneRequest",
+            },
+            "response": undefined,
+          },
+          "get": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrParamInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/RoutesTransferNotFoundError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "getRoutesTransfer",
+            "request": undefined,
+            "response": {
+              "$ref": "#/components/schemas/RoutesTransfer",
+            },
+          },
+          "list": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "listRoutesTransfers",
+            "request": undefined,
+            "response": {
+              "$ref": "#/components/schemas/RoutesTransferList",
+            },
+          },
+          "registerSourceTransaction": {
+            "errors": {
+              "400": {
+                "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidOrSourceTransactionInvalidError",
+              },
+              "401": {
+                "$ref": "#/components/schemas/AuthenticationError",
+              },
+              "403": {
+                "$ref": "#/components/schemas/ForbiddenError",
+              },
+              "404": {
+                "$ref": "#/components/schemas/RoutesTransferNotFoundError",
+              },
+              "409": {
+                "$ref": "#/components/schemas/RoutesTransferNotAwaitingSourceOrSourceTransactionConflictOrSourceTransactionPendingError",
+              },
+              "429": "#/components/responses/RateLimited",
+              "500": "#/components/responses/InternalError",
+              "501": {
+                "$ref": "#/components/schemas/NotImplemented501Error",
+              },
+              "502": {
+                "$ref": "#/components/schemas/UpstreamError",
+              },
+              "504": "#/components/responses/RequestTimeout",
+            },
+            "operationId": "registerRoutesTransferSourceTransaction",
+            "request": {
+              "$ref": "#/components/schemas/RegisterRoutesTransferSourceTransactionRequest",
+            },
+            "response": {
+              "$ref": "#/components/schemas/RoutesTransfer",
+            },
+          },
+        },
+      }
+    `)
+  })
+
+  test('publishes an executable account transfer example', async () => {
+    const app = create({ auth: false })
+    type TransferExample = {
+      action: RoutesAction.EvmCalls
+      destinationAmountMin: { baseUnits: string }
+      destinationAmountRequired: { baseUnits: string }
+      destinationChain: { id: string }
+      destinationToken: { address: string }
+      fees: readonly {
+        amount: { baseUnits: string }
+        side: string
+        token: { address?: string | undefined; standard: string; symbol: string }
+      }[]
+      recipient: string
+      sender: string
+      sourceAmount: { baseUnits: string }
+      sourceChain: { id: string }
+      sourceToken: { address: string }
+      subsidize: boolean
+    }
+    type Operation = {
+      requestBody: {
+        content: Record<string, { schema: JsonSchema }>
+      }
+      responses: Record<string, { content: Record<string, { example: TransferExample }> }>
+    }
+    type Spec = ComponentSpec & { paths: Record<string, { post: Operation }> }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const operation = spec.paths['/v1/routes/transfers']!.post
+    const request = dereference(spec, operation.requestBody.content['application/json']!.schema)
+    const response = operation.responses['200']!.content['application/json']!.example
+
+    expect({
+      request: {
+        destinationChain: request.properties!['destinationChain']!.examples,
+        destinationToken: request.properties!['destinationToken']!.examples,
+        sourceChain: request.properties!['sourceChain']!.examples,
+        sourceToken: request.properties!['sourceToken']!.examples,
+        subsidyDescription: request.properties!['subsidize']!.description,
+        subsidize: request.properties!['subsidize']!.examples,
+      },
+      response,
+    }).toEqual({
+      request: {
+        destinationChain: ['base', 'ethereum', 'tempo', 'eip155:8453'],
+        destinationToken: ['usdc', 'pathusd'],
+        sourceChain: ['tempo', 'base', 'ethereum', 'eip155:4217'],
+        sourceToken: ['usdce', 'usdc'],
+        subsidyDescription:
+          'Guarantees normalized 1:1 delivery for exact-source Tempo USD transfers to Base or Ethereum. A Tempo Admin must enable subsidies for the organization.',
+        subsidize: [true],
+      },
+      response: expect.objectContaining({
+        action: expect.objectContaining({ type: 'evm:calls' }),
+        destinationAmountMin: expect.objectContaining({ baseUnits: '974398' }),
+        destinationAmountRequired: expect.objectContaining({ baseUnits: '1000000' }),
+        destinationChain: expect.objectContaining({ id: 'eip155:8453' }),
+        destinationToken: expect.objectContaining({
+          address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        }),
+        fees: [
+          expect.objectContaining({
+            amount: expect.objectContaining({ baseUnits: '10000' }),
+            side: 'source',
+            token: expect.objectContaining({
+              address: '0x20c0000000000000000000000000000000000000',
+              standard: 'TIP-20',
+              symbol: 'pathUSD',
+            }),
+          }),
+        ],
+        sourceChain: expect.objectContaining({ id: 'eip155:4217' }),
+        sourceToken: expect.objectContaining({
+          address: '0x20c000000000000000000000b9537d11c60e8b50',
+        }),
+        subsidize: true,
+      }),
+    })
+    const calls = response.action.calls
+    expect(calls).toHaveLength(5)
+    expect(calls.map((call) => ({ to: call.to, value: call.value }))).toEqual([
+      { to: response.sourceToken.address, value: '0x0' },
+      { to: response.fees[0]!.token.address, value: '0x0' },
+      { to: '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb', value: '0x0' },
+      { to: '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb', value: '0x0' },
+      { to: '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392', value: '0x0' },
+    ])
+    const approve = AbiFunction.from('function approve(address spender, uint256 amount)')
+    const wrap = AbiFunction.from('function wrap(address token, address to, uint256 amount)')
+    const send = AbiFunction.from(
+      'function send((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress) payable returns ((bytes32 guid, uint64 nonce, (uint256 nativeFee, uint256 lzTokenFee) fee) msgReceipt, (uint256 amountSentLD, uint256 amountReceivedLD) oftReceipt)',
+    )
+    expect(AbiFunction.decodeData(approve, calls[0]!.data as Hex.Hex)).toEqual([
+      '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392',
+      1_000_000n,
+    ])
+    expect(AbiFunction.decodeData(approve, calls[1]!.data as Hex.Hex)).toEqual([
+      '0x0ceb237e109ee22374a567c6b09f373c73fa4cbb',
+      10_000n,
+    ])
+    expect(AbiFunction.decodeData(wrap, calls[2]!.data as Hex.Hex)).toEqual([
+      '0x20c0000000000000000000000000000000000000',
+      response.sender,
+      10_000n,
+    ])
+    expect(AbiFunction.decodeData(approve, calls[3]!.data as Hex.Hex)).toEqual([
+      '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392',
+      10_000n,
+    ])
+    const [sendParameters, messagingFee, refundAddress] = AbiFunction.decodeData(
+      send,
+      calls[4]!.data as Hex.Hex,
+    )
+    expect(sendParameters).toMatchObject({
+      amountLD: 1_000_000n,
+      dstEid: 30_184,
+      minAmountLD: 974_398n,
+    })
+    expect(messagingFee).toEqual({ lzTokenFee: 0n, nativeFee: 10_000n })
+    expect(refundAddress).toBe(response.sender)
+    expect(
+      Stargate.validateAction({
+        action: response.action,
+        configuration: {
+          destinationPoolAddress: '0x27a16dc786820b16e5c9028b75b99f6f604b5d26',
+          poolAddress: '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392',
+        },
+        destinationAmountMin: response.destinationAmountMin.baseUnits,
+        destinationChainId: response.destinationChain.id,
+        destinationTokenAddress: response.destinationToken.address,
+        recipient: response.recipient,
+        sender: response.sender,
+        sourceAmount: response.sourceAmount.baseUnits,
+        sourceChainId: response.sourceChain.id,
+        sourceTokenAddress: response.sourceToken.address,
+      }),
+    ).toEqual({
+      tokenApprovals: [
+        {
+          amount: '10000',
+          spender: '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb',
+          token: '0x20C0000000000000000000000000000000000000',
+        },
+        {
+          amount: '10000',
+          spender: '0x8c76e2F6C5ceDA9AA7772e7efF30280226c44392',
+          token: '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb',
+        },
+      ],
+    })
+  })
+
+  test('publishes human-readable deposit address route examples', async () => {
+    const app = create({ auth: false })
+    type Operation = {
+      requestBody: {
+        content: Record<string, { schema: JsonSchema }>
+      }
+    }
+    type Spec = ComponentSpec & { paths: Record<string, { post: Operation }> }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const properties = dereference(
+      spec,
+      spec.paths['/v1/routes/deposit-addresses']!.post.requestBody.content['application/json']!
+        .schema,
+    ).properties!
+
+    expect({
+      destinationToken: properties['destinationToken']!.examples,
+      sourceChain: properties['sourceChain']!.examples,
+      sourceToken: properties['sourceToken']!.examples,
+    }).toMatchInlineSnapshot(`
+      {
+        "destinationToken": [
+          "usdt0",
+        ],
+        "sourceChain": [
+          "tron",
+          "tron:0x2b6653dc",
+        ],
+        "sourceToken": [
+          "usdt",
+        ],
+      }
+    `)
+  })
+
+  test('publishes concise operation documentation', async () => {
+    const app = create({ auth: false })
+    type Operation = { description: string; summary: string; tags: string[] }
+    type Spec = {
+      paths: Record<string, { get?: Operation; post?: Operation }>
+      tags: { description?: string; name: string }[]
+      'x-tagGroups': { name: string; tags: string[] }[]
+    }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/routes/transfers/{') && !path.endsWith('/source-transactions'),
+    )!
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
+    )!
+    const depositAddressPath = Object.keys(spec.paths).find(
+      (path) =>
+        path.includes('/v1/routes/deposit-addresses/{') &&
+        !path.endsWith('/deposits') &&
+        !path.endsWith('/reconcile'),
+    )!
+    const depositPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/routes/deposits/{'),
+    )!
+    const reconcilePath = Object.keys(spec.paths).find((path) => path.endsWith('/reconcile'))!
+    const summarize = (operation: Operation) => ({
+      description: operation.description,
+      summary: operation.summary,
+    })
+    const operations = {
+      account: summarize(spec.paths['/v1/routes/transfers']!.post!),
+      chains: summarize(spec.paths['/v1/routes/chains']!.get!),
+      deposit: summarize(spec.paths[depositPath]!.get!),
+      depositAddress: summarize(spec.paths[depositAddressPath]!.get!),
+      depositAddressCreate: summarize(spec.paths['/v1/routes/deposit-addresses']!.post!),
+      depositAddressList: summarize(spec.paths['/v1/routes/deposit-addresses']!.get!),
+      depositAddressReconcile: summarize(spec.paths[reconcilePath]!.post!),
+      deposits: summarize(spec.paths['/v1/routes/deposits']!.get!),
+      detail: summarize(spec.paths[detailPath]!.get!),
+      list: summarize(spec.paths['/v1/routes/transfers']!.get!),
+      providers: summarize(spec.paths['/v1/routes/providers']!.get!),
+      quotes: summarize(spec.paths['/v1/routes/quotes']!.get!),
+      sourceTransaction: summarize(spec.paths[sourceTransactionPath]!.post!),
+      vault: summarize(spec.paths['/v1/routes/transfers/vault']!.post!),
+      zone: summarize(spec.paths['/v1/routes/transfers/zone']!.post!),
+    }
+    const category = spec['x-tagGroups'].find((group) => group.name === 'Routes API')
+    const categoryTags = new Set(category?.tags)
+    const sidebar = Object.values(spec.paths).flatMap((path) =>
+      [path.get, path.post].flatMap((operation) =>
+        operation?.tags.some((tag) => categoryTags.has(tag)) ? [operation.summary] : [],
+      ),
+    )
+
+    for (const operation of Object.values(operations))
+      expect(operation.description.split(/\s+/).length).toBeLessThan(15)
+
+    expect({
+      category: category?.name,
+      operations,
+      sidebar,
+    }).toMatchInlineSnapshot(`
+      {
+        "category": "Routes API",
+        "operations": {
+          "account": {
+            "description": "Creates a durable transfer between supported chains, including optional normalized destination subsidies.",
+            "summary": "Create transfer",
+          },
+          "chains": {
+            "description": "Lists supported source chains and tokens.",
+            "summary": "Get chains",
+          },
+          "deposit": {
+            "description": "Returns one detected deposit and its delivery status.",
+            "summary": "Get deposit",
+          },
+          "depositAddress": {
+            "description": "Returns one reusable route deposit address.",
+            "summary": "Get deposit address",
+          },
+          "depositAddressCreate": {
+            "description": "Creates or returns a reusable deposit address for routes a Tempo account.",
+            "summary": "Create deposit address",
+          },
+          "depositAddressList": {
+            "description": "Lists reusable route deposit addresses, newest first.",
+            "summary": "List deposit addresses",
+          },
+          "depositAddressReconcile": {
+            "description": "Queues an immediate provider reconciliation for one reusable route deposit address.",
+            "summary": "Reconcile deposit address",
+          },
+          "deposits": {
+            "description": "Lists visible deposits, optionally filtered, newest first.",
+            "summary": "List deposits",
+          },
+          "detail": {
+            "description": "Returns a transfer by ID.",
+            "summary": "Get transfer",
+          },
+          "list": {
+            "description": "Lists transfers from newest to oldest.",
+            "summary": "List transfers",
+          },
+          "providers": {
+            "description": "Lists available transfer providers.",
+            "summary": "Get providers",
+          },
+          "quotes": {
+            "description": "Returns live quotes for transferring stablecoins between supported chains.",
+            "summary": "Get quotes",
+          },
+          "sourceTransaction": {
+            "description": "Registers verified source transactions once per organization, environment, and project.",
+            "summary": "Register source transaction",
+          },
+          "vault": {
+            "description": "Creates a transfer into a Tempo Earn vault.",
+            "summary": "Create transfer into vault",
+          },
+          "zone": {
+            "description": "Creates a transfer into a Tempo Zone.",
+            "summary": "Create transfer into zone",
+          },
+        },
+        "sidebar": [
+          "Get quotes",
+          "Get chains",
+          "Get providers",
+          "List deposit addresses",
+          "Create deposit address",
+          "Register source transaction",
+          "List transfers",
+          "Create transfer",
+          "Create transfer into vault",
+          "Create transfer into zone",
+          "Reconcile deposit address",
+          "Get deposit address",
+          "Get transfer",
+          "Get deposit",
+          "List deposits",
+        ],
+      }
+    `)
+  })
+
+  test('publishes concrete creation schemas', async () => {
+    const app = create({ auth: false })
+    type Spec = ComponentSpec & {
+      paths: Record<
+        string,
+        {
+          post?: {
+            requestBody: {
+              content: Record<string, { schema: JsonSchema }>
+            }
+            responses: Record<string, unknown>
+          }
+        }
+      >
+    }
+    const spec = (await (await app.request('/openapi.json')).json()) as Spec
+    const creationSchema = (path: string) =>
+      dereference(spec, spec.paths[path]!.post!.requestBody.content['application/json']!.schema)
+    expect(
+      creationSchema('/v1/routes/deposit-addresses').required?.includes('subsidize') ?? false,
+    ).toMatchInlineSnapshot(`false`)
+    const summarize = (path: string) => {
+      const schema = creationSchema(path)
+      return {
+        additionalProperties: schema.additionalProperties,
+        properties: Object.keys(schema.properties!),
+      }
+    }
+
+    expect({
+      account: summarize('/v1/routes/transfers'),
+      depositAddress: summarize('/v1/routes/deposit-addresses'),
+      depositAddressResponses: Object.keys(
+        spec.paths['/v1/routes/deposit-addresses']!.post!.responses,
+      ),
+      vault: summarize('/v1/routes/transfers/vault'),
+      vaultResponses: Object.keys(spec.paths['/v1/routes/transfers/vault']!.post!.responses),
+      zone: summarize('/v1/routes/transfers/zone'),
+      zoneResponses: Object.keys(spec.paths['/v1/routes/transfers/zone']!.post!.responses),
+    }).toMatchInlineSnapshot(`
+      {
+        "account": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationChain",
+            "destinationToken",
+            "mode",
+            "provider",
+            "recipient",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+            "subsidize",
+          ],
+        },
+        "depositAddress": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationToken",
+            "recipient",
+            "refundAddress",
+            "sourceChain",
+            "sourceToken",
+            "subsidize",
+          ],
+        },
+        "depositAddressResponses": [
+          "200",
+          "400",
+          "401",
+          "403",
+          "404",
+          "409",
+          "429",
+          "500",
+          "502",
+          "504",
+        ],
+        "vault": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "mode",
+            "recipient",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+            "vaultAddress",
+          ],
+        },
+        "vaultResponses": [
+          "400",
+          "401",
+          "403",
+          "429",
+          "500",
+          "501",
+          "504",
+        ],
+        "zone": {
+          "additionalProperties": false,
+          "properties": [
+            "amount",
+            "destinationChain",
+            "destinationToken",
+            "mode",
+            "recipient",
+            "recipientFallback",
+            "sender",
+            "slippageBps",
+            "sourceChain",
+            "sourceToken",
+          ],
+        },
+        "zoneResponses": [
+          "400",
+          "401",
+          "403",
+          "429",
+          "500",
+          "501",
+          "504",
+        ],
+      }
+    `)
+  })
+
+  test('publishes alphabetically ordered example fields and parameter examples', async () => {
+    const app = create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<
+        string,
+        {
+          get: {
+            parameters?: { example?: unknown; name: string; schema?: { examples?: unknown } }[]
+            responses: Record<string, { content: Record<string, { example: { data: {}[] } }> }>
+          }
+        }
+      >
+    }
+    const operation = spec.paths['/v1/routes/transfers']!.get
+    const fields = Object.keys(operation.responses['200']!.content['application/json']!.example.data[0]!) // prettier-ignore
+    expect(fields).toEqual([...fields].sort())
+    for (const route of [
+      operation,
+      spec.paths['/v1/routes/deposit-addresses']!.get,
+      spec.paths['/v1/routes/deposits']!.get,
+    ])
+      for (const parameter of route.parameters ?? [])
+        expect(parameter.example ?? parameter.schema?.examples, parameter.name).toBeDefined()
+  })
+
+  test('publishes operation ids and required scopes', async () => {
+    const app = create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as {
+      paths: Record<
+        string,
+        {
+          get: { operationId: string; 'x-required-scopes': string[] }
+          post?: {
+            operationId: string
+            parameters: { in: string; name: string; required: boolean }[]
+            'x-required-scopes': string[]
+          }
+        }
+      >
+    }
+    const detailPath = Object.keys(spec.paths).find(
+      (path) => path.includes('/v1/routes/transfers/{') && !path.endsWith('/source-transactions'),
+    )
+    const sourceTransactionPath = Object.keys(spec.paths).find((path) =>
+      path.endsWith('/source-transactions'),
+    )
+    const depositAddressPath = Object.keys(spec.paths).find(
+      (path) =>
+        path.includes('/v1/routes/deposit-addresses/{') &&
+        !path.endsWith('/deposits') &&
+        !path.endsWith('/reconcile'),
+    )
+    const depositPath = Object.keys(spec.paths).find((path) =>
+      path.includes('/v1/routes/deposits/{'),
+    )
+    const reconcilePath = Object.keys(spec.paths).find((path) => path.endsWith('/reconcile'))
+    expect({
+      deposit: depositPath && spec.paths[depositPath]?.get.operationId,
+      depositAddress: depositAddressPath && spec.paths[depositAddressPath]?.get.operationId,
+      depositAddressCreate: spec.paths['/v1/routes/deposit-addresses']?.post?.operationId,
+      depositAddressCreateScopes:
+        spec.paths['/v1/routes/deposit-addresses']?.post?.['x-required-scopes'],
+      depositAddressList: spec.paths['/v1/routes/deposit-addresses']?.get.operationId,
+      depositAddressListScopes:
+        spec.paths['/v1/routes/deposit-addresses']?.get['x-required-scopes'],
+      depositAddressReconcile: reconcilePath && spec.paths[reconcilePath]?.post?.operationId,
+      depositAddressReconcileScopes:
+        reconcilePath && spec.paths[reconcilePath]?.post?.['x-required-scopes'],
+      depositAddressScopes:
+        depositAddressPath && spec.paths[depositAddressPath]?.get['x-required-scopes'],
+      depositScopes: depositPath && spec.paths[depositPath]?.get['x-required-scopes'],
+      deposits: spec.paths['/v1/routes/deposits']?.get.operationId,
+      depositsScopes: spec.paths['/v1/routes/deposits']?.get['x-required-scopes'],
+      detail: detailPath && spec.paths[detailPath]?.get.operationId,
+      detailScopes: detailPath && spec.paths[detailPath]?.get['x-required-scopes'],
+      list: spec.paths['/v1/routes/transfers']?.get.operationId,
+      listScopes: spec.paths['/v1/routes/transfers']?.get['x-required-scopes'],
+      requiredCreateHeader: spec.paths['/v1/routes/transfers']?.post?.parameters.find(
+        (parameter) => parameter.name === 'idempotency-key',
+      ),
+      sourceTransaction:
+        sourceTransactionPath && spec.paths[sourceTransactionPath]?.post?.operationId,
+      sourceTransactionScopes:
+        sourceTransactionPath && spec.paths[sourceTransactionPath]?.post?.['x-required-scopes'],
+      vault: spec.paths['/v1/routes/transfers/vault']?.post?.operationId,
+      vaultScopes: spec.paths['/v1/routes/transfers/vault']?.post?.['x-required-scopes'],
+      zone: spec.paths['/v1/routes/transfers/zone']?.post?.operationId,
+      zoneScopes: spec.paths['/v1/routes/transfers/zone']?.post?.['x-required-scopes'],
+    }).toEqual({
+      deposit: 'getRoutesDeposit',
+      depositAddress: 'getRoutesDepositAddress',
+      depositAddressCreate: 'createRoutesDepositAddress',
+      depositAddressCreateScopes: ['routes:write'],
+      depositAddressList: 'listRoutesDepositAddresses',
+      depositAddressListScopes: ['routes:read'],
+      depositAddressReconcile: 'reconcileRoutesDepositAddress',
+      depositAddressReconcileScopes: ['routes:write'],
+      depositAddressScopes: ['routes:read'],
+      depositScopes: ['routes:read'],
+      deposits: 'listRoutesDeposits',
+      depositsScopes: ['routes:read'],
+      detail: 'getRoutesTransfer',
+      detailScopes: ['routes:read'],
+      list: 'listRoutesTransfers',
+      listScopes: ['routes:read'],
+      requiredCreateHeader: expect.objectContaining({
+        description: expect.stringContaining('24 hours'),
+        in: 'header',
+        name: 'idempotency-key',
+        required: true,
+        schema: expect.any(Object),
+      }),
+      sourceTransaction: 'registerRoutesTransferSourceTransaction',
+      sourceTransactionScopes: ['routes:write'],
+      vault: 'createRoutesTransferVault',
+      vaultScopes: ['routes:write'],
+      zone: 'createRoutesTransferZone',
+      zoneScopes: ['routes:write'],
+    })
+  })
+})
+
+const routesReader = {
+  id: 'key_routes',
+  orgId: 'org_routes',
+  scopes: ['routes:read'],
+  token: 'secret_routes_reader',
+} satisfies TestApp.kvStore.Key
+
+const routesProjectReader = {
+  id: 'key_routes_project',
+  orgId: 'org_routes',
+  projectId: 'prj_routes',
+  scopes: ['routes:read'],
+  token: 'secret_routes_project',
+} satisfies TestApp.kvStore.Key
+
+const routesForeign = {
+  id: 'key_routes_other',
+  orgId: 'org_routes_other',
+  scopes: ['routes:read', 'routes:write'],
+  token: 'secret_routes_other',
+} satisfies TestApp.kvStore.Key
+
+const routesWriter = {
+  id: 'key_routes_writer',
+  orgId: 'org_routes',
+  scopes: ['routes:read', 'routes:write'],
+  token: 'secret_routes_writer',
+} satisfies TestApp.kvStore.Key
+
+function transfersApp(options: TestApp.create.Options = {}) {
+  return create({
+    ...options,
+    auth: {
+      keys: [TestApp.key, routesReader, routesProjectReader, routesForeign, routesWriter],
+    },
+    db: options.db ?? db,
+    defaultChainId: options.defaultChainId ?? tempoMainnet.id,
+  })
+}
+
+function transferSubsidy(maxAmount: string): RoutesTransferSubsidy.Inventory {
+  return {
+    account: `0x${'77'.repeat(20)}`,
+    async check() {
+      return { nativeAmount: '100' }
+    },
+    policy: { maxAmount },
+  }
+}
+
+function as(key: { token: string }) {
+  return { headers: { authorization: `Bearer ${key.token}` } } as const
+}
+
+let seedSecond = 0
+
+function seedTransfer(input: Partial<RoutesTransfer.create.Input> = {}) {
+  // Distinct create times keep ids strictly ordered for paging assertions.
+  return RoutesTransfer.create(db, {
+    apiKeyId: routesReader.id,
+    environment: 'production',
+    id: RoutesTransfer.generateId(new Date(Date.UTC(2026, 0, 2, 0, 0, seedSecond++))),
+    orgId: routesReader.orgId,
+    snapshot: TestRoutes.transferSnapshot(),
+    ...input,
+  })
+}