@zkp2p/sdk 0.2.4 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@
 
 Stable TypeScript SDK for trustless fiat-to-crypto on Base. ZKP2P combines escrowed on-chain settlement, TLS attestations for payment verification, and API/indexer helpers so makers, takers, wallets, and embedded ramps can ship production-grade fiat liquidity flows without building their own contract or indexing stack.
 
-Current version: `0.2.3`
+Current version: `0.3.1`
 
 ## Why This SDK
 
@@ -73,13 +73,13 @@ const client = new Zkp2pClient({
 - Supported runtime environments: `'production'`, `'preproduction'`, `'staging'`
 - `runtimeEnv` default: `'production'`
 - `rpcUrl`: optional RPC URL override (defaults to wallet's chain RPC)
-- `apiKey`: optional curator API key — enhances some responses (e.g. `getQuote` returns `depositData` when authenticated) but is **not required** for any SDK method
+- `apiKey`: optional curator-issued API key — used when the SDK auto-fetches `signalIntent()` gating signatures and enables richer authenticated `getQuote()` responses with resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`)
 - `authorizationToken` / `getAuthorizationToken`: optional bearer auth for hybrid client and indexer flows
 - `indexerApiKey`: optional `x-api-key` for indexer proxy auth
 - `indexerUrl` and `baseApiUrl`: override defaults when you are targeting custom deployments
 - `timeouts`: `{ api?: number }` — API timeout in milliseconds (default 15000)
 
-**No API key is required to get started.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, and all other SDK methods work without `apiKey` or `authorizationToken`. Auth credentials are optional and only affect response richness (e.g. authenticated quotes include maker `depositData`).
+**No API key is required to get started.** `createDeposit`, `registerPayeeDetails`, `getQuote`, `getTakerTier`, and the rest of the SDK work without `apiKey` or `authorizationToken`. The main tradeoff is that `signalIntent()` only auto-fetches a gating service signature from curator `/v3/intent/sign` when `apiKey` or `authorizationToken` is available; otherwise provide both `gatingServiceSignature` and `signatureExpiration` manually if your integration needs one. Authenticated quotes also include resolved maker payee details (`offchainId`, `telegramUsername`, `metadata`).
 
 Indexer defaults by environment:
 
@@ -95,7 +95,7 @@ Indexer defaults by environment:
 | Payment methods and currencies | `addPaymentMethods`, `removePaymentMethod`, `setPaymentMethodActive`, `addCurrencies`, `removeCurrency`, `deactivateCurrency`, `pruneExpiredIntents`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Intents                        | `signalIntent`, `fulfillIntent`, `cancelIntent`, `releaseFundsToPayer`, `getFulfillIntentInputs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Prepared transactions          | `client.prepareCreateDeposit(...)`, `client.signalIntent.prepare(...)`, `client.fulfillIntent.prepare(...)`, `client.setVaultFee.prepare(...)`, and equivalent prepare flows across the rest of the prepareable write surface                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Payee and quote APIs           | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getTakerTier`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Payee and quote APIs           | `registerPayeeDetails`, `resolvePayeeHash`, `getQuote`, `getQuotesBestByPlatform`, `getTakerTier`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Delegation and hooks           | `setDelegate`, `removeDelegate`, `setRateManager`, `clearRateManager`, `setDepositRateManager`, `clearDepositRateManager`, `setDepositPreIntentHook`, `setDepositWhitelistHook`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Vault / DRM                    | `createRateManager`, `setVaultMinRate`, `setVaultMinRatesBatch`, `setVaultFee`, `setVaultConfig`, `getDepositRateManager`, `getManagerFee`, `getEffectiveRate`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Oracle config                  | `setOracleRateConfig`, `setOracleRateConfigBatch`, `removeOracleRateConfig`, `updateCurrencyConfigBatch`, `deactivateCurrenciesBatch`, `supportsInlineOracleRateConfig`, `validateOracleFeedsOnChain`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -156,7 +156,7 @@ const payeeHash = await client.resolvePayeeHash(
 );
 ```
 
-`getQuote()` returns available liquidity plus payee details when authenticated. `getTakerTier()` returns limits and cooldown data for taker UX.
+`getQuote()` returns available liquidity plus payee details when authenticated. Use `getQuotesBestByPlatform()` to fetch the best quote per supported payment platform in a single call (handy for cross-platform comparison UIs). `getTakerTier()` returns limits and cooldown data for taker UX.
 
 ## Signal, Fulfill, and Release Intents
 
@@ -519,7 +519,7 @@ The SDK ships currency metadata for 34 fiat currencies:
 
 ## Supported Payment Platforms
 
-`wise`, `venmo`, `revolut`, `cashapp`, `mercadopago`, `zelle`, `paypal`, `monzo`, `chime`, `luxon`, `n26`
+`wise`, `venmo`, `revolut`, `cashapp`, `mercadopago`, `zelle`, `paypal`, `monzo`, `chime`, `luxon`, `n26`, `alipay`
 
 ## Attribution (ERC-8021)
 

package/dist/index.cjs

@@ -1099,15 +1099,9 @@ var init_protocolViewerParsers = __esm({
 
 // src/client/clientUtils.ts
 init_bigint();
+
+// src/utils/address.ts
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
-var MIN_ORACLE_SPREAD_BPS = -32768;
-var MAX_ORACLE_SPREAD_BPS = 32767;
-var EMPTY_ORACLE_RATE_CONFIG = {
-  adapter: ZERO_ADDRESS,
-  adapterConfig: "0x",
-  spreadBps: 0,
-  maxStaleness: 0
-};
 var isValidHexAddress = (addr) => {
   if (typeof addr !== "string") return false;
   return /^0x[0-9a-fA-F]{40}$/.test(addr);
@@ -1116,6 +1110,16 @@ var normalizeAddress = (addr) => {
   if (!isValidHexAddress(addr)) return void 0;
   return addr;
 };
+
+// src/client/clientUtils.ts
+var MIN_ORACLE_SPREAD_BPS = -32768;
+var MAX_ORACLE_SPREAD_BPS = 32767;
+var EMPTY_ORACLE_RATE_CONFIG = {
+  adapter: ZERO_ADDRESS,
+  adapterConfig: "0x",
+  spreadBps: 0,
+  maxStaleness: 0
+};
 var parseEscrowAddressFromCompositeDepositId = (depositId) => {
   if (typeof depositId !== "string") return void 0;
   const parts = depositId.split("_");
@@ -1422,9 +1426,6 @@ function parseAPIError(response, responseText) {
   } catch {
     if (responseText && responseText.length < 200) message = responseText;
   }
-  if (response.status === 429) {
-    message = "Too many requests. Please try again later.";
-  }
   return new exports.APIError(message, response.status, { url: response.url });
 }
 async function withRetry(fn, maxRetries = 3, delayMs = 1e3, timeoutMs) {
@@ -1459,7 +1460,7 @@ function createHeaders(apiKey, authorizationToken) {
   return headers2;
 }
 async function apiSignIntentV3(request, opts) {
-  const url = `${opts.baseApiUrl.replace(/\/$/, "")}/v3/intent`;
+  const url = `${opts.baseApiUrl.replace(/\/$/, "")}/v3/intent/sign`;
   const json = await withRetry(
     async () => {
       let res;
@@ -1471,7 +1472,7 @@ async function apiSignIntentV3(request, opts) {
         });
       } catch (error) {
         throw new exports.NetworkError("Failed to connect to API server", {
-          endpoint: "/v3/intent",
+          endpoint: "/v3/intent/sign",
           error
         });
       }
@@ -1488,11 +1489,13 @@ async function apiSignIntentV3(request, opts) {
   const sig = json?.responseObject?.signedIntent;
   const expStr = json?.responseObject?.intentData?.signatureExpiration ?? json?.responseObject?.signatureExpiration;
   const preIntentHookData = json?.responseObject?.intentData?.preIntentHookData ?? json?.responseObject?.preIntentHookData;
-  if (!sig || !expStr) throw new Error("v3/intent missing signature or expiration");
+  const referralFees = json?.responseObject?.intentData?.referralFees ?? json?.responseObject?.referralFees;
+  if (!sig || !expStr) throw new Error("v3/intent/sign missing signature or expiration");
   return {
     signature: sig,
     signatureExpiration: BigInt(expStr),
-    preIntentHookData
+    preIntentHookData,
+    referralFees
   };
 }
 
@@ -1919,7 +1922,7 @@ var IntentOperations = class {
     const depositId = parseRawDepositId(params.depositId);
     const amount = typeof params.amount === "bigint" ? params.amount : BigInt(params.amount);
     const conversionRate = typeof params.conversionRate === "bigint" ? params.conversionRate : BigInt(params.conversionRate);
-    const referralFees = referrerFeeConfig !== void 0 ? [
+    let referralFees = referrerFeeConfig !== void 0 ? [
       {
         recipient: referrerFeeConfig.recipient,
         fee: referrerFeeConfigToPreciseUnits(referrerFeeConfig)
@@ -1961,6 +1964,23 @@ var IntentOperations = class {
       gatingServiceSignature = response.signature;
       signatureExpiration = response.signatureExpiration;
       preIntentHookData = response.preIntentHookData ?? preIntentHookData;
+      if (response.referralFees !== void 0) {
+        referralFees = response.referralFees.map((referralFee) => {
+          if (!isValidReferrerFeeRecipient(referralFee.recipient)) {
+            throw new Error("v3/intent/sign returned invalid referral fee recipient");
+          }
+          let fee;
+          try {
+            fee = BigInt(referralFee.fee);
+          } catch {
+            throw new Error("v3/intent/sign returned non-integer referral fee value");
+          }
+          return {
+            recipient: referralFee.recipient,
+            fee
+          };
+        });
+      }
     }
     if (!gatingServiceSignature || !signatureExpiration) {
       throw new Error("Missing gatingServiceSignature/signatureExpiration");
@@ -4590,9 +4610,10 @@ function convertIndexerDepositToEscrowView(deposit, _chainId, _escrowAddress) {
     verifiers
   };
 }
-function convertDepositsForLiquidity(deposits, chainId, escrowAddress) {
+function convertDepositsForLiquidity(deposits, chainId, escrowAddress, options = {}) {
+  const { includePrivateOrderbooks = false } = options;
   return deposits.filter(
-    (d) => d.depositor && d.depositor.toLowerCase() !== ZERO && normalizeAddress2(d.whitelistHookAddress).toLowerCase() === ZERO && d.acceptingIntents && toBigInt(d.remainingDeposits) > 0n && d.status === "ACTIVE"
+    (d) => d.depositor && d.depositor.toLowerCase() !== ZERO && (includePrivateOrderbooks || normalizeAddress2(d.whitelistHookAddress).toLowerCase() === ZERO) && d.acceptingIntents && toBigInt(d.remainingDeposits) > 0n && d.status === "ACTIVE"
   ).map((d) => convertIndexerDepositToEscrowView(d));
 }
 function convertIndexerIntentsToEscrowViews(intents, depositViewsById) {
@@ -5927,13 +5948,11 @@ function convertIndexerDepositToLegacyApiDeposit(deposit) {
     verifiers
   };
 }
-async function apiPostDepositDetails(req, baseApiUrl, timeoutMs, apiKey, authToken) {
+async function apiPostDepositDetails(req, baseApiUrl, timeoutMs, _apiKey, _authToken) {
   return apiFetch({
-    url: `${withApiBase(baseApiUrl)}/v1/makers/create`,
+    url: `${withApiBase(baseApiUrl)}/v2/makers/create`,
     method: "POST",
     body: req,
-    apiKey,
-    authToken,
     timeoutMs
   });
 }
@@ -5943,16 +5962,29 @@ async function apiGetQuote(req, baseApiUrl, timeoutMs, apiKey, authToken) {
       throw new exports.ValidationError("quotesToReturn must be a positive integer", "quotesToReturn");
     }
   }
+  if (!isValidHexAddress(req.user)) {
+    throw new exports.ValidationError("user must be a valid Ethereum address", "user");
+  }
+  if (!isValidHexAddress(req.recipient)) {
+    throw new exports.ValidationError("recipient must be a valid Ethereum address", "recipient");
+  }
+  if (!isValidHexAddress(req.destinationToken)) {
+    throw new exports.ValidationError(
+      "destinationToken must be a valid Ethereum address",
+      "destinationToken"
+    );
+  }
   const isExactFiat = req.isExactFiat !== false;
   const endpoint = isExactFiat ? "exact-fiat" : "exact-token";
   let url = `${withApiBase(baseApiUrl)}/v2/quote/${endpoint}`;
   if (req.quotesToReturn) url += `?quotesToReturn=${req.quotesToReturn}`;
   const requestBody = {
     ...req,
-    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: req.amount,
+    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: String(req.amount),
     amount: void 0,
     isExactFiat: void 0,
-    quotesToReturn: void 0
+    quotesToReturn: void 0,
+    includePrivateOrderbooks: req.includePrivateOrderbooks
   };
   Object.keys(requestBody).forEach((k) => requestBody[k] === void 0 && delete requestBody[k]);
   return apiFetch({
@@ -5964,9 +5996,32 @@ async function apiGetQuote(req, baseApiUrl, timeoutMs, apiKey, authToken) {
     timeoutMs
   });
 }
+async function apiGetQuotesBestByPlatform(req, baseApiUrl, timeoutMs, apiKey, authToken) {
+  const isExactFiat = req.isExactFiat !== false;
+  const endpoint = isExactFiat ? "best-by-platform" : "best-by-platform-exact-token";
+  const url = `${withApiBase(baseApiUrl)}/v2/quote/${endpoint}`;
+  const requestBody = {
+    ...req,
+    [isExactFiat ? "exactFiatAmount" : "exactTokenAmount"]: String(req.amount),
+    amount: void 0,
+    isExactFiat: void 0,
+    referrerFeeConfig: void 0
+  };
+  Object.keys(requestBody).forEach(
+    (key) => requestBody[key] === void 0 && delete requestBody[key]
+  );
+  return apiFetch({
+    url,
+    method: "POST",
+    body: requestBody,
+    apiKey,
+    authToken,
+    timeoutMs
+  });
+}
 async function apiGetPayeeDetails(req, apiKey, baseApiUrl, authToken, timeoutMs) {
   return apiFetch({
-    url: `${baseApiUrl.replace(/\/$/, "")}/v1/makers/${req.processorName}/${req.hashedOnchainId}`,
+    url: `${baseApiUrl.replace(/\/$/, "")}/v2/makers/${req.processorName}/${req.hashedOnchainId}`,
     method: "GET",
     apiKey,
     authToken,
@@ -5975,7 +6030,7 @@ async function apiGetPayeeDetails(req, apiKey, baseApiUrl, authToken, timeoutMs)
 }
 async function apiValidatePayeeDetails(req, baseApiUrl, timeoutMs) {
   const data = await apiFetch({
-    url: `${baseApiUrl.replace(/\/$/, "")}/v1/makers/validate`,
+    url: `${baseApiUrl.replace(/\/$/, "")}/v2/makers/validate`,
     method: "POST",
     body: req,
     timeoutMs
@@ -6030,7 +6085,6 @@ async function apiGetTakerTier(req, apiKey, baseApiUrl, timeoutMs) {
   return apiFetch({
     url: `${withApiBase(baseApiUrl)}${endpoint}`,
     method: "GET",
-    apiKey,
     timeoutMs
   });
 }
@@ -6132,6 +6186,23 @@ var appendReferrerFeeDisplayFields = (quoteResponse, referrerFeeConfig) => {
     }
   };
 };
+var appendReferrerFeeDisplayFieldsToBestByPlatform = (quoteResponse, referrerFeeConfig) => {
+  if (!referrerFeeConfig) {
+    return quoteResponse;
+  }
+  const decimals = quoteResponse.responseObject?.token?.decimals ?? 6;
+  const enrichedPlatformQuotes = (quoteResponse.responseObject?.platformQuotes ?? []).map((platformQuote) => ({
+    ...platformQuote,
+    bestQuote: platformQuote.available && platformQuote.bestQuote ? applyReferrerFeeDisplayFieldsToQuote(platformQuote.bestQuote, referrerFeeConfig, decimals) : platformQuote.bestQuote
+  }));
+  return {
+    ...quoteResponse,
+    responseObject: {
+      ...quoteResponse.responseObject,
+      platformQuotes: enrichedPlatformQuotes
+    }
+  };
+};
 
 // src/utils/erc20.ts
 var ERC20_ABI = [
@@ -6158,6 +6229,95 @@ var ERC20_ABI = [
 ];
 
 // src/client/Zkp2pClient.ts
+function isStringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every((entry) => typeof entry === "string");
+}
+function normalizeTelegramUsername(value) {
+  if (typeof value !== "string") {
+    return value === null ? null : null;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+function extractLegacyQuotePayeeData(depositData) {
+  if (!depositData || typeof depositData !== "object" || Array.isArray(depositData)) {
+    return void 0;
+  }
+  const stringEntries = Object.entries(depositData).filter(
+    (entry) => typeof entry[1] === "string" && entry[1].trim().length > 0
+  );
+  const telegramUsername = stringEntries.find(([key]) => key === "telegramUsername")?.[1] ?? null;
+  const identifierEntries = stringEntries.filter(([key]) => key !== "telegramUsername");
+  const [primaryEntry, ...metadataEntries] = identifierEntries;
+  if (!primaryEntry) {
+    return void 0;
+  }
+  return {
+    offchainId: primaryEntry[1],
+    telegramUsername,
+    metadata: metadataEntries.length > 0 ? Object.fromEntries(metadataEntries) : null
+  };
+}
+function normalizeQuotePayeeData(maker) {
+  const legacy = extractLegacyQuotePayeeData(maker?.depositData);
+  const offchainId = typeof maker?.offchainId === "string" && maker.offchainId.trim().length > 0 ? maker.offchainId : legacy?.offchainId;
+  if (!offchainId) {
+    return void 0;
+  }
+  return {
+    offchainId,
+    telegramUsername: normalizeTelegramUsername(maker?.telegramUsername) ?? legacy?.telegramUsername ?? null,
+    metadata: isStringRecord(maker?.metadata) ? maker.metadata : legacy?.metadata ?? null
+  };
+}
+function normalizePayeeDataInputItem(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const candidate = raw;
+  if (typeof candidate.offchainId === "string" && candidate.offchainId.trim().length > 0) {
+    return candidate;
+  }
+  const legacy = extractLegacyQuotePayeeData(raw);
+  if (!legacy) {
+    return null;
+  }
+  return {
+    offchainId: legacy.offchainId,
+    telegramUsername: legacy.telegramUsername,
+    metadata: legacy.metadata
+  };
+}
+function resolvePayeeDataInput(params, methodName) {
+  const payeeData = params.payeeData ?? params.depositData;
+  if (!Array.isArray(payeeData)) {
+    throw new Error(`${methodName} requires payeeData`);
+  }
+  const normalized = payeeData.map((item, index) => {
+    const result = normalizePayeeDataInputItem(item);
+    if (!result) {
+      throw new Error(
+        `${methodName}: payeeData[${index}] must include a non-empty offchainId or a recognizable legacy identifier`
+      );
+    }
+    return result;
+  });
+  return normalized;
+}
+function toPostDepositDetailsRequest(processorName, payeeData, index) {
+  if (!payeeData || typeof payeeData.offchainId !== "string" || payeeData.offchainId.length === 0) {
+    throw new Error(`payeeData[${index}] must include a non-empty offchainId`);
+  }
+  return {
+    processorName,
+    offchainId: payeeData.offchainId,
+    telegramUsername: payeeData.telegramUsername,
+    metadata: payeeData.metadata
+  };
+}
 var Zkp2pClient = class {
   /**
    * Creates a new Zkp2pClient instance.
@@ -6704,7 +6864,9 @@ var Zkp2pClient = class {
      * sending fiat payment to the deposit's payee.
      *
      * If `gatingServiceSignature` is not provided, the SDK will automatically
-     * fetch one from the API (requires `apiKey` or `authorizationToken`).
+     * fetch one from curator `/v3/intent/sign` when `apiKey` or `authorizationToken`
+     * is available. Otherwise you must provide `gatingServiceSignature` and
+     * `signatureExpiration` yourself.
      *
      * **Prepare Mode**: Use `.prepare()` to get the transaction calldata without sending:
      * ```typescript
@@ -8016,42 +8178,32 @@ var Zkp2pClient = class {
    * register maker payment details with the curator service.
    *
    * @param params.processorNames - Payment platforms (e.g., ['wise', 'revolut'])
-   * @param params.depositData - Payee details per processor (e.g., [{ email: '...' }])
+   * @param params.payeeData - Payee details per processor (e.g., [{ offchainId: 'you@example.com' }]). Required when the SDK needs to register payee details with the curator.
    * @returns The posted deposit details and their corresponding hashed on-chain IDs
    *
    * @example
    * ```typescript
    * const { hashedOnchainIds } = await client.registerPayeeDetails({
    *   processorNames: ['wise'],
-   *   depositData: [{ email: 'you@example.com' }],
+   *   payeeData: [{ offchainId: 'you@example.com' }],
    * });
    * // Then pass hashedOnchainIds to createDeposit
    * ```
    */
   async registerPayeeDetails(params) {
+    const payeeData = resolvePayeeDataInput(params, "registerPayeeDetails");
     if (!Array.isArray(params.processorNames) || params.processorNames.length === 0) {
       throw new Error("processorNames must be a non-empty array");
     }
-    if (params.processorNames.length !== params.depositData.length) {
-      throw new Error("processorNames and depositData length mismatch");
+    if (params.processorNames.length !== payeeData.length) {
+      throw new Error("processorNames and payeeData length mismatch");
     }
     const baseApiUrl = (this.baseApiUrl ?? "https://api.zkp2p.xyz").replace(/\/$/, "");
     const depositDetails = params.processorNames.map(
-      (processorName, index) => ({
-        processorName,
-        depositData: params.depositData[index] || {}
-      })
+      (processorName, index) => toPostDepositDetailsRequest(processorName, payeeData[index], index)
     );
     const apiResponses = await Promise.all(
-      depositDetails.map(
-        (req) => apiPostDepositDetails(
-          req,
-          baseApiUrl,
-          this.apiTimeoutMs,
-          this.apiKey,
-          this.authorizationToken
-        )
-      )
+      depositDetails.map((req) => apiPostDepositDetails(req, baseApiUrl, this.apiTimeoutMs))
     );
     if (!apiResponses.every((r) => r?.success)) {
       const failed = apiResponses.find((r) => !r?.success);
@@ -8075,16 +8227,17 @@ var Zkp2pClient = class {
    * @param params.amount - Total deposit amount in token units (6 decimals for USDC)
    * @param params.intentAmountRange - Min/max amount per intent
    * @param params.processorNames - Payment platforms to accept (e.g., ['wise', 'revolut'])
-   * @param params.depositData - Payee details per processor (e.g., [{ email: '...' }])
+   * @param params.payeeData - Payee details per processor (e.g., [{ offchainId: 'you@example.com' }])
    * @param params.conversionRates - Conversion rates per processor, grouped by currency
    * @param params.payeeDetailsHashes - Pre-computed hashed on-chain IDs (from registerPayeeDetails). When provided, skips the curator API call entirely.
    * @param params.delegate - Optional delegate address that can manage the deposit
    * @param params.intentGuardian - Optional guardian for intent approval
    * @param params.retainOnEmpty - Keep deposit active when balance reaches zero
    * @param params.txOverrides - Optional viem transaction overrides
-   * @returns The deposit details posted to API and the transaction hash
+   * @returns The deposit details posted to API (empty when payee registration is skipped) and the transaction hash
    *
-   * @throws Error if processorNames, depositData, and conversionRates lengths don't match
+   * @throws Error if processorNames, payeeData, and conversionRates lengths don't match
+   * @throws Error if payeeData is missing and neither payeeDetailsHashes nor full payment method overrides are provided
    * @throws Error if a currency is not supported by the specified processor
    *
    * @example
@@ -8095,7 +8248,7 @@ var Zkp2pClient = class {
    *   amount: 1000_000000n,
    *   intentAmountRange: { min: 10_000000n, max: 500_000000n },
    *   processorNames: ['wise'],
-   *   depositData: [{ email: 'you@example.com' }],
+   *   payeeData: [{ offchainId: 'you@example.com' }],
    *   conversionRates: [[
    *     { currency: 'USD', conversionRate: '1020000000000000000' }, // 1.02
    *     { currency: 'EUR', conversionRate: '1100000000000000000' }, // 1.10
@@ -8128,24 +8281,30 @@ var Zkp2pClient = class {
     };
   }
   async prepareCreateDepositInternal(params) {
+    const hasOverrides = Boolean(
+      params.paymentMethodsOverride || params.paymentMethodDataOverride || params.currenciesOverride
+    );
+    const payeeDetailsHashes = params.payeeDetailsHashes;
+    const hasPayeeHashes = payeeDetailsHashes !== void 0;
+    const shouldResolvePayeeData = params.payeeData !== void 0 || params.depositData !== void 0;
+    const payeeData = shouldResolvePayeeData ? resolvePayeeDataInput(params, "createDeposit") : null;
     if (!Array.isArray(params.processorNames) || params.processorNames.length === 0) {
       throw new Error("processorNames must be a non-empty array");
     }
     if (params.processorNames.length !== params.conversionRates.length) {
       throw new Error("processorNames and conversionRates length mismatch");
     }
-    if (params.processorNames.length !== params.depositData.length) {
-      throw new Error("processorNames and depositData length mismatch");
+    if (payeeData && params.processorNames.length !== payeeData.length) {
+      throw new Error("processorNames and payeeData length mismatch");
     }
-    const depositDetails = params.processorNames.map(
-      (processorName, index) => ({
-        processorName,
-        depositData: params.depositData[index] || {}
-      })
-    );
-    const hasOverrides = Boolean(
-      params.paymentMethodsOverride || params.paymentMethodDataOverride || params.currenciesOverride
-    );
+    if (!hasOverrides && !hasPayeeHashes && !payeeData) {
+      throw new Error(
+        "createDeposit requires payeeData unless payeeDetailsHashes or full payment method overrides are provided"
+      );
+    }
+    const depositDetails = payeeData ? params.processorNames.map(
+      (processorName, index) => toPostDepositDetailsRequest(processorName, payeeData[index], index)
+    ) : [];
     let paymentMethods;
     let paymentMethodData;
     let currencies;
@@ -8170,23 +8329,15 @@ var Zkp2pClient = class {
       );
       const intentGatingService = getGatingServiceAddress(this.chainId, this.runtimeEnv);
       let hashedOnchainIds;
-      if (params.payeeDetailsHashes) {
-        if (params.payeeDetailsHashes.length !== params.processorNames.length) {
+      if (payeeDetailsHashes !== void 0) {
+        if (payeeDetailsHashes.length !== params.processorNames.length) {
           throw new Error("payeeDetailsHashes length must match processorNames length");
         }
-        hashedOnchainIds = params.payeeDetailsHashes;
+        hashedOnchainIds = payeeDetailsHashes;
       } else {
         const baseApiUrl = (this.baseApiUrl ?? "https://api.zkp2p.xyz").replace(/\/$/, "");
         const apiResponses = await Promise.all(
-          depositDetails.map(
-            (req) => apiPostDepositDetails(
-              req,
-              baseApiUrl,
-              this.apiTimeoutMs,
-              this.apiKey,
-              this.authorizationToken
-            )
-          )
+          depositDetails.map((req) => apiPostDepositDetails(req, baseApiUrl, this.apiTimeoutMs))
         );
         if (!apiResponses.every((r) => r?.success)) {
           const failed = apiResponses.find((r) => !r?.success);
@@ -8383,12 +8534,64 @@ var Zkp2pClient = class {
     const quotes = quote?.responseObject?.quotes ?? [];
     for (const q of quotes) {
       const maker = q?.maker;
-      if (maker?.depositData && typeof q === "object") {
-        q.payeeData = maker.depositData;
+      const payeeData = normalizeQuotePayeeData(maker);
+      if (payeeData && typeof q === "object") {
+        q.payeeData = payeeData;
       }
     }
     return appendReferrerFeeDisplayFields(quote, referrerFeeConfig);
   }
+  /**
+   * **Supporting Method** - Fetches the best available quote per supported payment platform.
+   *
+   * Returns one quote per platform when available. When authenticated, the API
+   * returns payee details in each platform's best quote.
+   *
+   * @param req - Best-by-platform quote request parameters
+   * @param opts - Optional overrides for API URL and timeout
+   * @returns Best-by-platform quote response
+   */
+  async getQuotesBestByPlatform(req, opts) {
+    const referrerFeeConfig = assertValidReferrerFeeConfig(
+      req.referrerFeeConfig,
+      "getQuotesBestByPlatform"
+    );
+    const baseApiUrl = (opts?.baseApiUrl ?? this.baseApiUrl ?? "https://api.zkp2p.xyz").replace(
+      /\/$/,
+      ""
+    );
+    const timeoutMs = opts?.timeoutMs ?? this.apiTimeoutMs;
+    const reqWithEscrow = { ...req };
+    if (!reqWithEscrow.escrowAddresses || reqWithEscrow.escrowAddresses.length === 0) {
+      const configuredEscrows = this.escrowAddresses.length > 0 ? [...this.escrowAddresses] : this.escrowAddress ? [this.escrowAddress] : [];
+      if (configuredEscrows.length > 0) {
+        reqWithEscrow.escrowAddresses = configuredEscrows;
+      }
+    }
+    const quote = await apiGetQuotesBestByPlatform(
+      reqWithEscrow,
+      baseApiUrl,
+      timeoutMs,
+      this.apiKey,
+      this.authorizationToken
+    );
+    const enrichedQuote = quote ? {
+      ...quote,
+      responseObject: {
+        ...quote.responseObject,
+        platformQuotes: (quote.responseObject?.platformQuotes ?? []).map((platformQuote) => {
+          const bestQuote = platformQuote?.bestQuote;
+          const payeeData = normalizeQuotePayeeData(bestQuote?.maker);
+          if (!bestQuote || !payeeData) return platformQuote;
+          return {
+            ...platformQuote,
+            bestQuote: { ...bestQuote, payeeData }
+          };
+        })
+      }
+    } : quote;
+    return appendReferrerFeeDisplayFieldsToBestByPlatform(enrichedQuote, referrerFeeConfig);
+  }
   // ───────────────────────────────────────────────────────────────────────────
   // SUPPORTING: TAKER TIER
   // (Used by frontends to display taker limits)
@@ -8408,7 +8611,7 @@ var Zkp2pClient = class {
       ""
     );
     const timeoutMs = opts?.timeoutMs ?? this.apiTimeoutMs;
-    return apiGetTakerTier(req, this.apiKey, baseApiUrl, timeoutMs);
+    return apiGetTakerTier(req, void 0, baseApiUrl, timeoutMs);
   }
   // ╔═══════════════════════════════════════════════════════════════════════════╗
   // ║ CORE: ON-CHAIN DEPOSIT VIEWS                                             ║
@@ -8838,6 +9041,7 @@ exports.ZKP2P_IOS_REFERRER = ZKP2P_IOS_REFERRER;
 exports.Zkp2pClient = Zkp2pClient;
 exports.apiGetOwnerDeposits = apiGetOwnerDeposits;
 exports.apiGetPayeeDetails = apiGetPayeeDetails;
+exports.apiGetQuotesBestByPlatform = apiGetQuotesBestByPlatform;
 exports.apiGetTakerTier = apiGetTakerTier;
 exports.apiPostDepositDetails = apiPostDepositDetails;
 exports.apiValidatePayeeDetails = apiValidatePayeeDetails;