From 512943d0c58c1fa97f79fc8f16b516d1056e9dd5 Mon Sep 17 00:00:00 2001 From: Richard Liang Date: Wed, 24 Jun 2026 19:21:43 +0000 Subject: [PATCH] Document SDK 0.5.7 quote auth --- .../integrate-zkp2p/integrate-redirect-onramp.md | 1 + developer/sdk/client-reference.md | 14 +++++++++++--- developer/sdk/overview.md | 2 +- static/onramp-llm.md | 4 ++-- 4 files changed, 15 insertions(+), 6 deletions(-) diff --git a/developer/integrate-zkp2p/integrate-redirect-onramp.md b/developer/integrate-zkp2p/integrate-redirect-onramp.md index 19edb94..468da7e 100644 --- a/developer/integrate-zkp2p/integrate-redirect-onramp.md +++ b/developer/integrate-zkp2p/integrate-redirect-onramp.md @@ -34,6 +34,7 @@ You need: - `@zkp2p/sdk` `0.5.0` or newer installed in your web app — `0.5.0` is the first release that ships the headless `peerExtensionSdk`; `0.4.x` only exposes the removed deeplink wrapper - `@zkp2p/sdk` `0.5.2` or newer if your integration also performs Venmo identity registration through `register_venmo` +- `@zkp2p/sdk` `0.5.7` or newer if your quote flow uses authenticated curator behavior such as private orderbooks or internal quote preferences - The Peer extension installed and connected for the current origin - A `Zkp2pClient` configured for the chain and runtime - An intent your app already created or selected diff --git a/developer/sdk/client-reference.md b/developer/sdk/client-reference.md index df92a0d..dae375f 100644 --- a/developer/sdk/client-reference.md +++ b/developer/sdk/client-reference.md @@ -25,7 +25,7 @@ Create a client with `new Zkp2pClient(opts)`. | `runtimeEnv` | No | Runtime environment: `production`, `preproduction`, or `staging`. Defaults to `production` | | `indexerUrl` | No | Override for the indexer GraphQL endpoint | | `baseApiUrl` | No | Override for ZKP2P service APIs | -| `apiKey` | No | Optional curator API key — not required to get started. When provided, it enables auto-fetching `signalIntent()` gating signatures and enriches authenticated quote responses with maker `payeeData` | +| `apiKey` | No | Optional curator API key — not required to get started. When provided, the SDK forwards it as `x-api-key` for authenticated quote APIs, enables auto-fetching `signalIntent()` gating signatures, and enriches quote responses with maker `payeeData` | | `authorizationToken` | No | Optional bearer token for hybrid authentication | | `getAuthorizationToken` | No | Async token provider for long-lived clients | | `indexerApiKey` | No | Optional `x-api-key` header for indexer proxy authentication | @@ -41,7 +41,7 @@ const client = new Zkp2pClient({ ``` :::info No API key required -Most public SDK methods work without `apiKey` or `authorizationToken`. Auth credentials are optional for normal deposit, quote, and intent flows and mostly affect response richness. `signalIntent()` can auto-fetch its gating signature when you provide `apiKey` or `authorizationToken`; if you do not want the SDK to make that request, pass `gatingServiceSignature` and `signatureExpiration` yourself. +Most public SDK methods work without `apiKey` or `authorizationToken`. Auth credentials are optional for normal public deposit, quote, and intent flows. Configure `apiKey` when you need authenticated curator quote behavior, such as private orderbook lookups or quote preferences scoped to internal flows. `signalIntent()` can auto-fetch its gating signature when you provide `apiKey` or `authorizationToken`; if you do not want the SDK to make that request, pass `gatingServiceSignature` and `signatureExpiration` yourself. ::: :::note Service roots @@ -49,7 +49,7 @@ Set `baseApiUrl` to the service root, for example `https://api.zkp2p.xyz`. Do no ::: :::note Runtime requirements -The published `0.5.2` package declares `node >= 22` for Node runtimes and `viem ^2.37.3` as a peer dependency. `0.5.2` depends on `@zkp2p/zkp2p-attestation@1.5.1`, which is the first attestation package version that supports the current Venmo identity registration shape. +The published `0.5.7` package declares `node >= 22` for Node runtimes and `viem ^2.37.3` as a peer dependency. `0.5.7` depends on `@zkp2p/zkp2p-attestation@1.6.3`, which includes the browser and extension fetch binding fix while preserving the current Venmo identity registration shape introduced in `1.5.1`. ::: ## Prepared transactions @@ -357,6 +357,10 @@ Use `getQuote(req, opts?)` to fetch available liquidity for a taker flow. | `nearbyQuotesCount` | No | Number of nearby suggestions above and below | | `includePrivateOrderbooks` | No | Include whitelist-gated private orderbook deposits scoped to the requesting user | +:::note Authenticated quote requests +Starting in `@zkp2p/sdk@0.5.7`, `getQuote()` forwards the client's `apiKey` as `x-api-key` to curator. Pass `apiKey` when using authenticated quote options such as `includePrivateOrderbooks: true` or internal quote preferences like `quotePreference: 'EXCLUSIVE_SAR'`. Public quote behavior is unchanged when no `apiKey` is configured. +::: + The response includes: - `responseObject.quotes`: matched quotes @@ -399,6 +403,10 @@ Use `getQuotesBestByPlatform(req, opts?)` when you want the single best quote pe | `intentGatingService` | No | Filter by a specific intent gating service address | | `includePrivateOrderbooks` | No | Include whitelist-gated private orderbook deposits. Defaults to `false` | +:::note Authenticated quote requests +Starting in `@zkp2p/sdk@0.5.7`, `getQuotesBestByPlatform()` forwards the client's `apiKey` as `x-api-key` to curator. Pass `apiKey` when using authenticated quote options such as `includePrivateOrderbooks: true` or internal quote preferences like `quotePreference: 'EXCLUSIVE_SAR'`. Public quote behavior is unchanged when no `apiKey` is configured. +::: + The response shape mirrors `getQuote` but is keyed by platform: - `responseObject.platformQuotes`: array of `{ platform, bestQuote }` entries diff --git a/developer/sdk/overview.md b/developer/sdk/overview.md index 0083782..6017b96 100644 --- a/developer/sdk/overview.md +++ b/developer/sdk/overview.md @@ -8,7 +8,7 @@ slug: /sdk ## What this does -`@zkp2p/sdk` is the TypeScript SDK for building with Peer. Use it to manage deposits, signal and fulfill intents, access quote and taker-tier APIs, work with vault and rate-manager flows, run Peer extension headless metadata capture, request identity attestations, and integrate Seller Autopilot. The current npm release is `0.5.2` and is published under the MIT license. +`@zkp2p/sdk` is the TypeScript SDK for building with Peer. Use it to manage deposits, signal and fulfill intents, access quote and taker-tier APIs, work with vault and rate-manager flows, run Peer extension headless metadata capture, request identity attestations, and integrate Seller Autopilot. The current npm release is `0.5.7` and is published under the MIT license. ## Who is this for? diff --git a/static/onramp-llm.md b/static/onramp-llm.md index e176bde..2410e4e 100644 --- a/static/onramp-llm.md +++ b/static/onramp-llm.md @@ -4,7 +4,7 @@ The app owns order UI, payment-row selection, and `fulfillIntent()`. The extensi ## 1. Initialize the SDK -Use a scoped extension instance and an app-owned `Zkp2pClient`. Require `@zkp2p/sdk` `0.5.0` or newer. +Use a scoped extension instance and an app-owned `Zkp2pClient`. Require `@zkp2p/sdk` `0.5.0` or newer for the headless extension surface, and `0.5.7` or newer for authenticated quote paths that rely on private orderbooks or internal quote preferences. ```ts import { @@ -289,7 +289,7 @@ async function verifyBuyerTeePaymentDirectly({ ## Key rules -- Target Peer extension manifest `0.6.0` or newer and `@zkp2p/sdk` `0.5.0` or newer — `0.4.x` only ships the removed deeplink wrapper. +- Target Peer extension manifest `0.6.0` or newer and `@zkp2p/sdk` `0.5.0` or newer — `0.4.x` only ships the removed deeplink wrapper. Use `@zkp2p/sdk` `0.5.7` or newer when authenticated quote options need the client's `apiKey` forwarded to curator as `x-api-key`. - Never use `onramp()`, `openSidebar()`, `onIntentFulfilled()`, `onProofComplete()`, or `callbackUrl` — the pre-`0.6.0` deeplink/side-panel API was removed. - Use `createPeerExtensionSdk({ window })`. - Register `onMetadataMessage()` before `authenticate()`.