tapimo 0.7.0 → 0.7.2

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

@@ -1,108 +1,35 @@
-import { Hono } from 'hono'
+import { type Context, Hono } from 'hono'
+import { etag } from 'hono/etag'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
+import * as Db from '../../../db/Db.js'
+import * as FundingDepositAddresses from '../../../db/tables/fundingDepositAddresses.js'
+import * as FundingDeposits from '../../../db/tables/fundingDeposits.js'
+import * as FundingIdempotency from '../../../db/tables/fundingIdempotency.js'
+import * as FundingTransfers from '../../../db/tables/fundingTransfers.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
-import * as FundingQuotes from '../../../internal/FundingQuotes.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as FundingCatalog from '../../../internal/funding/Catalog.js'
+import * as FundingDeposit from '../../../internal/funding/Deposit.js'
+import * as FundingDepositAddress from '../../../internal/funding/DepositAddress.js'
+import * as FundingProvider from '../../../internal/funding/Provider.js'
+import * as FundingTransfer from '../../../internal/funding/Transfer.js'
+import * as Idempotency from '../../../internal/Idempotency.js'
 import type * as Log from '../../../internal/Log.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Value from '../../../internal/Value.js'
-import * as FundingQuoteProviders from '../FundingQuoteProviders.js'
 
 /** Zod schemas owned by funding quote resources. */
 export namespace schema {
   /** Source or destination chain reference. */
-  export const Chain = Schema.describe(
-    z.object({
-      addressFormat: z
-        .enum(['base58', 'base58check', 'evm'])
-        .check(
-          z.describe('Address family used by accounts and token identifiers on this chain.'),
-          z.meta({ examples: ['evm'] }),
-        ),
-      id: z
-        .string()
-        .check(
-          z.describe(
-            'Stable chain id. Uses CAIP-2 where standardized and a Tempo-defined compatible id otherwise.',
-          ),
-          z.meta({ examples: ['eip155:8453'] }),
-        ),
-      kind: z
-        .enum(['evm', 'solana', 'tron'])
-        .check(
-          z.describe('Chain execution family used for provider routing.'),
-          z.meta({ examples: ['evm'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
-      providerIds: z
-        .optional(z.record(z.string(), z.string()))
-        .check(
-          z.describe('Provider-specific chain ids Tempo uses when requesting quotes.'),
-          z.meta({ examples: [{ across: '8453', relay: '8453', rhino: 'BASE' }] }),
-        ),
-    }),
-    'A normalized chain reference for funding quotes.',
-  )
+  export const Chain = FundingProvider.schema.ChainRef
 
   /** Source or destination token reference. */
-  export const Token = Schema.describe(
-    z.object({
-      address: z
-        .string()
-        .check(
-          z.describe('Contract address, mint, or issuer address on the token chain.'),
-          z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
-        ),
-      currency: z
-        .string()
-        .check(
-          z.describe('Monetary denomination represented by this token.'),
-          z.meta({ examples: ['USD'] }),
-        ),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.describe('Number of decimal places this token uses.'),
-          z.meta({ examples: [6] }),
-        ),
-      metadata: z
-        .record(z.string(), z.string())
-        .check(
-          z.describe('Curated display or lookup metadata for this token.'),
-          z.meta({ examples: [{ coingeckoId: 'usd-coin' }] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
-      standard: z
-        .string()
-        .check(z.describe('Token standard on the token chain.'), z.meta({ examples: ['ERC-20'] })),
-      symbol: z
-        .string()
-        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
-      tokenKey: z.string().check(
-        z.describe('Stable Tempo token key scoped to the token chain.'),
-        z.meta({
-          examples: ['eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
-        }),
-      ),
-      verified: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo recognizes this token in its funding quote inventory.'),
-          z.meta({ examples: [true] }),
-        ),
-    }),
-    'A normalized token reference for funding quotes.',
-  )
+  export const Token = FundingProvider.schema.TokenRef
 
   /** Self-contained source or destination amount in a funding quote. */
   export const TokenAmount = Schema.describe(
@@ -111,138 +38,19 @@ export namespace schema {
   )
 
   /** Provider summary embedded in a funding quote. */
-  export const ProviderRef = Schema.describe(
-    z.object({
-      id: z
-        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
-        .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
-      kind: z
-        .string()
-        .check(
-          z.describe('Provider category, such as a solver network or aggregator.'),
-          z.meta({ examples: ['solverNetwork'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-      requiresApiKey: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo needs provider credentials to query or use this provider.'),
-          z.meta({ examples: [false] }),
-        ),
-    }),
-    'Provider metadata embedded in a funding quote.',
-  )
+  export const ProviderRef = FundingProvider.schema.ProviderRef
 
   /** Quote quality signals exposed directly instead of implied by list order. */
-  export const Quality = Schema.describe(
-    z.object({
-      estimatedSeconds: z
-        .optional(z.number().check(z.int(), z.nonnegative()))
-        .check(
-          z.describe('Estimated settlement time in seconds, when known.'),
-          z.meta({ examples: [2] }),
-        ),
-      liquiditySource: z
-        .string()
-        .check(
-          z.describe('Provider source for the live quote quality signal.'),
-          z.meta({ examples: ['providerQuote'] }),
-        ),
-      sourceDetail: z
-        .optional(z.string())
-        .check(
-          z.describe('Provider-specific source or endpoint detail for the quality signal.'),
-          z.meta({ examples: ['providerEndpoint'] }),
-        ),
-      tier: z
-        .enum(['liquid', 'thin'])
-        .check(
-          z.describe('Machine-readable quality tier for a successful quote.'),
-          z.meta({ examples: ['liquid'] }),
-        ),
-    }),
-    'Machine-readable liquidity, fee, and source signals for a successful quote.',
-  )
+  export const Quality = FundingProvider.schema.FundingQuoteQuality
 
   /** Provider quote freshness data. */
-  export const QuoteDetails = Schema.describe(
-    z.object({
-      expiresAt: z
-        .optional(z.iso.datetime())
-        .check(
-          z.describe('Timestamp after which the provider quote is no longer valid.'),
-          z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
-        ),
-      sampledAt: z.iso
-        .datetime()
-        .check(
-          z.describe('Timestamp for the live quote probe.'),
-          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
-        ),
-    }),
-    'Freshness data for a provider funding quote.',
-  )
+  export const QuoteDetails = FundingProvider.schema.QuoteDetails
 
   /** Successful live funding quote. */
-  export const FundingQuote = Schema.describe(
-    z.object({
-      destinationAmount: TokenAmount.check(z.describe('Expected destination amount.')),
-      destinationAmountMin: z
-        .optional(TokenAmount)
-        .check(
-          z.describe(
-            'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
-          ),
-        ),
-      destinationChain: Chain.check(z.describe('Destination chain, always Tempo mainnet in V1.')),
-      destinationToken: Token.check(z.describe('Tempo token expected from this quote.')),
-      id: z
-        .string()
-        .check(
-          z.describe('Stable deterministic funding quote id.'),
-          z.meta({ examples: ['base-usdc-tempo-usdce-relay'] }),
-        ),
-      provider: ProviderRef,
-      quality: Quality,
-      quote: QuoteDetails,
-      sourceAmount: TokenAmount,
-      sourceChain: Chain.check(z.describe('Chain where the caller currently holds funds.')),
-      sourceToken: Token.check(z.describe('Token the caller currently holds.')),
-    }),
-    'One successful provider-specific funding quote.',
-  )
+  export const FundingQuote = FundingProvider.schema.FundingQuote
 
   /** Funding quote provider catalog entry. */
-  export const Provider = Schema.describe(
-    z.object({
-      id: z
-        .enum(['across', 'relay', 'rhino', 'squid', 'symbiosis'])
-        .check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
-      kind: z
-        .string()
-        .check(z.describe('Provider category.'), z.meta({ examples: ['solverNetwork'] })),
-      name: z
-        .string()
-        .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-      requiresApiKey: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo needs provider credentials to query or use this provider.'),
-          z.meta({ examples: [false] }),
-        ),
-      status: z
-        .enum(['configured', 'unconfigured'])
-        .check(
-          z.describe(
-            '`configured` means live quotes are enabled for this deployment. `unconfigured` means the provider is supported but unavailable here.',
-          ),
-          z.meta({ examples: ['configured', 'unconfigured'] }),
-        ),
-    }),
-    'One funding quote provider.',
-  )
+  export const Provider = Schema.describe(ProviderRef, 'One funding quote provider.')
 
   /** Chain inventory entry returned by the funding chains endpoint. */
   export const ChainInventory = Schema.describe(
@@ -255,59 +63,7 @@ export namespace schema {
   /** Schemas for the quoteFunding operation. */
   export namespace quoteFunding {
     /** Query parameters for live funding quotes. */
-    export const Query = z
-      .strictObject({
-        destinationToken: z
-          .optional(z.string())
-          .check(
-            z.describe(
-              'Tempo destination token symbol, address, or token key. Defaults to USDC.e.',
-            ),
-            z.meta({ examples: ['USDC.e'] }),
-          ),
-        provider: z
-          .optional(z.enum(['across', 'relay', 'rhino', 'squid', 'symbiosis']))
-          .check(
-            z.describe(
-              'Only request a quote from this provider. Supported ids are `across`, `relay`, `rhino`, `squid`, and `symbiosis`; omit it to query every configured provider.',
-            ),
-            z.meta({ examples: ['relay'] }),
-          ),
-        sourceAmount: z
-          .string()
-          .check(
-            z.regex(/^(?=.*[1-9])\d+(\.\d+)?$/),
-            z.describe(
-              'Positive source token amount. Base units by default, so 1 USDC is `1000000`.',
-            ),
-            z.meta({ examples: ['1000000'] }),
-          ),
-        sourceAmountUnits: z
-          ._default(z.enum(['baseUnits', 'decimal']), 'baseUnits')
-          .check(
-            z.describe('Whether `sourceAmount` is base units or a human-readable decimal.'),
-            z.meta({ examples: ['baseUnits', 'decimal'] }),
-          ),
-        sourceChain: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe(
-              'Source chain alias or stable id, such as `base`, `solana`, or `eip155:8453`.',
-            ),
-            z.meta({ examples: ['base', 'eip155:8453'] }),
-          ),
-        sourceToken: z
-          .string()
-          .check(
-            z.minLength(1),
-            z.describe(
-              'Source token symbol, contract address, or Tempo token key. Lookup is scoped to `sourceChain`; non-EVM addresses are case-sensitive. An unknown token returns an empty list.',
-            ),
-            z.meta({ examples: ['USDC', '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
-          ),
-      })
-      .check(z.describe('Query parameters for live funding quotes into Tempo.'))
+    export const Query = FundingProvider.schema.QuoteRequest
 
     /** Non-paginated list of successful funding quotes. */
     export const Response = Schema.describe(
@@ -318,8 +74,8 @@ export namespace schema {
     )
   }
 
-  /** Schemas for the listFundingChains operation. */
-  export namespace listFundingChains {
+  /** Schemas for the getFundingChains operation. */
+  export namespace getFundingChains {
     /** Non-paginated source-chain inventory. */
     export const Response = Schema.describe(
       z.object({
@@ -331,8 +87,8 @@ export namespace schema {
     )
   }
 
-  /** Schemas for the listProviders operation. */
-  export namespace listProviders {
+  /** Schemas for the getFundingProviders operation. */
+  export namespace getFundingProviders {
     /** Non-paginated funding quote provider catalog. */
     export const Response = Schema.describe(
       z.object({
@@ -341,69 +97,601 @@ export namespace schema {
       'A non-paginated list of funding quote providers.',
     )
   }
+
+  /** A durable funding transfer. Reads never include the executable `action`. */
+  export const Transfer = FundingTransfer.schema.FundingTransfer
+
+  /** One reusable funding deposit address. */
+  export const DepositAddress = FundingDepositAddress.schema.FundingDepositAddress
+
+  /** One detected funding deposit. */
+  export const Deposit = FundingDeposit.schema.FundingDeposit
+
+  /** Schemas for the createFundingDepositAddress operation. */
+  export namespace createFundingDepositAddress {
+    /** Funding deposit address creation request body. */
+    export const Body = z
+      .strictObject({
+        amount: FundingTransfer.schema.CreateRequest.shape.amount,
+        destinationToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Tempo destination token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdt0'] }),
+          ),
+        recipient: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Tempo account that receives completed deposits.'),
+            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+          ),
+        refundAddress: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source-chain account that receives refunds.'),
+            z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+          ),
+        sourceChain: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source chain CAIP-2 id, slug, or alias.'),
+            z.meta({ examples: ['tron', 'tron:0x2b6653dc'] }),
+          ),
+        sourceToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdt'] }),
+          ),
+        subsidize: z
+          .optional(z.boolean())
+          .check(
+            z.describe('Guarantees normalized 1:1 delivery through a Tempo-funded subsidy.'),
+            z.meta({ examples: [false] }),
+          ),
+      })
+      .check(z.describe('Reusable funding deposit address creation request.'))
+
+    /** Required headers for funding deposit address creation. */
+    export const Headers = z.object({
+      'idempotency-key': z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe(
+            'Opaque retry key scoped to the API key. Matching requests replay successful responses for 24 hours; changed input conflicts, in-flight requests block, and failed attempts release the key.',
+          ),
+          z.meta({ examples: ['funding_01k1c5j8q8p0be6j5v9m6d1e4r'] }),
+        ),
+    })
+
+    /** The reusable address, with quoted terms only when the provider address was newly stored. */
+    export const Response = z
+      .union([
+        FundingDepositAddress.schema.CreatedFundingDepositAddress,
+        FundingDepositAddress.schema.FundingDepositAddress,
+      ])
+      .check(
+        z.describe(
+          'A reusable funding deposit address, including terms sampled for a newly stored provider address.',
+        ),
+      )
+  }
+
+  /** Schemas for the getFundingDepositAddress operation. */
+  export namespace getFundingDepositAddress {
+    /** Path parameters for reading a funding deposit address. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.regex(/^fda_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit address ID (`fda_…`).'),
+            z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for reading a funding deposit address.'))
+
+    /** One reusable funding deposit address. */
+    export const Response = DepositAddress
+  }
+
+  /** Schemas for the listFundingDepositAddressDeposits operation. */
+  export namespace listFundingDepositAddressDeposits {
+    /** Path parameters for listing one address's deposits. */
+    export const Params = getFundingDepositAddress.Params
+
+    /** Query parameters for listing one address's deposits. */
+    export const Query = z
+      .object({ cursor: Schema.Cursor, limit: Schema.Limit })
+      .check(z.describe('Paging parameters for one funding deposit address.'))
+
+    /** One page of detected deposits. */
+    export const Response = z
+      .object({
+        data: z.array(Deposit).check(z.describe('Detected deposits on this page, newest first.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of deposits detected for one funding deposit address.'))
+  }
+
+  /** Schemas for the getFundingDeposit operation. */
+  export namespace getFundingDeposit {
+    /** Path parameters for reading a funding deposit. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.regex(/^fdp_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit id (`fdp_…`).'),
+            z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for reading a funding deposit.'))
+
+    /** One detected funding deposit. */
+    export const Response = Deposit
+  }
+
+  /** Schemas for the listFundingTransfers operation. */
+  export namespace listFundingTransfers {
+    /** Query parameters for listing funding transfers. */
+    export const Query = z
+      .object({
+        cursor: Schema.Cursor,
+        include: Schema.totalCountInclude,
+        limit: Schema.Limit,
+        status: z.optional(FundingTransfer.schema.Status),
+      })
+      .check(z.describe('Query parameters for listing funding transfers.'))
+
+    /** Paginated funding transfer list. */
+    export const Response = z
+      .object({
+        data: z.array(Transfer).check(z.describe('Funding transfers on this page, newest first.')),
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(z.describe('Extra response metadata requested with `include`.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of funding transfers.'))
+  }
+
+  /** Schemas for the createFundingTransfer operation. */
+  export namespace createFundingTransfer {
+    /** Funding transfer creation request body. */
+    export const Body = FundingTransfer.schema.CreateRequest
+
+    /** Required headers for funding transfer creation. */
+    export const Headers = z.object({
+      'idempotency-key': z
+        .string()
+        .check(
+          z.minLength(1),
+          z.describe(
+            'Opaque retry key scoped to the API key. Matching requests replay successful responses for 24 hours; changed input conflicts, in-flight requests block, and failed attempts release the key.',
+          ),
+          z.meta({ examples: ['funding_01k1c5j8q8p0be6j5v9m6d1e4r'] }),
+        ),
+    })
+
+    /** The created transfer with its one-time executable action. */
+    export const Response = FundingTransfer.schema.CreatedFundingTransfer
+  }
+
+  const destinationCreateFields = {
+    amount: FundingTransfer.schema.CreateRequest.shape.amount,
+    mode: FundingTransfer.schema.CreateRequest.shape.mode,
+    recipient: FundingTransfer.schema.CreateRequest.shape.recipient,
+    sender: FundingTransfer.schema.CreateRequest.shape.sender,
+    slippageBps: FundingTransfer.schema.CreateRequest.shape.slippageBps,
+    sourceChain: FundingTransfer.schema.CreateRequest.shape.sourceChain,
+    sourceToken: FundingTransfer.schema.CreateRequest.shape.sourceToken,
+  }
+
+  /** Schemas for the createFundingTransferVault operation. */
+  export namespace createFundingTransferVault {
+    /** Funding transfer creation request for an Earn vault destination. */
+    export const Body = z
+      .strictObject({
+        ...destinationCreateFields,
+        vaultAddress: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Tempo Earn vault contract address.'),
+            z.meta({ examples: [`0x${'f4'.repeat(20)}`] }),
+          ),
+      })
+      .check(z.describe('Vault funding transfer creation request.'))
+
+    /** Required headers for vault funding transfer creation. */
+    export const Headers = createFundingTransfer.Headers
+  }
+
+  /** Schemas for the createFundingTransferZone operation. */
+  export namespace createFundingTransferZone {
+    /** Funding transfer creation request for a Zone destination. */
+    export const Body = z
+      .strictObject({
+        amount: destinationCreateFields.amount,
+        destinationChain: z
+          .string()
+          .check(
+            z.regex(/^eip155:\d+$/),
+            z.describe('Configured Zone CAIP-2 id.'),
+            z.meta({ examples: ['eip155:421700001'] }),
+          ),
+        destinationToken: FundingTransfer.schema.CreateRequest.shape.destinationToken,
+        mode: destinationCreateFields.mode,
+        recipient: destinationCreateFields.recipient,
+        recipientFallback: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Public Tempo recipient used if the Zone credit cannot complete.'),
+            z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
+          ),
+        sender: destinationCreateFields.sender,
+        slippageBps: destinationCreateFields.slippageBps,
+        sourceChain: destinationCreateFields.sourceChain,
+        sourceToken: destinationCreateFields.sourceToken,
+      })
+      .check(z.describe('Zone funding transfer creation request.'))
+
+    /** Required headers for Zone funding transfer creation. */
+    export const Headers = createFundingTransfer.Headers
+  }
+
+  /** Schemas for the getFundingTransfer operation. */
+  export namespace getFundingTransfer {
+    /** Path parameters for a funding transfer read. */
+    export const Params = z
+      .object({
+        id: z
+          .string()
+          .check(
+            z.describe('Funding transfer ID (`ftr_…`).'),
+            z.meta({ examples: ['ftr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+      })
+      .check(z.describe('Path parameters for a funding transfer request.'))
+
+    /** The funding transfer resource, returned directly. */
+    export const Response = Transfer
+  }
 }
 
-const fundingQuoteResponseExample = (() => {
-  const [candidate] = FundingQuotes.listQuoteCandidates({
-    provider: 'relay',
-    sourceAmount: '1000000',
-    sourceAmountUnits: 'baseUnits',
-    sourceChain: 'base',
-    sourceToken: 'USDC',
-  })
-  if (!candidate) throw new Error('Missing Relay funding quote example candidate')
-  return {
-    data: [
-      {
-        destinationAmount: Value.tokenAmount({
-          baseUnits: '979295',
-          currency: candidate.destinationToken.currency,
-          decimals: candidate.destinationToken.decimals,
-        }),
-        destinationAmountMin: Value.tokenAmount({
-          baseUnits: '939242',
-          currency: candidate.destinationToken.currency,
-          decimals: candidate.destinationToken.decimals,
-        }),
-        destinationChain: candidate.destinationChain,
-        destinationToken: candidate.destinationToken,
-        id: candidate.id,
-        provider: candidate.provider,
-        quality: {
-          estimatedSeconds: 1,
-          liquiditySource: 'providerQuote',
-          sourceDetail: 'relay:quote-v2',
-          tier: 'liquid',
-        },
-        quote: {
-          sampledAt: '2026-01-01T00:00:00.000Z',
-        },
-        sourceAmount: Value.tokenAmount({
-          baseUnits: candidate.sourceAmount.amount,
-          currency: candidate.sourceToken.currency,
-          decimals: candidate.sourceToken.decimals,
-        }),
-        sourceChain: candidate.sourceChain,
-        sourceToken: candidate.sourceToken,
+const baseChainExample = {
+  addressFormat: 'hex',
+  id: 'eip155:8453',
+  kind: 'evm',
+  name: 'Base',
+} as const
+
+const baseUsdcExample = {
+  address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  currency: 'USD',
+  decimals: 6,
+  name: 'USD Coin',
+  standard: 'ERC-20',
+  symbol: 'USDC',
+  tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+  verified: true,
+} as const
+
+const fundingQuoteResponseExample = {
+  data: [
+    {
+      destinationAmount: Value.tokenAmount({
+        baseUnits: '979295',
+        currency: 'USD',
+        decimals: 6,
+      }),
+      destinationAmountMin: Value.tokenAmount({
+        baseUnits: '939242',
+        currency: 'USD',
+        decimals: 6,
+      }),
+      destinationChain: {
+        addressFormat: 'hex',
+        id: 'eip155:4217',
+        kind: 'evm',
+        name: 'Tempo',
       },
-    ],
-  }
-})() satisfies z.output<typeof schema.quoteFunding.Response>
+      destinationToken: {
+        address: '0x20c000000000000000000000b9537d11c60e8b50',
+        currency: 'USD',
+        decimals: 6,
+        name: 'Bridged USDC (Stargate)',
+        standard: 'TIP-20',
+        symbol: 'USDC.e',
+        tokenKey: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+        verified: true,
+      },
+      id: 'base-usdc-tempo-usdce-relay',
+      provider: { id: 'relay', name: 'Relay' },
+      quality: {
+        estimatedSeconds: 1,
+        liquiditySource: 'providerQuote',
+        sourceDetail: 'relay:quote-v2',
+        tier: 'liquid',
+      },
+      quote: {
+        sampledAt: '2026-01-01T00:00:00.000Z',
+      },
+      sourceAmount: Value.tokenAmount({
+        baseUnits: '1000000',
+        currency: 'USD',
+        decimals: 6,
+      }),
+      sourceChain: baseChainExample,
+      sourceToken: baseUsdcExample,
+    },
+  ],
+} satisfies z.output<typeof schema.quoteFunding.Response>
 
 const fundingChainsResponseExample = {
-  data: FundingQuotes.listChains(),
-} satisfies z.output<typeof schema.listFundingChains.Response>
+  data: [{ ...baseChainExample, tokens: [baseUsdcExample] }],
+} satisfies z.output<typeof schema.getFundingChains.Response>
 
 const providersResponseExample = {
-  data: FundingQuotes.listProviders().map((provider) => ({
-    ...provider,
-    status: 'configured' as const,
-  })),
-} satisfies z.output<typeof schema.listProviders.Response>
+  data: [{ id: 'relay', name: 'Relay' }],
+} satisfies z.output<typeof schema.getFundingProviders.Response>
+
+const tronChainExample = {
+  addressFormat: 'base58check',
+  id: 'tron:0x2b6653dc',
+  kind: 'tron',
+  name: 'Tron',
+} as const
+
+const tronUsdtExample = {
+  address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+  currency: 'USD',
+  decimals: 6,
+  name: 'Tether USD',
+  standard: 'TRC-20',
+  symbol: 'USDT',
+  tokenKey: 'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+  verified: true,
+} as const
+
+const tempoChainExample = {
+  addressFormat: 'hex',
+  id: 'eip155:4217',
+  kind: 'evm',
+  name: 'Tempo',
+} as const
+
+const tempoUsdt0Example = {
+  address: '0x20c00000000000000000000014f22ca97301eb73',
+  currency: 'USD',
+  decimals: 6,
+  name: 'USDT0',
+  standard: 'TIP-20',
+  symbol: 'USDT0',
+  tokenKey: 'eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73',
+  verified: true,
+} as const
+
+const fundingDepositAddressExample = {
+  address: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+  createdAt: '2026-08-04T00:00:00.000Z',
+  destinationChain: tempoChainExample,
+  destinationToken: tempoUsdt0Example,
+  id: 'fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx',
+  provider: { id: 'relay', name: 'Relay' },
+  recipient: `0x${'11'.repeat(20)}`,
+  refundAddress: 'TJRabPrwbZy45sbavfcjinPJC18kjpRTv8',
+  sourceChain: tronChainExample,
+  sourceToken: tronUsdtExample,
+  status: 'active',
+  subsidize: false,
+  updatedAt: '2026-08-04T00:00:00.000Z',
+} satisfies z.output<typeof schema.DepositAddress>
+
+const createdFundingDepositAddressExample = {
+  ...fundingDepositAddressExample,
+  destinationAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+  destinationAmountMin: Value.tokenAmount({
+    baseUnits: '1000000',
+    currency: 'USD',
+    decimals: 6,
+  }),
+  fees: [],
+  quote: { sampledAt: '2026-08-04T00:00:00.000Z' },
+  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+} satisfies z.output<typeof schema.createFundingDepositAddress.Response>
+
+const fundingDepositExample = {
+  createdAt: '2026-08-04T00:01:00.000Z',
+  depositAddressId: fundingDepositAddressExample.id,
+  destinationChain: tempoChainExample,
+  destinationToken: tempoUsdt0Example,
+  id: 'fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx',
+  provider: { id: 'relay', name: 'Relay' },
+  recipient: fundingDepositAddressExample.recipient,
+  refundAddress: fundingDepositAddressExample.refundAddress,
+  sourceChain: tronChainExample,
+  sourceToken: tronUsdtExample,
+  sourceTransactionHashes: ['9f2c4c80dbb468878baa8c07ff523e0464bf6437f2a486268508485d83f14d12'],
+  status: 'detected',
+  updatedAt: '2026-08-04T00:01:00.000Z',
+} satisfies z.output<typeof schema.Deposit>
+
+const fundingDepositAddressDepositsExample = {
+  data: [fundingDepositExample],
+  nextCursor: null,
+} satisfies z.output<typeof schema.listFundingDepositAddressDeposits.Response>
+
+const fundingTransferExample = {
+  createdAt: '2026-01-01T00:00:00.000Z',
+  destinationAmount: Value.tokenAmount({ baseUnits: '979295', currency: 'USD', decimals: 6 }),
+  destinationAmountMin: Value.tokenAmount({ baseUnits: '939242', currency: 'USD', decimals: 6 }),
+  destinationChain: {
+    addressFormat: 'hex',
+    id: 'eip155:4217',
+    kind: 'evm',
+    name: 'Tempo',
+  },
+  destinationToken: {
+    address: '0x20c0000000000000000000000000000000000000',
+    currency: 'USD',
+    decimals: 6,
+    name: 'PathUSD',
+    standard: 'TIP-20',
+    symbol: 'pathUSD',
+    tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+    verified: true,
+  },
+  fees: [
+    {
+      amount: Value.tokenAmount({ baseUnits: '20705', currency: 'USD', decimals: 6 }),
+      side: 'source',
+      token: baseUsdcExample,
+      type: 'provider',
+    },
+  ],
+  id: 'ftr_001767225600000_2ZPE2gvateYEQ0dQslgvkhjx',
+  method: 'transaction',
+  mode: 'exactSource',
+  provider: { id: 'relay', name: 'Relay' },
+  quote: {
+    expiresAt: '2026-01-01T00:01:00.000Z',
+    sampledAt: '2026-01-01T00:00:00.000Z',
+  },
+  recipient: `0x${'11'.repeat(20)}`,
+  sender: `0x${'22'.repeat(20)}`,
+  sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+  sourceChain: baseChainExample,
+  sourceToken: baseUsdcExample,
+  status: 'awaiting-source',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+  version: 1,
+} satisfies z.output<typeof schema.Transfer>
+
+const listFundingTransfersResponseExample = {
+  data: [fundingTransferExample],
+  nextCursor: null,
+} satisfies z.output<typeof schema.listFundingTransfers.Response>
+
+const createdFundingTransferExample = {
+  action: {
+    calls: [
+      {
+        data: `0x095ea7b3000000000000000000000000${'44'.repeat(20)}00000000000000000000000000000000000000000000000000000000000f4240`,
+        to: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        value: '0x0',
+      },
+      {
+        data: '0xe8017952',
+        to: `0x${'44'.repeat(20)}`,
+        value: '0x0',
+      },
+    ],
+    type: 'evm:calls',
+  },
+  ...fundingTransferExample,
+} satisfies z.output<typeof schema.createFundingTransfer.Response>
+
+const unimplementedFundingTransferResponses = (() => {
+  const responses = OpenApi.responses({
+    errors: {
+      400: { codes: ['body_invalid', 'idempotency_key_required'] },
+      501: {
+        codes: ['not_implemented'],
+        description: 'This funding transfer destination is not implemented.',
+      },
+    },
+    success: {
+      description: 'Unused until this destination is implemented.',
+      schema: z.never(),
+    },
+  })
+  const { 200: success, 502: upstream, ...errors } = responses
+  void success
+  void upstream
+  return errors
+})()
+
+// Replay the exact successful creation response for 24 hours.
+const idempotencyReplayTtlMs = 86_400_000
+// Pending claims only cover the bounded provider preparation window.
+const idempotencyPendingTtlMs = 60_000
+
+const depositAddressCheckpoint = Schema.describe(
+  z.object({
+    candidate: Schema.describe(
+      z.object({
+        destinationChain: FundingProvider.schema.ChainRef,
+        destinationToken: FundingProvider.schema.TokenRef,
+        sourceChain: FundingProvider.schema.ChainRef,
+        sourceToken: FundingProvider.schema.TokenRef,
+      }),
+      'Normalized route retained after provider provisioning.',
+    ),
+    provider: FundingProvider.schema.ProviderRef,
+    recipient: z.string().check(z.describe('Normalized Tempo recipient.')),
+    refundAddress: z.string().check(z.describe('Normalized source-chain refund account.')),
+    result: FundingProvider.schema.DepositAddressResult,
+  }),
+  'Provider result retained until deposit address creation completes.',
+)
+
+const inventorySourceScopes = new WeakMap<Db.Source, number>()
+let nextInventorySourceScope = 0
+const fundingEtag = etag()
+
+function inventorySourceScope(source: Db.Source) {
+  const current = inventorySourceScopes.get(source)
+  if (current !== undefined) return current
+  // A production isolate's source is consistently zero, while multi-app runtimes receive distinct scopes.
+  const scope = nextInventorySourceScope++
+  inventorySourceScopes.set(source, scope)
+  return scope
+}
 
 /** Mounts live funding quotes and their supporting inventory endpoints. */
-export function funding(options: funding.Options = {}) {
+export function funding() {
+  const inventoryKey = (c: Context<App.Environment>) => {
+    const url = new URL(c.req.url)
+    const providers = c
+      .get('providers')
+      .filter(FundingProvider.is)
+      .map((provider) => provider.id)
+      .sort()
+    url.searchParams.set('__tempo_database', String(inventorySourceScope(c.get('dbCached'))))
+    url.searchParams.set('__tempo_providers', providers.join(','))
+    return url.toString()
+  }
+
   return new Hono<App.Environment>()
+    .post('/webhooks/funding/:providerId', async (c) => {
+      const provider = c
+        .get('providers')
+        .filter(FundingProvider.is)
+        .find((candidate) => candidate.id === c.req.param('providerId'))
+      if (!provider || !FundingProvider.canReceiveWebhook(provider)) return c.body(null, 404)
+      try {
+        await provider.webhook.receive({
+          body: await c.req.text(),
+          headers: c.req.raw.headers,
+        })
+        return c.body(null, 204)
+      } catch (cause) {
+        if (cause instanceof FundingProvider.WebhookAuthenticationError) return c.body(null, 401)
+        if (cause instanceof FundingProvider.WebhookPayloadError) return c.body(null, 400)
+        throw cause
+      }
+    })
     .get(
       '/v1/funding/quotes',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -412,8 +700,7 @@ export function funding(options: funding.Options = {}) {
         message: 'Invalid query parameters',
       }),
       OpenApi.describeRoute({
-        description:
-          'Returns live quotes for funding Tempo with a stablecoin. Omit `provider` to query all configured providers. Provider minimums can use provider-specific slippage policies; Symbiosis and Squid use 1%. This endpoint does not execute a transfer.',
+        description: 'Returns live quotes for transferring stablecoins to Tempo.',
         operationId: 'quoteFunding',
         responses: OpenApi.responses({
           errors: {
@@ -430,7 +717,7 @@ export function funding(options: funding.Options = {}) {
             schema: schema.quoteFunding.Response,
           },
         }),
-        summary: 'Get funding quotes',
+        summary: 'Get quotes',
         tags: ['Funding'],
       }),
       async (c) => {
@@ -442,34 +729,38 @@ export function funding(options: funding.Options = {}) {
           })
 
         const query = c.req.valid('query')
-        const attempts: FundingQuotes.ProviderAttempt[] = []
+        const attempts: FundingProvider.ProviderAttempt[] = []
+        const catalog = await FundingCatalog.snapshot(c)
+        const providers = c.get('providers').filter(FundingProvider.is)
         try {
           c.header('Cache-Control', 'no-store')
+          const data = await FundingProvider.getQuotes({
+            cache: { bypass: cacheBypass(c.req.raw) },
+            catalog,
+            destinationToken: query.destinationToken,
+            onAttempt: (attempt) => attempts.push(attempt),
+            provider: query.provider,
+            providers,
+            sourceAmount: query.sourceAmount,
+            sourceAmountUnits: query.sourceAmountUnits,
+            sourceChain: query.sourceChain,
+            sourceToken: query.sourceToken,
+          })
+          if (attempts.length > 0) c.set('fundingProviderAttempts', attempts.map(formatAttempt))
           return c.json(
             Response.validated(schema.quoteFunding.Response, {
-              data: await FundingQuotes.listQuotes({
-                adapters: options.adapters,
-                adapterTimeoutMs: options.adapterTimeoutMs,
-                cache: { bypass: cacheBypass(c.req.raw) },
-                destinationToken: query.destinationToken,
-                onAttempt: (attempt) => attempts.push(attempt),
-                provider: query.provider,
-                sourceAmount: query.sourceAmount,
-                sourceAmountUnits: query.sourceAmountUnits,
-                sourceChain: query.sourceChain,
-                sourceToken: query.sourceToken,
-              }),
+              data,
             }),
             200,
           )
         } catch (cause) {
           const message = requestErrorMessage(cause)
           if (message) return Response.error(c, { code: 'query_invalid', message, status: 400 })
-          if (cause instanceof FundingQuotes.ProviderQuoteError) {
-            const failures = cause.failures.map(FundingQuoteProviders.providerFailure)
-            const failure = failures[0]
-            if (failure) c.set('providerFailure', failure)
-            if (failures.length > 1) c.set('providerFailures', failures)
+          if (cause instanceof FundingProvider.ProviderQuoteError) {
+            if (cause.fundingProviderAttempts.length > 0)
+              c.set('fundingProviderAttempts', cause.fundingProviderAttempts)
+            if (cause.providerFailure) c.set('providerFailure', cause.providerFailure)
+            if (cause.providerFailures) c.set('providerFailures', cause.providerFailures)
             return Response.error(c, {
               code: 'upstream_error',
               message: 'Quote providers could not complete the request.',
@@ -477,9 +768,6 @@ export function funding(options: funding.Options = {}) {
             })
           }
           throw cause
-        } finally {
-          if (attempts.length > 0)
-            c.set('fundingProviderAttempts', attempts.map(fundingProviderAttempt))
         }
       },
     )
@@ -487,29 +775,30 @@ export function funding(options: funding.Options = {}) {
       '/v1/funding/chains',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.describeRoute({
-        description:
-          'Lists the source chains and stablecoins you can use when requesting a funding quote.',
-        operationId: 'listFundingChains',
+        description: 'Lists supported source chains and tokens.',
+        operationId: 'getFundingChains',
         responses: OpenApi.responses({
           success: {
             description: 'Supported source chains and stablecoins.',
             example: fundingChainsResponseExample,
-            schema: schema.listFundingChains.Response,
+            schema: schema.getFundingChains.Response,
           },
         }),
-        summary: 'List funding chains',
+        summary: 'Get chains',
         tags: ['Funding'],
       }),
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.stable,
-        name: 'tempo-api:funding-chains:v2',
-        key: (c) => c.req.url,
+        key: inventoryKey,
+        name: 'tempo-api:funding-chains:v5',
       }),
-      (c) => {
+      async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        const catalog = await FundingCatalog.snapshot(c)
+        const providers = c.get('providers').filter(FundingProvider.is)
         return c.json(
-          Response.validated(schema.listFundingChains.Response, {
-            data: FundingQuotes.listChains(),
+          Response.validated(schema.getFundingChains.Response, {
+            data: FundingProvider.getChains({ catalog, providers }),
           }),
           200,
         )
@@ -519,77 +808,1001 @@ export function funding(options: funding.Options = {}) {
       '/v1/funding/providers',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
       OpenApi.describeRoute({
-        description:
-          'Lists funding quote providers and whether live quoting is configured for this deployment.',
-        operationId: 'listFundingProviders',
+        description: 'Lists available transfer providers.',
+        operationId: 'getFundingProviders',
         responses: OpenApi.responses({
           success: {
             description: 'Funding quote providers supported by Tempo.',
             example: providersResponseExample,
-            schema: schema.listProviders.Response,
+            schema: schema.getFundingProviders.Response,
           },
         }),
-        summary: 'List funding providers',
+        summary: 'Get providers',
         tags: ['Funding'],
       }),
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.stable,
-        name: 'tempo-api:funding-providers:v1',
-        key: (c) => c.req.url,
+        key: inventoryKey,
+        name: 'tempo-api:funding-providers:v4',
       }),
-      (c) => {
+      async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        const catalog = await FundingCatalog.snapshot(c)
+        const providers = c.get('providers').filter(FundingProvider.is)
         return c.json(
-          Response.validated(schema.listProviders.Response, {
-            data: FundingQuotes.listProviders({ adapters: options.adapters }),
+          Response.validated(schema.getFundingProviders.Response, {
+            data: FundingProvider.getProviders({ catalog, providers }),
           }),
           200,
         )
       },
     )
+    .post(
+      '/v1/funding/deposit-addresses',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingDepositAddress.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding deposit address creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingDepositAddress.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates or returns a reusable deposit address for funding a Tempo account.',
+        operationId: 'createFundingDepositAddress',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            404: {
+              codes: ['deposit_address_not_available'],
+              description: 'No provider can provision the requested reusable address route.',
+            },
+            409: {
+              codes: ['idempotency_conflict', 'idempotency_in_progress'],
+              description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'The selected provider could not provision the address.',
+            },
+          },
+          success: {
+            description: 'The created or matching reusable funding deposit address and quote.',
+            example: createdFundingDepositAddressExample,
+            schema: schema.createFundingDepositAddress.Response,
+          },
+        }),
+        summary: 'Create deposit address',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const principal = Auth.getPrincipal(c)
+        const owner = fundingOwner(c)
+        if (!owner || principal?.type !== 'api_key') return fundingUnauthorized(c)
+        c.header('Cache-Control', 'no-store')
+
+        const body = c.req.valid('json')
+        const subsidize = body.subsidize ?? false
+        const db = Db.get(c.get('db'))
+        const identity = {
+          apiKeyId: principal.id,
+          keyHash: Idempotency.inputHash(c.req.valid('header')['idempotency-key']),
+          requestHash: Idempotency.inputHash({
+            body,
+            endpoint: 'POST /v1/funding/deposit-addresses',
+          }),
+        }
+        const claim = await FundingIdempotency.claim(db, {
+          ...identity,
+          ttlMs: idempotencyPendingTtlMs,
+        })
+        if (claim.type === 'mismatch')
+          return Response.error(c, {
+            code: 'idempotency_conflict',
+            message: 'This Idempotency-Key was already used with different input.',
+            status: 409,
+          })
+        if (claim.type === 'pending')
+          return Response.error(c, {
+            code: 'idempotency_in_progress',
+            message: 'An equivalent funding deposit address creation is still running.',
+            status: 409,
+          })
+        if (claim.type === 'replay') {
+          const response = JSON.parse(claim.response) as Record<string, unknown>
+          return c.json(
+            Response.validated(schema.createFundingDepositAddress.Response, {
+              ...response,
+              subsidize: response['subsidize'] ?? false,
+            }),
+            200,
+          )
+        }
+
+        const release = async () => {
+          try {
+            await FundingIdempotency.release(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+            })
+          } catch {
+            // The pending claim expires on its own; the response stays authoritative.
+          }
+        }
+        const complete = async (
+          database: Db.Db,
+          response: z.output<typeof schema.createFundingDepositAddress.Response>,
+        ) => {
+          const validated = Response.validated(
+            schema.createFundingDepositAddress.Response,
+            response,
+          )
+          const completion = await FundingIdempotency.complete(database, {
+            apiKeyId: identity.apiKeyId,
+            createdAt: claim.createdAt,
+            keyHash: identity.keyHash,
+            replayTtlMs: idempotencyReplayTtlMs,
+            response: JSON.stringify(validated),
+          })
+          if (!completion)
+            throw new IdempotencyLeaseLostError('Funding deposit address creation lease was lost.')
+          return validated
+        }
+
+        const attempts: FundingProvider.ProviderAttempt[] = []
+        const provisioning = { succeeded: claim.type === 'resume' }
+        try {
+          const selected = await (async () => {
+            if (claim.type === 'resume')
+              return depositAddressCheckpoint.parse(JSON.parse(claim.response))
+            const catalog = await FundingCatalog.snapshot(c)
+            const providers = c.get('providers').filter(FundingProvider.is)
+            const provisioned = await FundingProvider.createDepositAddress({
+              amount: body.amount,
+              catalog,
+              destinationChainId: c.get('chainId'),
+              destinationToken: body.destinationToken,
+              onAttempt: (attempt) => attempts.push(attempt),
+              providers,
+              recipient: body.recipient,
+              refundAddress: body.refundAddress,
+              sourceChain: body.sourceChain,
+              sourceToken: body.sourceToken,
+              subsidize,
+            })
+            if (!provisioned) return undefined
+            provisioning.succeeded = true
+            const checkpoint = depositAddressCheckpoint.parse({
+              candidate: provisioned.candidate,
+              provider: provisioned.provider,
+              recipient: provisioned.recipient,
+              refundAddress: provisioned.refundAddress,
+              result: provisioned.result,
+            })
+            const stored = await FundingIdempotency.checkpoint(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+              replayTtlMs: idempotencyReplayTtlMs,
+              response: JSON.stringify(checkpoint),
+            })
+            if (!stored)
+              throw new IdempotencyLeaseLostError(
+                'Funding deposit address creation lease was lost.',
+              )
+            return checkpoint
+          })()
+          if (attempts.length > 0) c.set('fundingProviderAttempts', attempts.map(formatAttempt))
+          if (!selected) {
+            await release()
+            return depositAddressNotAvailable(c)
+          }
+
+          const {
+            candidate: selectedCandidate,
+            provider,
+            recipient,
+            refundAddress,
+            result,
+          } = selected
+          const feeToken = (side: 'destination' | 'source') =>
+            side === 'source' ? selectedCandidate.sourceToken : selectedCandidate.destinationToken
+          const created = await db.transaction(async (tx) => {
+            const stored = await FundingDepositAddress.createOrGet(tx, {
+              apiKeyId: principal.id,
+              deliveryStrategy: 'provider',
+              environment: owner.environment,
+              orgId: owner.orgId,
+              ...(owner.projectId === undefined ? {} : { projectId: owner.projectId }),
+              providerOutputToken: selectedCandidate.destinationToken,
+              providerRequestIds: [result.correlation.requestId],
+              providerState:
+                result.correlation.checkEndpoint === undefined
+                  ? undefined
+                  : { checkEndpoint: result.correlation.checkEndpoint },
+              snapshot: {
+                address: result.address,
+                destinationChain: selectedCandidate.destinationChain,
+                destinationToken: selectedCandidate.destinationToken,
+                provider,
+                recipient,
+                refundAddress,
+                sourceChain: selectedCandidate.sourceChain,
+                sourceToken: selectedCandidate.sourceToken,
+                subsidize,
+              },
+            })
+            const record = FundingDepositAddress.toPublic(stored.record)
+            if (stored.type === 'existing') return complete(tx, record)
+            return complete(tx, {
+              ...record,
+              destinationAmount: Value.tokenAmount({
+                baseUnits: result.destinationAmount,
+                currency: selectedCandidate.destinationToken.currency,
+                decimals: selectedCandidate.destinationToken.decimals,
+              }),
+              destinationAmountMin: Value.tokenAmount({
+                baseUnits: result.destinationAmountMin,
+                currency: selectedCandidate.destinationToken.currency,
+                decimals: selectedCandidate.destinationToken.decimals,
+              }),
+              fees: result.fees.map((fee) => ({
+                amount: Value.tokenAmount({
+                  baseUnits: fee.amount,
+                  currency: feeToken(fee.side).currency,
+                  decimals: feeToken(fee.side).decimals,
+                }),
+                side: fee.side,
+                token: feeToken(fee.side),
+                type: 'provider',
+              })),
+              quote: {
+                ...(result.expiresAt === undefined ? {} : { expiresAt: result.expiresAt }),
+                sampledAt: result.sampledAt,
+              },
+              sourceAmount: Value.tokenAmount({
+                baseUnits: body.amount,
+                currency: selectedCandidate.sourceToken.currency,
+                decimals: selectedCandidate.sourceToken.decimals,
+              }),
+            })
+          })
+          return c.json(created, 200)
+        } catch (cause) {
+          if (!provisioning.succeeded) await release()
+          if (cause instanceof FundingProvider.InvalidRefundAddressError)
+            return Response.error(c, {
+              code: 'body_invalid',
+              message: 'Invalid `refundAddress`.',
+              status: 400,
+            })
+          if (cause instanceof FundingProvider.UnsupportedSourceChainError)
+            return depositAddressNotAvailable(c)
+          if (
+            cause instanceof FundingDepositAddress.ConflictError ||
+            cause instanceof FundingProvider.ProviderQuoteError
+          ) {
+            if (cause instanceof FundingDepositAddress.ConflictError)
+              return Response.error(c, {
+                code: 'upstream_error',
+                message: 'The funding provider returned a conflicting deposit address.',
+                status: 502,
+              })
+            if (cause.fundingProviderAttempts.length > 0)
+              c.set('fundingProviderAttempts', cause.fundingProviderAttempts)
+            if (cause.providerFailure) c.set('providerFailure', cause.providerFailure)
+            if (cause.providerFailures) c.set('providerFailures', cause.providerFailures)
+            return Response.error(c, {
+              code: 'upstream_error',
+              message: 'The funding provider could not provision the deposit address.',
+              status: 502,
+            })
+          }
+          throw cause
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposit-addresses/:id{fda_[A-Za-z0-9_-]+}/deposits',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.listFundingDepositAddressDeposits.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.listFundingDepositAddressDeposits.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists deposits detected for one funding deposit address, newest first.',
+        operationId: 'listFundingDepositAddressDeposits',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid', 'query_invalid'] },
+            404: {
+              codes: ['funding_deposit_address_not_found'],
+              description: 'No visible funding deposit address exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'A page of deposits detected for the address.',
+            example: fundingDepositAddressDepositsExample,
+            schema: schema.listFundingDepositAddressDeposits.Response,
+          },
+        }),
+        summary: 'List deposits',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the request parameters and try again.',
+          })
+
+        const owner = fundingOwner(c)
+        if (!owner) return fundingUnauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        const { cursor, limit } = c.req.valid('query')
+        const decoded = cursor ? Cursor.decode(cursor, ['timestamp', 'id']) : undefined
+        try {
+          const address = await FundingDepositAddresses.getOwned(db, owner, id)
+          if (!address)
+            return Response.error(c, {
+              code: 'funding_deposit_address_not_found',
+              message: 'Funding deposit address not found',
+              status: 404,
+            })
+
+          const rows = await FundingDeposits.listByAddress(db, owner, id, {
+            ...(decoded
+              ? { cursor: { createdAt: String(decoded[0]), id: String(decoded[1]) } }
+              : {}),
+            limit: limit + 1,
+          })
+          const page = Cursor.paginate({
+            key: (record) => [record.createdAt, record.id],
+            limit,
+            rows,
+          })
+          const data = page.rows.map(FundingDeposit.toPublic)
+
+          c.header('Cache-Control', Cache.policies.noStore)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+          return c.json(
+            Response.validated(schema.listFundingDepositAddressDeposits.Response, {
+              data,
+              nextCursor: page.nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposit-addresses/:id{fda_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingDepositAddress.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns one reusable funding deposit address.',
+        operationId: 'getFundingDepositAddress',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_deposit_address_not_found'],
+              description: 'No visible funding deposit address exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding deposit address.',
+            example: fundingDepositAddressExample,
+            schema: schema.getFundingDepositAddress.Response,
+          },
+        }),
+        summary: 'Get deposit address',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = fundingOwner(c)
+        if (!owner) return fundingUnauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          const record = await FundingDepositAddresses.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_deposit_address_not_found',
+              message: 'Funding deposit address not found',
+              status: 404,
+            })
+
+          c.header('Cache-Control', Cache.policies.noStore)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+          return c.json(
+            Response.validated(
+              schema.getFundingDepositAddress.Response,
+              FundingDepositAddress.toPublic(record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/deposits/:id{fdp_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingDeposit.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns one detected deposit and its delivery status.',
+        operationId: 'getFundingDeposit',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_deposit_not_found'],
+              description: 'No visible funding deposit exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding deposit.',
+            example: fundingDepositExample,
+            schema: schema.getFundingDeposit.Response,
+          },
+        }),
+        summary: 'Get deposit',
+        tags: ['Funding'],
+      }),
+      fundingEtag,
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = fundingOwner(c)
+        if (!owner) return fundingUnauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          const record = await FundingDeposits.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_deposit_not_found',
+              message: 'Funding deposit not found',
+              status: 404,
+            })
+
+          c.header('Cache-Control', Cache.policies.state)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+          return c.json(
+            Response.validated(schema.getFundingDeposit.Response, FundingDeposit.toPublic(record)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/transfers',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('query', schema.listFundingTransfers.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists transfers from newest to oldest.',
+        operationId: 'listFundingTransfers',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['query_invalid'] },
+          },
+          success: {
+            description: 'A page of funding transfers.',
+            example: listFundingTransfersResponseExample,
+            schema: schema.listFundingTransfers.Response,
+          },
+        }),
+        summary: 'List transfers',
+        tags: ['Funding'],
+      }),
+      fundingEtag,
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const owner = fundingOwner(c)
+        if (!owner) return fundingUnauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { cursor, include, limit, status } = c.req.valid('query')
+        try {
+          // `totalCount` is opt-in and capped (a capped subquery shares the
+          // list filter); run it concurrently with the page list. Best-effort:
+          // a failure omits `meta` rather than failing the page.
+          const countPromise = include.includes('totalCount')
+            ? FundingTransfers.count(db, owner, { cap: Schema.countCap, status }).catch(() => {
+                c.set('fundingTransferCountFailed', true)
+                return undefined
+              })
+            : undefined
+
+          // Fetch one extra to detect a further page without a second round-trip.
+          const rows = await FundingTransfers.list(db, owner, { cursor, limit: limit + 1, status })
+          const hasMore = rows.length > limit
+          const data = (hasMore ? rows.slice(0, limit) : rows).map(FundingTransfer.toPublic)
+          const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null
+
+          const count = countPromise ? await countPromise : undefined
+
+          c.header('Cache-Control', Cache.policies.feed)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+
+          return c.json(
+            Response.validated(schema.listFundingTransfers.Response, {
+              data,
+              ...(count !== undefined
+                ? {
+                    meta: {
+                      totalCountCapped: count > Schema.countCap,
+                      totalCount: Math.min(count, Schema.countCap),
+                    },
+                  }
+                : {}),
+              nextCursor,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/funding/transfers/:id{ftr_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['funding:read'] } }),
+      OpenApi.validate('param', schema.getFundingTransfer.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Returns a transfer by ID.',
+        operationId: 'getFundingTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['param_invalid'] },
+            404: {
+              codes: ['funding_transfer_not_found'],
+              description: 'No visible funding transfer exists for the identifier.',
+            },
+          },
+          success: {
+            description: 'The requested funding transfer.',
+            example: fundingTransferExample,
+            schema: schema.getFundingTransfer.Response,
+          },
+        }),
+        summary: 'Get transfer',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const owner = fundingOwner(c)
+        if (!owner) return fundingUnauthorized(c)
+
+        const db = Db.get(c.get('db'))
+        const { id } = c.req.valid('param')
+        try {
+          // Ownership filters in SQL, so absent and foreign rows are the same 404.
+          const record = await FundingTransfers.getOwned(db, owner, id)
+          if (!record)
+            return Response.error(c, {
+              code: 'funding_transfer_not_found',
+              message: 'Funding transfer not found',
+              status: 404,
+            })
+          c.header('Cache-Control', Cache.policies.noStore)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key')
+          return c.json(
+            Response.validated(
+              schema.getFundingTransfer.Response,
+              FundingTransfer.toPublic(record),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/funding/transfers',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransfer.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransfer.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer to a Tempo account.',
+        operationId: 'createFundingTransfer',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            404: {
+              codes: ['quote_not_available'],
+              description: 'No provider can prepare the requested route.',
+            },
+            409: {
+              codes: ['idempotency_conflict', 'idempotency_in_progress'],
+              description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
+            },
+            502: {
+              codes: ['upstream_error'],
+              description: 'No provider succeeded and at least one failed unexpectedly.',
+            },
+          },
+          success: {
+            description: 'The created funding transfer with its one-time executable action.',
+            example: createdFundingTransferExample,
+            schema: schema.createFundingTransfer.Response,
+          },
+        }),
+        summary: 'Create transfer',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const principal = Auth.getPrincipal(c)
+        const owner = fundingOwner(c)
+        if (!owner || principal?.type !== 'api_key') return fundingUnauthorized(c)
+        c.header('Cache-Control', 'no-store')
+
+        const idempotencyKey = c.req.valid('header')['idempotency-key']
+
+        const body = c.req.valid('json')
+        const db = Db.get(c.get('db'))
+        const identity = {
+          apiKeyId: principal.id,
+          keyHash: Idempotency.inputHash(idempotencyKey),
+          requestHash: Idempotency.inputHash(body),
+        }
+        const claim = await FundingIdempotency.claim(db, {
+          ...identity,
+          ttlMs: idempotencyPendingTtlMs,
+        })
+        if (claim.type === 'mismatch')
+          return Response.error(c, {
+            code: 'idempotency_conflict',
+            message: 'This Idempotency-Key was already used with different input.',
+            status: 409,
+          })
+        if (claim.type === 'pending')
+          return Response.error(c, {
+            code: 'idempotency_in_progress',
+            message: 'An equivalent funding transfer creation is still running.',
+            status: 409,
+          })
+        if (claim.type === 'replay')
+          return c.json(
+            JSON.parse(claim.response) as z.output<typeof schema.createFundingTransfer.Response>,
+            200,
+          )
+
+        const release = async () => {
+          try {
+            await FundingIdempotency.release(db, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+            })
+          } catch {
+            // The pending claim expires on its own; the response stays authoritative.
+          }
+        }
+        try {
+          const attempts: FundingProvider.ProviderAttempt[] = []
+          const catalog = await FundingCatalog.snapshot(c)
+          const providers = c.get('providers').filter(FundingProvider.is)
+          const selected = await FundingProvider.prepareTransfer({
+            catalog,
+            destinationChainId: c.get('chainId'),
+            destinationToken: body.destinationToken,
+            method: 'transaction',
+            mode: body.mode,
+            onAttempt: (attempt) => attempts.push(attempt),
+            providers,
+            recipient: body.recipient,
+            sender: body.sender,
+            slippageBps: body.slippageBps,
+            sourceAmount: body.amount,
+            sourceChain: body.sourceChain,
+            sourceToken: body.sourceToken,
+          })
+          if (attempts.length > 0) c.set('fundingProviderAttempts', attempts.map(formatAttempt))
+          if (!selected) {
+            await release()
+            return quoteNotAvailable(c)
+          }
+
+          const { candidate, result } = selected
+          const feeToken = (side: 'destination' | 'source') =>
+            side === 'source' ? candidate.sourceToken : candidate.destinationToken
+          const snapshot: FundingTransfer.Snapshot = {
+            destinationAmount: Value.tokenAmount({
+              baseUnits: result.destinationAmount,
+              currency: candidate.destinationToken.currency,
+              decimals: candidate.destinationToken.decimals,
+            }),
+            destinationAmountMin: Value.tokenAmount({
+              baseUnits: result.destinationAmountMin,
+              currency: candidate.destinationToken.currency,
+              decimals: candidate.destinationToken.decimals,
+            }),
+            destinationChain: candidate.destinationChain,
+            destinationToken: candidate.destinationToken,
+            fees: result.fees.map((fee) => ({
+              amount: Value.tokenAmount({
+                baseUnits: fee.amount,
+                currency: feeToken(fee.side).currency,
+                decimals: feeToken(fee.side).decimals,
+              }),
+              side: fee.side,
+              token: feeToken(fee.side),
+              type: 'provider',
+            })),
+            method: 'transaction',
+            mode: body.mode,
+            provider: candidate.provider,
+            quote: { expiresAt: result.expiresAt, sampledAt: result.sampledAt },
+            recipient: body.recipient,
+            sender: body.sender,
+            sourceAmount: Value.tokenAmount({
+              baseUnits: candidate.sourceAmount.amount,
+              currency: candidate.sourceToken.currency,
+              decimals: candidate.sourceToken.decimals,
+            }),
+            sourceChain: candidate.sourceChain,
+            sourceToken: candidate.sourceToken,
+          }
+
+          // The transfer row, its version-1 event, and the replay body commit
+          // atomically so a crash cannot leave a claimed key without a replay.
+          const created = await db.transaction(async (tx) => {
+            const record = await FundingTransfer.createIn(tx, {
+              apiKeyId: principal.id,
+              environment: owner.environment,
+              orgId: owner.orgId,
+              projectId: owner.projectId,
+              providerState: result.correlation,
+              snapshot,
+            })
+            const validated = Response.validated(
+              schema.createFundingTransfer.Response,
+              FundingTransfer.toCreated(record, result.action),
+            )
+            const completion = await FundingIdempotency.complete(tx, {
+              apiKeyId: identity.apiKeyId,
+              createdAt: claim.createdAt,
+              keyHash: identity.keyHash,
+              replayTtlMs: idempotencyReplayTtlMs,
+              response: JSON.stringify(validated),
+              transferId: record.id,
+            })
+            if (!completion)
+              throw new IdempotencyLeaseLostError('Funding transfer creation lease was lost.')
+            return validated
+          })
+          return c.json(created, 200)
+        } catch (cause) {
+          await release()
+          if (cause instanceof FundingProvider.InvalidAmountError)
+            return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }) // prettier-ignore
+          if (cause instanceof FundingProvider.UnsupportedSourceChainError)
+            return quoteNotAvailable(c)
+          if (cause instanceof FundingProvider.ProviderQuoteError) {
+            if (cause.fundingProviderAttempts.length > 0)
+              c.set('fundingProviderAttempts', cause.fundingProviderAttempts)
+            if (cause.providerFailure) c.set('providerFailure', cause.providerFailure)
+            if (cause.providerFailures) c.set('providerFailures', cause.providerFailures)
+            return Response.error(c, {
+              code: 'upstream_error',
+              message: 'No funding provider could prepare the transfer.',
+              status: 502,
+            })
+          }
+          throw cause
+        }
+      },
+    )
+    .post(
+      '/v1/funding/transfers/vault',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransferVault.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransferVault.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Earn vault.',
+        operationId: 'createFundingTransferVault',
+        responses: unimplementedFundingTransferResponses,
+        summary: 'Create transfer into vault',
+        tags: ['Funding'],
+      }),
+      (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        c.header('Cache-Control', 'no-store')
+        return Response.error(c, {
+          code: 'not_implemented',
+          message: 'Vault funding transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+    .post(
+      '/v1/funding/transfers/zone',
+      Auth.policy({ apiKey: { scopes: ['funding:write'] } }),
+      OpenApi.validate('header', schema.createFundingTransferZone.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Funding transfer creation requires an `Idempotency-Key` header.',
+      }),
+      OpenApi.validate('json', schema.createFundingTransferZone.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Zone.',
+        operationId: 'createFundingTransferZone',
+        responses: unimplementedFundingTransferResponses,
+        summary: 'Create transfer into zone',
+        tags: ['Funding'],
+      }),
+      (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        c.header('Cache-Control', 'no-store')
+        return Response.error(c, {
+          code: 'not_implemented',
+          message: 'Zone funding transfers are not implemented.',
+          status: 501,
+        })
+      },
+    )
+}
+
+function quoteNotAvailable(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'quote_not_available',
+    message: 'No provider can prepare the requested funding route.',
+    status: 404,
+  })
 }
 
-export declare namespace funding {
-  /** Options for live funding quotes. */
-  type Options = {
-    /** Provider adapters used to request live quotes. */
-    adapters?: FundingQuotes.ProviderAdapters | undefined
-    /** Per-provider quote timeout in milliseconds. */
-    adapterTimeoutMs?: number | undefined
+function depositAddressNotAvailable(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'deposit_address_not_available',
+    message: 'No provider can provision the requested reusable deposit address.',
+    status: 404,
+  })
+}
+
+/** Ownership filter from the API-key principal; other principals get no funding access. */
+function fundingOwner(c: Context<App.Environment>): FundingTransfers.Owner | null {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'api_key') return null
+  return {
+    environment: principal.environment,
+    orgId: principal.orgId,
+    projectId: principal.projectId,
   }
 }
 
-function fundingProviderAttempt(
-  attempt: FundingQuotes.ProviderAttempt,
-): Log.FundingProviderAttempt {
-  const operation = FundingQuoteProviders.providerOperation(attempt.provider)
+function fundingUnauthorized(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'unauthorized',
+    message: 'Tempo could not determine which organization owns this funding resource.',
+    status: 401,
+  })
+}
+
+function formatAttempt(attempt: FundingProvider.ProviderAttempt): Log.FundingProviderAttempt {
+  const { id } = attempt.provider
   if (attempt.outcome !== 'failed')
     return {
       durationMs: attempt.durationMs,
-      id: attempt.provider,
-      operation,
+      id,
+      operation: attempt.operation,
       outcome: attempt.outcome,
     }
 
   return {
     durationMs: attempt.durationMs,
-    failure: FundingQuoteProviders.providerFailure({
+    failure: FundingProvider.failure({
       cause: attempt.cause,
+      operation: attempt.operation,
       provider: attempt.provider,
     }).failure,
-    id: attempt.provider,
-    operation,
+    id,
+    operation: attempt.operation,
     outcome: attempt.outcome,
   }
 }
 
 // Maps caller-input errors to a specific 400 message; anything else rethrows.
 function requestErrorMessage(cause: unknown) {
-  if (cause instanceof FundingQuotes.InvalidAmountError) return 'Invalid `sourceAmount`.'
-  if (cause instanceof FundingQuotes.UnsupportedDestinationTokenError)
+  if (cause instanceof FundingProvider.InvalidAmountError) return 'Invalid `sourceAmount`.'
+  if (cause instanceof FundingProvider.UnsupportedDestinationTokenError)
     return 'Unsupported `destinationToken`.'
-  if (cause instanceof FundingQuotes.UnsupportedProviderError) return 'Unsupported `provider`.'
-  if (cause instanceof FundingQuotes.UnsupportedSourceChainError)
+  if (cause instanceof FundingProvider.UnsupportedProviderError) return 'Unsupported `provider`.'
+  if (cause instanceof FundingProvider.UnsupportedSourceChainError)
     return 'Unsupported `sourceChain`.'
   return undefined
 }
@@ -602,3 +1815,7 @@ function cacheBypass(request: Request) {
   ).toLowerCase()
   return directives.includes('no-cache') || directives.includes('no-store')
 }
+
+class IdempotencyLeaseLostError extends Error {
+  override name = 'Funding.IdempotencyLeaseLostError'
+}