@zkp2p/cash 0.1.8 → 0.1.9

package/AGENTS.md

@@ -54,6 +54,9 @@ const relayCaps = await cash.capabilities({ includeRelaySources: true });
 // 2. Estimate - idempotent, cacheable, no side effects. Includes rolling ETA.
 const est = await cash.estimate({ amount: usdc(500), currency: 'EUR' });
 
+// Progressive UI: do not let indexer-backed history hold up the oracle rate.
+const rateOnly = await cash.estimate({ amount: usdc(500), currency: 'EUR' }, { includeEta: false });
+
 // Optional: raw demand + speed evidence per offered platform:currency pair.
 const stats = await cash.fillStats();
 
@@ -106,7 +109,9 @@ console.log(routed.source?.transactions?.origin, routed.source?.transactions?.de
 - **Do not invent an ETA.** Use `estimate().eta`: `{ seconds, label }` backed
   by the same rolling 30-day, intent-attributed pair sample as `fillStats()`,
   measured from deposit creation to first fill. Use `order.explain()` for live
-  order state.
+  order state. For progressive UIs, call `estimate(..., { includeEta: false })`
+  and load `fillStats()["platform:CURRENCY"]` separately. The SDK caches the
+  raw snapshot for 15 minutes, but never substitutes another pair's data.
 - **Do not hardcode Relay source assets.** Use Relay SDK-backed EVM
   `capabilities({ includeRelaySources: true })` and `cashout({ source, ... })`.
   Destination is always Base USDC. Non-Base source chains require

package/README.md

@@ -34,6 +34,13 @@ const est = await cash.estimate({ amount: usdc(1000), currency: 'USD' });
 // { rate: 1, receiveAmount: 1000, kind: 'oracle-estimate', eta: { seconds, label } }
 // "≈", never a locked quote. Base USDC remains the default source.
 
+// Progressive UI: render rate/receive first, then resolve the exact pair ETA.
+const rateOnly = await cash.estimate(
+  { amount: usdc(1000), currency: 'USD' },
+  { includeEta: false },
+);
+const pairStats = (await cash.fillStats())['venmo:USD'];
+
 const { depositId } = await cash.cashout(
   {
     amount: usdc(1000),
@@ -76,10 +83,10 @@ console.log(source?.transactions?.origin, source?.transactions?.destination);
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `capabilities()`                                               | Sync discovery: Base USDC destination/default source, platforms × currencies × payee hints × amount bounds                      |
 | `capabilities({ includeRelaySources: true })`                  | Async discovery: adds live Relay SDK EVM source chains/tokens                                                                   |
-| `fillStats()`                                                  | Raw 30-day fill counts and median first-fill time per `platform:currency` pair                                                  |
+| `fillStats()`                                                  | Cached 30-day fill counts and median first-fill time per exact `platform:currency` pair                                         |
 | `quoteSource(input)` / `executeSourceQuote(quote, { signer })` | Relay SDK EVM source routing into Base USDC before cashout                                                                      |
 | `relayStatus(requestId)`                                       | Relay request status from the Relay SDK request path                                                                            |
-| `estimate({ amount, currency })`                               | Base USDC oracle estimate plus simple recent-fill ETA                                                                           |
+| `estimate({ amount, currency }, { includeEta? })`              | Base USDC oracle estimate; optionally skip the historical ETA for progressive rendering                                         |
 | `cashout(input, { signer })`                                   | Registers your payee, creates the protocol-held order, returns the `depositId`                                                  |
 | `order(depositId)` / `orders(owner)`                           | Resume any order from its id alone; list all orders for a wallet                                                                |
 | `watch(depositId)`                                             | Async iterator: yields on every state change until terminal, abort, or timeout                                                  |
@@ -180,6 +187,9 @@ awaiting-buyer ──────────► matched ───────
 - **ETA is historical.** `estimate().eta` is just `{ seconds, label }`, backed
   by the same rolling 30-day, intent-attributed pair sampler as `fillStats()`,
   measured from deposit creation to the first fulfilled fill through the pair.
+  The raw snapshot is cached for 15 minutes per client and each ETA is still
+  resolved from its exact normalized `platform:currency` key. Use
+  `{ includeEta: false }` when rate and receive amount should render first.
 - **Availability thresholds belong to the consumer.** `fillStats()` returns raw
   evidence. A recommended gate is `fills >= 10 && medianFillSeconds <= 48h`.
   Fail open to the full `capabilities()` catalog when stats are unavailable or

package/dist/{createCashClient-BIzOLHjF.d.cts → createCashClient-BhOytyHE.d.cts}

@@ -401,6 +401,13 @@ interface EstimateInput {
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
 }
+interface EstimateOptions {
+    /**
+     * Include the historical indexer-backed ETA. Disable for progressive UIs
+     * that render the oracle rate first and load pair fill stats separately.
+     */
+    includeEta?: boolean;
+}
 interface CashEstimate {
     /** Always `'oracle-estimate'` - there is no committed quote in Peer Cash. */
     kind: 'oracle-estimate';
@@ -612,7 +619,7 @@ interface CashClient {
     /** Track Relay execution status by quote/request id. */
     relayStatus(requestId: string): Promise<RelayStatus>;
     /** 1 - Estimate: currency + amount only. No payee, no side effects, no expiry. */
-    estimate(input: EstimateInput): Promise<CashEstimate>;
+    estimate(input: EstimateInput, options?: EstimateOptions): Promise<CashEstimate>;
     /** 2 - Cash out: payee registration + deposit params + submission happen here. */
     cashout(input: CashoutInput, opts: CashoutOptions): Promise<CashoutResult>;
     /** 2b - Unsigned path: `txs[]` for agent wallets, AA, server keys, policy layers. */
@@ -655,4 +662,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, RECOMMENDED_MIN_CASHOUT_AMOUNT as H, type IntentStatus as I, type RelayOptions as J, type RelayQuoteInput as K, type RelaySourceInput as L, MIN_CASHOUT_AMOUNT as M, type RelayTransaction as N, type OrdersOptions as O, type PrepareResult as P, type WatchOptions as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WithdrawOptions as U, buildCapabilities as V, type WithdrawResult as W, createCashClient as X, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };
+export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, type EstimateOptions as H, type IntentStatus as I, RECOMMENDED_MIN_CASHOUT_AMOUNT as J, type RelayOptions as K, type RelayQuoteInput as L, MIN_CASHOUT_AMOUNT as M, type RelaySourceInput as N, type OrdersOptions as O, type PrepareResult as P, type RelayTransaction as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WatchOptions as U, type WithdrawOptions as V, type WithdrawResult as W, buildCapabilities as X, createCashClient as Y, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };

package/dist/{createCashClient-BIzOLHjF.d.ts → createCashClient-BhOytyHE.d.ts}

@@ -401,6 +401,13 @@ interface EstimateInput {
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
 }
+interface EstimateOptions {
+    /**
+     * Include the historical indexer-backed ETA. Disable for progressive UIs
+     * that render the oracle rate first and load pair fill stats separately.
+     */
+    includeEta?: boolean;
+}
 interface CashEstimate {
     /** Always `'oracle-estimate'` - there is no committed quote in Peer Cash. */
     kind: 'oracle-estimate';
@@ -612,7 +619,7 @@ interface CashClient {
     /** Track Relay execution status by quote/request id. */
     relayStatus(requestId: string): Promise<RelayStatus>;
     /** 1 - Estimate: currency + amount only. No payee, no side effects, no expiry. */
-    estimate(input: EstimateInput): Promise<CashEstimate>;
+    estimate(input: EstimateInput, options?: EstimateOptions): Promise<CashEstimate>;
     /** 2 - Cash out: payee registration + deposit params + submission happen here. */
     cashout(input: CashoutInput, opts: CashoutOptions): Promise<CashoutResult>;
     /** 2b - Unsigned path: `txs[]` for agent wallets, AA, server keys, policy layers. */
@@ -655,4 +662,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, RECOMMENDED_MIN_CASHOUT_AMOUNT as H, type IntentStatus as I, type RelayOptions as J, type RelayQuoteInput as K, type RelaySourceInput as L, MIN_CASHOUT_AMOUNT as M, type RelayTransaction as N, type OrdersOptions as O, type PrepareResult as P, type WatchOptions as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WithdrawOptions as U, buildCapabilities as V, type WithdrawResult as W, createCashClient as X, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };
+export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, type EstimateOptions as H, type IntentStatus as I, RECOMMENDED_MIN_CASHOUT_AMOUNT as J, type RelayOptions as K, type RelayQuoteInput as L, MIN_CASHOUT_AMOUNT as M, type RelaySourceInput as N, type OrdersOptions as O, type PrepareResult as P, type RelayTransaction as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WatchOptions as U, type WithdrawOptions as V, type WithdrawResult as W, buildCapabilities as X, createCashClient as Y, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };

package/dist/index.cjs

@@ -959,11 +959,7 @@ async function readFillStatsSample(client, environment) {
   }
   return computeFillStatsSample(deposits, now, environment);
 }
-async function readFillStats(client, environment) {
-  return (await readFillStatsSample(client, environment)).stats;
-}
-async function readFillEta(client, input) {
-  const sample = await readFillStatsSample(client, input.environment);
+function fillEtaFromSample(sample, input) {
   const currency = input.currency.toUpperCase();
   const seconds = input.platform ? sample.stats[`${basePlatformForMethod(input.platform)}:${currency}`]?.medianFillSeconds : sample.medianFillSecondsByCurrency.get(currency);
   return {
@@ -971,6 +967,10 @@ async function readFillEta(client, input) {
     label: etaLabel(seconds)
   };
 }
+async function readFillEta(client, input) {
+  const sample = await readFillStatsSample(client, input.environment);
+  return fillEtaFromSample(sample, input);
+}
 var RELAY_API_URL = relaySdk.MAINNET_RELAY_API;
 var NATIVE_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";
 var BASE_USDC_ASSET = {
@@ -1506,13 +1506,18 @@ async function readEstimate(publicClient, input, context = {}) {
       }
     } : {}
   };
-  if (context.indexerClient && context.environment) {
+  if (context.includeEta !== false && context.environment) {
     try {
-      estimate.eta = await readFillEta(context.indexerClient, {
+      const etaInput = {
         environment: context.environment,
         currency,
         ...input.platform ? { platform: input.platform } : {}
-      });
+      };
+      if (context.etaReader) {
+        estimate.eta = await context.etaReader(etaInput);
+      } else if (context.indexerClient) {
+        estimate.eta = await readFillEta(context.indexerClient, etaInput);
+      }
     } catch {
     }
   }
@@ -1521,6 +1526,7 @@ async function readEstimate(publicClient, input, context = {}) {
 
 // src/client/createCashClient.ts
 var DEFAULT_RPC_URL = "https://mainnet.base.org";
+var FILL_STATS_CACHE_MS = 15 * 60 * 1e3;
 var CASH_ATTRIBUTION_CODE = "peer-cash";
 var DEFAULT_CURATOR_URLS = {
   preproduction: "https://api-preprod.zkp2p.xyz",
@@ -1619,6 +1625,25 @@ function createCashClient(options) {
     });
   }
   const readClient = buildSdkClient(viem.createWalletClient({ chain: chains.base, transport }));
+  let fillStatsCache = null;
+  let fillStatsRequest = null;
+  async function getFillStatsSample() {
+    if (fillStatsCache && fillStatsCache.expiresAt > Date.now()) {
+      return fillStatsCache.sample;
+    }
+    if (fillStatsRequest) return fillStatsRequest;
+    fillStatsRequest = readFillStatsSample(readClient, environment);
+    try {
+      const sample = await fillStatsRequest;
+      fillStatsCache = {
+        sample,
+        expiresAt: Date.now() + FILL_STATS_CACHE_MS
+      };
+      return sample;
+    } finally {
+      fillStatsRequest = null;
+    }
+  }
   const signingClients = /* @__PURE__ */ new WeakMap();
   async function signingClient(verb, opts) {
     const signer = opts?.signer;
@@ -1921,16 +1946,17 @@ function createCashClient(options) {
     async relayStatus(requestId) {
       return readRelayStatus(requestId, options.relay);
     },
-    async estimate(input) {
+    async estimate(input, estimateOptions) {
       return readEstimate(readClient.publicClient, input, {
-        indexerClient: readClient,
         environment,
+        ...estimateOptions?.includeEta !== void 0 ? { includeEta: estimateOptions.includeEta } : {},
+        etaReader: async (etaInput) => fillEtaFromSample(await getFillStatsSample(), etaInput),
         ...options.relay ? { relay: options.relay } : {}
       });
     },
     async fillStats() {
       try {
-        return await readFillStats(readClient, environment);
+        return (await getFillStatsSample()).stats;
       } catch (err) {
         throw errors.indexerUnavailable("fill stats", err);
       }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-BIzOLHjF.cjs';
-export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashNextAction, w as CashOrderState, x as CashPairFillStats, y as CashPayout, z as CashPayoutPricing, A as CashPlatformCapability, B as CashPreparedStepKind, D as CashoutInput, E as CashoutOptions, F as CuratorPayeeDataInput, G as EstimateInput, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, H as RECOMMENDED_MIN_CASHOUT_AMOUNT, J as RelayOptions, K as RelayQuoteInput, L as RelaySourceInput, N as RelayTransaction, S as SignerOptions, Q as WatchOptions, U as WithdrawOptions, V as buildCapabilities, X as createCashClient } from './createCashClient-BIzOLHjF.cjs';
+import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-BhOytyHE.cjs';
+export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashNextAction, w as CashOrderState, x as CashPairFillStats, y as CashPayout, z as CashPayoutPricing, A as CashPlatformCapability, B as CashPreparedStepKind, D as CashoutInput, E as CashoutOptions, F as CuratorPayeeDataInput, G as EstimateInput, H as EstimateOptions, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, J as RECOMMENDED_MIN_CASHOUT_AMOUNT, K as RelayOptions, L as RelayQuoteInput, N as RelaySourceInput, Q as RelayTransaction, S as SignerOptions, U as WatchOptions, V as WithdrawOptions, X as buildCapabilities, Y as createCashClient } from './createCashClient-BhOytyHE.cjs';
 import { PaymentMethodCatalog, CurrencyType, OracleAdapterOverrides, OnchainCurrency, Zkp2pClient, PreparedTransaction } from '@zkp2p/sdk';
 export { CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Log, Abi } from 'viem';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-BIzOLHjF.js';
-export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashNextAction, w as CashOrderState, x as CashPairFillStats, y as CashPayout, z as CashPayoutPricing, A as CashPlatformCapability, B as CashPreparedStepKind, D as CashoutInput, E as CashoutOptions, F as CuratorPayeeDataInput, G as EstimateInput, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, H as RECOMMENDED_MIN_CASHOUT_AMOUNT, J as RelayOptions, K as RelayQuoteInput, L as RelaySourceInput, N as RelayTransaction, S as SignerOptions, Q as WatchOptions, U as WithdrawOptions, V as buildCapabilities, X as createCashClient } from './createCashClient-BIzOLHjF.js';
+import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-BhOytyHE.js';
+export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashNextAction, w as CashOrderState, x as CashPairFillStats, y as CashPayout, z as CashPayoutPricing, A as CashPlatformCapability, B as CashPreparedStepKind, D as CashoutInput, E as CashoutOptions, F as CuratorPayeeDataInput, G as EstimateInput, H as EstimateOptions, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, J as RECOMMENDED_MIN_CASHOUT_AMOUNT, K as RelayOptions, L as RelayQuoteInput, N as RelaySourceInput, Q as RelayTransaction, S as SignerOptions, U as WatchOptions, V as WithdrawOptions, X as buildCapabilities, Y as createCashClient } from './createCashClient-BhOytyHE.js';
 import { PaymentMethodCatalog, CurrencyType, OracleAdapterOverrides, OnchainCurrency, Zkp2pClient, PreparedTransaction } from '@zkp2p/sdk';
 export { CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Log, Abi } from 'viem';

package/dist/index.js

@@ -580,11 +580,7 @@ async function readFillStatsSample(client, environment) {
   }
   return computeFillStatsSample(deposits, now, environment);
 }
-async function readFillStats(client, environment) {
-  return (await readFillStatsSample(client, environment)).stats;
-}
-async function readFillEta(client, input) {
-  const sample = await readFillStatsSample(client, input.environment);
+function fillEtaFromSample(sample, input) {
   const currency = input.currency.toUpperCase();
   const seconds = input.platform ? sample.stats[`${basePlatformForMethod(input.platform)}:${currency}`]?.medianFillSeconds : sample.medianFillSecondsByCurrency.get(currency);
   return {
@@ -592,6 +588,10 @@ async function readFillEta(client, input) {
     label: etaLabel(seconds)
   };
 }
+async function readFillEta(client, input) {
+  const sample = await readFillStatsSample(client, input.environment);
+  return fillEtaFromSample(sample, input);
+}
 var RELAY_API_URL = MAINNET_RELAY_API;
 var NATIVE_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";
 var BASE_USDC_ASSET = {
@@ -1127,13 +1127,18 @@ async function readEstimate(publicClient, input, context = {}) {
       }
     } : {}
   };
-  if (context.indexerClient && context.environment) {
+  if (context.includeEta !== false && context.environment) {
     try {
-      estimate.eta = await readFillEta(context.indexerClient, {
+      const etaInput = {
         environment: context.environment,
         currency,
         ...input.platform ? { platform: input.platform } : {}
-      });
+      };
+      if (context.etaReader) {
+        estimate.eta = await context.etaReader(etaInput);
+      } else if (context.indexerClient) {
+        estimate.eta = await readFillEta(context.indexerClient, etaInput);
+      }
     } catch {
     }
   }
@@ -1142,6 +1147,7 @@ async function readEstimate(publicClient, input, context = {}) {
 
 // src/client/createCashClient.ts
 var DEFAULT_RPC_URL = "https://mainnet.base.org";
+var FILL_STATS_CACHE_MS = 15 * 60 * 1e3;
 var CASH_ATTRIBUTION_CODE = "peer-cash";
 var DEFAULT_CURATOR_URLS = {
   preproduction: "https://api-preprod.zkp2p.xyz",
@@ -1240,6 +1246,25 @@ function createCashClient(options) {
     });
   }
   const readClient = buildSdkClient(createWalletClient({ chain: base, transport }));
+  let fillStatsCache = null;
+  let fillStatsRequest = null;
+  async function getFillStatsSample() {
+    if (fillStatsCache && fillStatsCache.expiresAt > Date.now()) {
+      return fillStatsCache.sample;
+    }
+    if (fillStatsRequest) return fillStatsRequest;
+    fillStatsRequest = readFillStatsSample(readClient, environment);
+    try {
+      const sample = await fillStatsRequest;
+      fillStatsCache = {
+        sample,
+        expiresAt: Date.now() + FILL_STATS_CACHE_MS
+      };
+      return sample;
+    } finally {
+      fillStatsRequest = null;
+    }
+  }
   const signingClients = /* @__PURE__ */ new WeakMap();
   async function signingClient(verb, opts) {
     const signer = opts?.signer;
@@ -1542,16 +1567,17 @@ function createCashClient(options) {
     async relayStatus(requestId) {
       return readRelayStatus(requestId, options.relay);
     },
-    async estimate(input) {
+    async estimate(input, estimateOptions) {
       return readEstimate(readClient.publicClient, input, {
-        indexerClient: readClient,
         environment,
+        ...estimateOptions?.includeEta !== void 0 ? { includeEta: estimateOptions.includeEta } : {},
+        etaReader: async (etaInput) => fillEtaFromSample(await getFillStatsSample(), etaInput),
         ...options.relay ? { relay: options.relay } : {}
       });
     },
     async fillStats() {
       try {
-        return await readFillStats(readClient, environment);
+        return (await getFillStatsSample()).stats;
       } catch (err) {
         throw errors.indexerUnavailable("fill stats", err);
       }

package/dist/react.cjs

@@ -9,6 +9,7 @@ function useEstimate({
   currency,
   platform,
   source,
+  includeEta = true,
   refreshIntervalMs = 0
 }) {
   const [estimate, setEstimate] = react.useState(null);
@@ -34,7 +35,7 @@ function useEstimate({
       }
       return;
     }
-    const identity = { client, amount, currency, platform, source };
+    const identity = { client, amount, currency, platform, source, includeEta };
     if (isCurrent()) {
       loadingIdentityRef.current = identity;
       errorIdentityRef.current = null;
@@ -42,12 +43,15 @@ function useEstimate({
       setError(null);
     }
     try {
-      const result = await client.estimate({
-        amount,
-        currency,
-        ...platform ? { platform } : {},
-        ...source ? { source } : {}
-      });
+      const result = await client.estimate(
+        {
+          amount,
+          currency,
+          ...platform ? { platform } : {},
+          ...source ? { source } : {}
+        },
+        { includeEta }
+      );
       if (isCurrent()) {
         estimateIdentityRef.current = identity;
         setEstimate(result);
@@ -63,7 +67,7 @@ function useEstimate({
     } finally {
       if (isCurrent()) setIsLoading(false);
     }
-  }, [client, currency, amount, platform, source]);
+  }, [client, currency, amount, platform, source, includeEta]);
   react.useEffect(() => {
     latestRequestRef.current += 1;
     estimateIdentityRef.current = null;
@@ -72,7 +76,7 @@ function useEstimate({
     setEstimate(null);
     setIsLoading(false);
     setError(null);
-  }, [client, amount, currency, platform, source]);
+  }, [client, amount, currency, platform, source, includeEta]);
   react.useEffect(() => {
     mountedRef.current = true;
     void refresh();
@@ -85,7 +89,7 @@ function useEstimate({
       if (timerRef.current) clearInterval(timerRef.current);
     };
   }, [refresh, refreshIntervalMs]);
-  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source;
+  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source && identity.includeEta === includeEta;
   return {
     estimate: matchesCurrentIdentity(estimateIdentityRef.current) ? estimate : null,
     isLoading: matchesCurrentIdentity(loadingIdentityRef.current) ? isLoading : false,

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BIzOLHjF.cjs';
+import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BhOytyHE.cjs';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 
@@ -12,6 +12,8 @@ interface UseEstimateOptions {
     platform?: string | null | undefined;
     /** Optional Relay source. Omit for the Base USDC default path. */
     source?: EstimateInput['source'] | null | undefined;
+    /** Disable to render the oracle rate before loading pair fill stats separately. */
+    includeEta?: boolean;
     /** Re-fetch interval (ms) so the displayed rate tracks the market. 0 = no auto-refresh. */
     refreshIntervalMs?: number;
 }
@@ -20,7 +22,7 @@ interface UseEstimateOptions {
  * estimate; the binding rate resolves at the Chainlink oracle when a buyer
  * fills - there is no committed quote to show.
  */
-declare function useEstimate({ client, amount, currency, platform, source, refreshIntervalMs, }: UseEstimateOptions): {
+declare function useEstimate({ client, amount, currency, platform, source, includeEta, refreshIntervalMs, }: UseEstimateOptions): {
     estimate: CashEstimate | null;
     isLoading: boolean;
     error: Error | null;

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BIzOLHjF.js';
+import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BhOytyHE.js';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 
@@ -12,6 +12,8 @@ interface UseEstimateOptions {
     platform?: string | null | undefined;
     /** Optional Relay source. Omit for the Base USDC default path. */
     source?: EstimateInput['source'] | null | undefined;
+    /** Disable to render the oracle rate before loading pair fill stats separately. */
+    includeEta?: boolean;
     /** Re-fetch interval (ms) so the displayed rate tracks the market. 0 = no auto-refresh. */
     refreshIntervalMs?: number;
 }
@@ -20,7 +22,7 @@ interface UseEstimateOptions {
  * estimate; the binding rate resolves at the Chainlink oracle when a buyer
  * fills - there is no committed quote to show.
  */
-declare function useEstimate({ client, amount, currency, platform, source, refreshIntervalMs, }: UseEstimateOptions): {
+declare function useEstimate({ client, amount, currency, platform, source, includeEta, refreshIntervalMs, }: UseEstimateOptions): {
     estimate: CashEstimate | null;
     isLoading: boolean;
     error: Error | null;

package/dist/react.js

@@ -7,6 +7,7 @@ function useEstimate({
   currency,
   platform,
   source,
+  includeEta = true,
   refreshIntervalMs = 0
 }) {
   const [estimate, setEstimate] = useState(null);
@@ -32,7 +33,7 @@ function useEstimate({
       }
       return;
     }
-    const identity = { client, amount, currency, platform, source };
+    const identity = { client, amount, currency, platform, source, includeEta };
     if (isCurrent()) {
       loadingIdentityRef.current = identity;
       errorIdentityRef.current = null;
@@ -40,12 +41,15 @@ function useEstimate({
       setError(null);
     }
     try {
-      const result = await client.estimate({
-        amount,
-        currency,
-        ...platform ? { platform } : {},
-        ...source ? { source } : {}
-      });
+      const result = await client.estimate(
+        {
+          amount,
+          currency,
+          ...platform ? { platform } : {},
+          ...source ? { source } : {}
+        },
+        { includeEta }
+      );
       if (isCurrent()) {
         estimateIdentityRef.current = identity;
         setEstimate(result);
@@ -61,7 +65,7 @@ function useEstimate({
     } finally {
       if (isCurrent()) setIsLoading(false);
     }
-  }, [client, currency, amount, platform, source]);
+  }, [client, currency, amount, platform, source, includeEta]);
   useEffect(() => {
     latestRequestRef.current += 1;
     estimateIdentityRef.current = null;
@@ -70,7 +74,7 @@ function useEstimate({
     setEstimate(null);
     setIsLoading(false);
     setError(null);
-  }, [client, amount, currency, platform, source]);
+  }, [client, amount, currency, platform, source, includeEta]);
   useEffect(() => {
     mountedRef.current = true;
     void refresh();
@@ -83,7 +87,7 @@ function useEstimate({
       if (timerRef.current) clearInterval(timerRef.current);
     };
   }, [refresh, refreshIntervalMs]);
-  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source;
+  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source && identity.includeEta === includeEta;
   return {
     estimate: matchesCurrentIdentity(estimateIdentityRef.current) ? estimate : null,
     isLoading: matchesCurrentIdentity(loadingIdentityRef.current) ? isLoading : false,

package/dist/tools.cjs

@@ -2,7 +2,7 @@
 
 // package.json
 var package_default = {
-  version: "0.1.8"};
+  version: "0.1.9"};
 
 // src/tools/index.ts
 var bigintString = {

package/dist/tools.js

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "0.1.8"};
+  version: "0.1.9"};
 
 // src/tools/index.ts
 var bigintString = {

package/docs/lifecycle-and-recovery.md

@@ -135,6 +135,11 @@ methods aggregate to `zelle:USD`. Consumers own thresholding; the recommended
 gate is `fills >= 10 && medianFillSeconds <= 48h`, with a fail-open fallback to
 the full capability catalog when the read fails or filtering would empty it.
 Medians are per-deposit first-fill latencies, never means or censored cohorts.
+The client caches one raw environment snapshot for 15 minutes and de-duplicates
+concurrent reads; ETA resolution still uses only the requested normalized
+`platform:currency` key. A progressive UI can call
+`estimate(input, { includeEta: false })` to render rate/receive immediately,
+then read that pair from `fillStats()` without coupling the two loading states.
 
 - **Buyer arrival time is market-driven.** A deposit at market rate should
   fill fast, but the ETA is only a recent historical sample.

package/llms.txt

@@ -24,6 +24,11 @@ Key facts:
 - fillStats() returns raw `{ fills, medianFillSeconds? }` evidence keyed by
   `platform:currency`. Recommended consumer gate: fills >= 10 and median <=
   48h; fail open to capabilities() if unavailable or filtering empties it.
+  Its raw environment snapshot is cached for 15 minutes, while lookups remain
+  exact to the normalized platform:currency pair.
+- Progressive UIs can call estimate(input, { includeEta: false }) so the
+  oracle rate is not blocked by indexer history, then load the exact pair from
+  fillStats() separately.
 - capabilities() exposes one Zelle platform. A zelle cashout internally attaches
   the generic method plus Chase, Bank of America, and Citi buyer routes.
 - Resume any order from its depositId alone (composite escrow_onchainId).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Peer Cash - offramp-only SDK for routing crypto to Base USDC, then cashing out to fiat at the live oracle market rate.",
   "license": "MIT",
   "author": "Peer (https://peer.xyz)",