@zkp2p/sdk 0.3.0 → 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-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
+- `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 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.
+**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

@@ -1460,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;
@@ -1472,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
         });
       }
@@ -1490,7 +1490,7 @@ async function apiSignIntentV3(request, opts) {
   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");
+  if (!sig || !expStr) throw new Error("v3/intent/sign missing signature or expiration");
   return {
     signature: sig,
     signatureExpiration: BigInt(expStr),
@@ -1967,13 +1967,13 @@ var IntentOperations = class {
       if (response.referralFees !== void 0) {
         referralFees = response.referralFees.map((referralFee) => {
           if (!isValidReferrerFeeRecipient(referralFee.recipient)) {
-            throw new Error("v3/intent returned invalid referral fee 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 returned non-integer referral fee value");
+            throw new Error("v3/intent/sign returned non-integer referral fee value");
           }
           return {
             recipient: referralFee.recipient,
@@ -5950,7 +5950,7 @@ function convertIndexerDepositToLegacyApiDeposit(deposit) {
 }
 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,
     timeoutMs
@@ -5983,7 +5983,8 @@ async function apiGetQuote(req, baseApiUrl, timeoutMs, apiKey, authToken) {
     [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({
@@ -6020,7 +6021,7 @@ async function apiGetQuotesBestByPlatform(req, baseApiUrl, timeoutMs, apiKey, au
 }
 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,
@@ -6029,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
@@ -6228,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.
@@ -6774,7 +6864,7 @@ var Zkp2pClient = class {
      * sending fiat payment to the deposit's payee.
      *
      * If `gatingServiceSignature` is not provided, the SDK will automatically
-     * fetch one from curator `/v3/intent` when `apiKey` or `authorizationToken`
+     * fetch one from curator `/v3/intent/sign` when `apiKey` or `authorizationToken`
      * is available. Otherwise you must provide `gatingServiceSignature` and
      * `signatureExpiration` yourself.
      *
@@ -8088,31 +8178,29 @@ 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))
@@ -8139,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
@@ -8159,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
@@ -8192,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;
@@ -8234,11 +8329,11 @@ 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(
@@ -8439,8 +8534,9 @@ 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);
@@ -8485,11 +8581,11 @@ var Zkp2pClient = class {
         ...quote.responseObject,
         platformQuotes: (quote.responseObject?.platformQuotes ?? []).map((platformQuote) => {
           const bestQuote = platformQuote?.bestQuote;
-          const makerDepositData = bestQuote?.maker?.depositData;
-          if (!bestQuote || !makerDepositData) return platformQuote;
+          const payeeData = normalizeQuotePayeeData(bestQuote?.maker);
+          if (!bestQuote || !payeeData) return platformQuote;
           return {
             ...platformQuote,
-            bestQuote: { ...bestQuote, payeeData: makerDepositData }
+            bestQuote: { ...bestQuote, payeeData }
           };
         })
       }