@zkp2p/sdk 0.2.3 → 0.3.0

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.1.0`
+Current version: `0.2.3`
 
 ## Why This SDK
 
@@ -29,7 +29,7 @@ Current version: `0.1.0`
 - RPC-first reads: primary reads use ProtocolViewer and on-chain fallbacks, so `getDeposits()`, `getDeposit()`, `getIntents()`, `getIntent()`, and the `getPv*` methods are not blocked on indexer lag.
 - Indexer for history and filtering: use `client.indexer.*` for pagination, historical volumes, fund activities, daily snapshots, and vault analytics.
 - Current-stack routing: the client resolves against the upgraded escrow and orchestrator contracts, with historical escrow lookups available for reads and legacy deposits.
-- Modular internals: stable `0.1.0` extracted intent, vault, and ProtocolViewer logic into `IntentOperations`, `VaultOperations`, and `ProtocolViewerReader`, keeping `Zkp2pClient` focused on orchestration.
+- Modular internals: intent, vault, and ProtocolViewer logic are extracted into `IntentOperations`, `VaultOperations`, and `ProtocolViewerReader`, keeping `Zkp2pClient` focused on orchestration.
 - App-level rollout control: the SDK is capability-based. Product gating and phase flags belong in your app layer, not inside transaction helpers.
 
 ## Installation
@@ -72,10 +72,14 @@ const client = new Zkp2pClient({
 
 - Supported runtime environments: `'production'`, `'preproduction'`, `'staging'`
 - `runtimeEnv` default: `'production'`
-- `apiKey`: optional curator API key for authenticated service endpoints
+- `rpcUrl`: optional RPC URL override (defaults to wallet's chain RPC)
+- `apiKey`: optional curator-issued API key — used when the SDK auto-fetches `signalIntent()` gating signatures and enables richer authenticated `getQuote()` responses with maker `depositData`; curator may also attach `skipTierEnforce` to trusted keys on hybrid intent-signing endpoints
 - `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 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` when `apiKey` or `authorizationToken` is available; otherwise provide both `gatingServiceSignature` and `signatureExpiration` manually if your integration needs one. Authenticated quotes also include richer maker `depositData`, and curator-issued API keys may carry `skipTierEnforce` on hybrid intent-signing endpoints.
 
 Indexer defaults by environment:
 
@@ -85,20 +89,20 @@ Indexer defaults by environment:
 
 ## Core Capabilities
 
-| Area                           | Stable surface                                                                                                                                                                                                                           |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Deposits                       | `createDeposit`, `addFunds`, `removeFunds`, `withdrawDeposit`, `ensureAllowance`, `setAcceptingIntents`, `setIntentRange`, `setCurrencyMinRate`, `setRetainOnEmpty`                                                                      |
-| 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`                                                                                                                                                                   |
-| 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`                                    |
-| RPC reads                      | `getDeposits`, `getDeposit`, `getDepositsById`, `getIntents`, `getIntent`, `getPvDepositById`, `getPvDepositsFromIds`, `getPvAccountDeposits`, `getPvAccountIntents`, `getPvIntent`                                                      |
-| Indexer                        | `client.indexer.getDeposits`, `getDepositsWithRelations`, `getDepositById`, `getIntentFulfillmentAmounts`, `getDepositFundActivities`, `getDepositDailySnapshots`, `getRateManagers`, `getRateManagerDetail`, `getManagerDailySnapshots` |
-| React hooks                    | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, payment methods, and taker tier                                                                                                                              |
-| Attribution                    | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support                                                                                                                      |
+| Area                           | Stable surface                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deposits                       | `createDeposit`, `addFunds`, `removeFunds`, `withdrawDeposit`, `ensureAllowance`, `setAcceptingIntents`, `setIntentRange`, `setCurrencyMinRate`, `setRetainOnEmpty`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| 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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| 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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| RPC reads                      | `getDeposits`, `getDeposit`, `getDepositsById`, `getIntents`, `getIntent`, `getPvDepositById`, `getPvDepositsFromIds`, `getPvAccountDeposits`, `getPvAccountIntents`, `getPvIntent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Indexer                        | `client.indexer.getDeposits`, `getDepositsWithRelations`, `getDepositById`, `getDepositsByIds`, `getDepositsByIdsWithRelations`, `getDepositsByPayeeHash`, `getIntentsForDeposits`, `getOwnerIntents`, `getIntentsByRateManager`, `getIntentByHash`, `getExpiredIntents`, `getFulfilledIntentEvents`, `getIntentFulfillmentAmounts`, `getFulfillmentAndPayment`, `getDepositFundActivities`, `getMakerFundActivities`, `getDepositDailySnapshots`, `getProfitSnapshotsByDeposits`, `getRateManagers`, `getRateManagerDetail`, `getRateManagerDelegations`, `getDelegationForDeposit`, `getManagerDailySnapshots`, `getManualRateUpdates`, `getOracleConfigUpdates`, `query` |
+| React hooks                    | `@zkp2p/sdk/react` exports hooks for deposits, intents, delegation, vaults, payment methods, and taker tier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Attribution                    | ERC-8021 helpers like `sendTransactionWithAttribution`, `encodeWithAttribution`, and `txOverrides.referrer` support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Create a Deposit
 
@@ -385,35 +389,77 @@ You can also use the convenience wrappers `getDeposits()`, `getDeposit()`, `getI
 
 ## Indexer Queries
 
-Use the indexer for filtered queries, pagination, fund activity history, snapshots, and vault analytics.
+Use the indexer for filtered queries, pagination, fund activity history, snapshots, and vault analytics. All methods live on the flat `client.indexer.*` namespace.
 
 ```ts
+// Deposit queries
 const deposits = await client.indexer.getDeposits(
   { status: 'ACTIVE', depositor: '0xMaker' },
   { limit: 25, orderBy: 'updatedAt', orderDirection: 'desc' },
 );
-
-const depositWithRelations = await client.indexer.getDepositById('8453_0xEscrowAddress_42', {
+const depositsWithRelations = await client.indexer.getDepositsWithRelations(
+  { status: 'ACTIVE' },
+  { limit: 10 },
+  { includeIntents: true },
+);
+const deposit = await client.indexer.getDepositById('8453_0xEscrowAddress_42', {
+  includeIntents: true,
+});
+const depositsByIds = await client.indexer.getDepositsByIds(['8453_0xEscrow_42']);
+const depositsByIdsWithRelations = await client.indexer.getDepositsByIdsWithRelations(
+  ['8453_0xEscrow_42'],
+  { includeIntents: true },
+);
+const depositsByPayee = await client.indexer.getDepositsByPayeeHash('0xPayeeHash', {
+  paymentMethodHash: '0x...',
+  limit: 10,
   includeIntents: true,
 });
 
+// Intent queries
+const intentsForDeposits = await client.indexer.getIntentsForDeposits(
+  ['8453_0xEscrow_42'],
+  ['SIGNALED'],
+);
+const ownerIntents = await client.indexer.getOwnerIntents('0xTaker', ['SIGNALED', 'FULFILLED']);
+const intentsByVault = await client.indexer.getIntentsByRateManager('0xVaultId');
+const intent = await client.indexer.getIntentByHash('0xIntentHash');
+const expiredIntents = await client.indexer.getExpiredIntents({
+  now: BigInt(Math.floor(Date.now() / 1000)),
+  depositIds: ['8453_0xEscrow_42'],
+});
+const fulfilledEvents = await client.indexer.getFulfilledIntentEvents(['0xIntentHash']);
 const fulfillment = await client.indexer.getIntentFulfillmentAmounts('0xIntentHash');
+const fulfillmentAndPayment = await client.indexer.getFulfillmentAndPayment('0xIntentHash');
+
+// Fund activity and snapshots
 const fundActivities = await client.indexer.getDepositFundActivities('8453_0xEscrowAddress_42');
+const makerActivities = await client.indexer.getMakerFundActivities('0xMaker', 50);
 const snapshots = await client.indexer.getDepositDailySnapshots('8453_0xEscrowAddress_42', 30);
+const profitSnapshots = await client.indexer.getProfitSnapshotsByDeposits(['8453_0xEscrow_42']);
 
+// Rate manager (vault) queries
 const managers = await client.indexer.getRateManagers({
   limit: 10,
   orderBy: 'currentDelegatedBalance',
   orderDirection: 'desc',
 });
-
 const managerDetail = await client.indexer.getRateManagerDetail('0xVaultId', {
   rateManagerAddress: '0xVaultAddress',
+  statsLimit: 30,
+});
+const delegations = await client.indexer.getRateManagerDelegations('0xVaultId');
+const delegation = await client.indexer.getDelegationForDeposit('8453_0xEscrow_42');
+const managerSnapshots = await client.indexer.getManagerDailySnapshots('0xVaultId');
+const manualRates = await client.indexer.getManualRateUpdates('0xVaultId');
+const oracleUpdates = await client.indexer.getOracleConfigUpdates('0xVaultId');
+
+// Raw GraphQL
+const custom = await client.indexer.query<MyType>({
+  query: '{ deposits(limit: 5) { id } }',
 });
 ```
 
-`managerDetail?.aggregate` gives you current delegated balance and filled volume stats alongside recent snapshots and delegation history.
-
 ## React Hooks
 
 Install React and import hooks from `@zkp2p/sdk/react`. React is an optional peer dependency of the SDK.
@@ -494,7 +540,7 @@ const hash = await client.signalIntent({
 });
 ```
 
-Lower-level helpers are also exported: `BASE_BUILDER_CODE`, `getAttributionDataSuffix()`, `appendAttributionToCalldata()`, `encodeWithAttribution()`, and `sendTransactionWithAttribution()`.
+Lower-level helpers are also exported: `BASE_BUILDER_CODE`, `ZKP2P_IOS_REFERRER`, `ZKP2P_ANDROID_REFERRER`, `getAttributionDataSuffix()`, `appendAttributionToCalldata()`, `encodeWithAttribution()`, and `sendTransactionWithAttribution()`.
 
 ## TypeDoc API Reference
 

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) {
@@ -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;
+  const referralFees = json?.responseObject?.intentData?.referralFees ?? json?.responseObject?.referralFees;
   if (!sig || !expStr) throw new Error("v3/intent 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 returned invalid referral fee recipient");
+          }
+          let fee;
+          try {
+            fee = BigInt(referralFee.fee);
+          } catch {
+            throw new Error("v3/intent returned non-integer referral fee value");
+          }
+          return {
+            recipient: referralFee.recipient,
+            fee
+          };
+        });
+      }
     }
     if (!gatingServiceSignature || !signatureExpiration) {
       throw new Error("Missing gatingServiceSignature/signatureExpiration");
@@ -3461,6 +3481,7 @@ var DEPOSIT_FIELDS = `
   timestamp
   txHash
   updatedAt
+  whitelistHookAddress
 `;
 var LEGACY_DEPOSIT_FIELDS = `
   id
@@ -4451,6 +4472,35 @@ var DEPOSIT_DAILY_SNAPSHOTS_QUERY = (
   }
 `
 );
+var PROFIT_SNAPSHOTS_BY_DEPOSITS_QUERY = (
+  /* GraphQL */
+  `
+  query GetProfitSnapshotsByDeposits($depositIds: [String!]) {
+    profitSnapshots: MakerProfitSnapshot(
+      where: { depositId: { _in: $depositIds } }
+      order_by: { createdAt: desc }
+    ) {
+      id
+      chainId
+      maker
+      intentId
+      depositId
+      fiatCurrency
+      quoteConversionRate
+      oracleRate
+      spreadBps
+      amount
+      notionalFiatUsdCents
+      feeUsd
+      realizedProfitUsdCents
+      priceSnapshotId
+      status
+      createdAt
+      updatedAt
+    }
+  }
+`
+);
 var FULFILLMENT_AND_PAYMENT_QUERY = (
   /* GraphQL */
   `
@@ -4560,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 && 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) {
@@ -4678,14 +4729,16 @@ var IndexerDepositService = class {
     const where = {};
     if (params.depositIds?.length) where.depositId = { _in: params.depositIds };
     if (params.owner) where.owner = { _ilike: params.owner };
+    if (params.rateManagerId) where.rateManagerId = { _ilike: params.rateManagerId };
     if (params.statuses?.length) where.status = { _in: params.statuses };
     if (!Object.keys(where).length) return [];
+    const orderByField = params.orderByField ?? "signalTimestamp";
     const result = await this.queryWithLegacyFallback({
       query: INTENTS_QUERY,
       legacyQuery: LEGACY_INTENTS_QUERY,
       variables: {
         where,
-        order_by: [{ signalTimestamp: "desc" }],
+        order_by: [{ [orderByField]: "desc" }],
         limit: params.limit,
         offset: params.offset
       }
@@ -4748,6 +4801,16 @@ var IndexerDepositService = class {
     if (!owner) return [];
     return this.fetchIntents({ owner, statuses });
   }
+  async fetchIntentsByRateManager(rateManagerId, statuses) {
+    const normalizedRateManagerId = rateManagerId?.trim();
+    if (!normalizedRateManagerId) return [];
+    return this.fetchIntents({
+      rateManagerId: normalizedRateManagerId,
+      statuses,
+      limit: 500,
+      orderByField: "fulfillTimestamp"
+    });
+  }
   async fetchIntentByHash(intentHash) {
     if (!intentHash) return null;
     const result = await this.queryWithLegacyFallback({
@@ -4969,6 +5032,26 @@ var IndexerDepositService = class {
       return [];
     }
   }
+  async fetchProfitSnapshotsByDeposits(depositIds) {
+    const normalizedDepositIds = Array.from(
+      new Set(
+        depositIds.map((depositId) => depositId?.trim()).filter((depositId) => Boolean(depositId))
+      )
+    );
+    if (!normalizedDepositIds.length) return [];
+    try {
+      const result = await this.client.query({
+        query: PROFIT_SNAPSHOTS_BY_DEPOSITS_QUERY,
+        variables: { depositIds: normalizedDepositIds }
+      });
+      return result.profitSnapshots ?? result.MakerProfitSnapshot ?? [];
+    } catch (error) {
+      if (!isSchemaCompatibilityError(error)) {
+        throw error;
+      }
+      return [];
+    }
+  }
 };
 
 // src/indexer/rateManagerService.ts
@@ -5865,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`,
     method: "POST",
     body: req,
-    apiKey,
-    authToken,
     timeoutMs
   });
 }
@@ -5881,13 +5962,25 @@ 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
@@ -5902,6 +5995,29 @@ 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}`,
@@ -5968,7 +6084,6 @@ async function apiGetTakerTier(req, apiKey, baseApiUrl, timeoutMs) {
   return apiFetch({
     url: `${withApiBase(baseApiUrl)}${endpoint}`,
     method: "GET",
-    apiKey,
     timeoutMs
   });
 }
@@ -6070,6 +6185,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 = [
@@ -6642,7 +6774,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` 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
@@ -7766,6 +7900,12 @@ var Zkp2pClient = class {
       getOwnerIntents: (owner, statuses) => {
         return service.fetchIntentsByOwner(owner, statuses);
       },
+      /**
+       * Fetches fulfilled intents for a vault by rate manager ID.
+       */
+      getIntentsByRateManager: (rateManagerId, statuses) => {
+        return service.fetchIntentsByRateManager(rateManagerId, statuses);
+      },
       /**
        * Fetches a single intent by hash.
        */
@@ -7816,6 +7956,12 @@ var Zkp2pClient = class {
       getDepositsByIdsWithRelations: (ids, options) => {
         return service.fetchDepositsByIdsWithRelations(ids, options);
       },
+      /**
+       * Fetches maker profit snapshots for the provided deposits.
+       */
+      getProfitSnapshotsByDeposits: (depositIds) => {
+        return service.fetchProfitSnapshotsByDeposits(depositIds);
+      },
       /**
        * Fetches rate managers (vaults) with aggregate stats.
        */
@@ -7969,15 +8115,7 @@ var Zkp2pClient = class {
       })
     );
     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);
@@ -8104,15 +8242,7 @@ var Zkp2pClient = class {
       } 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);
@@ -8315,6 +8445,57 @@ var Zkp2pClient = class {
     }
     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 makerDepositData = bestQuote?.maker?.depositData;
+          if (!bestQuote || !makerDepositData) return platformQuote;
+          return {
+            ...platformQuote,
+            bestQuote: { ...bestQuote, payeeData: makerDepositData }
+          };
+        })
+      }
+    } : quote;
+    return appendReferrerFeeDisplayFieldsToBestByPlatform(enrichedQuote, referrerFeeConfig);
+  }
   // ───────────────────────────────────────────────────────────────────────────
   // SUPPORTING: TAKER TIER
   // (Used by frontends to display taker limits)
@@ -8334,7 +8515,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                                             ║
@@ -8764,6 +8945,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;