@zofai/zo-sdk 0.2.29 → 0.2.31

package/dist/traderPositions.mjs

@@ -0,0 +1,124 @@
+const DEFAULT_PAGE_LIMIT = 200;
+/**
+ * Parse `PositionName<collateral, index, LONG|SHORT>` from a Move type string.
+ */
+export function parsePositionNameType(positionNameType) {
+    const marker = 'PositionName<';
+    const start = positionNameType.indexOf(marker);
+    if (start < 0) {
+        return null;
+    }
+    const inner = positionNameType.slice(start + marker.length).split('>')[0];
+    if (!inner) {
+        return null;
+    }
+    const parts = inner.split(',').map(part => part.trim());
+    if (parts.length < 3) {
+        return null;
+    }
+    return {
+        symbol0: parts[0],
+        symbol1: parts[1],
+        long: parts[2].includes('LONG'),
+    };
+}
+function tokenKeyToMoveType(tokenKey, consts) {
+    const key = tokenKey.toLowerCase();
+    if (key === 'sui') {
+        return '0x2::sui::SUI';
+    }
+    const coin = consts.coins[key];
+    return coin?.module ?? null;
+}
+/** Map an indexed trader position row to PositionCap lookup fields for on-chain hydration. */
+export function traderPositionToCapInfo(record, consts) {
+    if (!record.positionId) {
+        return null;
+    }
+    const fromType = record.positionNameType
+        ? parsePositionNameType(record.positionNameType)
+        : null;
+    if (fromType) {
+        return {
+            positionCapId: record.positionId,
+            symbol0: fromType.symbol0,
+            symbol1: fromType.symbol1,
+            long: fromType.long,
+        };
+    }
+    const collateral = record.collateralToken?.trim().toLowerCase();
+    const index = record.indexToken?.trim().toLowerCase();
+    if (!collateral || !index) {
+        return null;
+    }
+    const symbol0 = tokenKeyToMoveType(collateral, consts);
+    const symbol1 = tokenKeyToMoveType(index, consts);
+    if (!symbol0 || !symbol1) {
+        return null;
+    }
+    return {
+        positionCapId: record.positionId,
+        symbol0,
+        symbol1,
+        long: (record.direction?.toUpperCase() ?? 'LONG') === 'LONG',
+    };
+}
+export async function fetchTraderPositionsPage(apiEndpoint, query) {
+    if (!apiEndpoint) {
+        throw new Error('apiEndpoint is required to fetch trader positions');
+    }
+    const params = new URLSearchParams({
+        owner: query.owner.trim().toLowerCase(),
+    });
+    if (query.status) {
+        params.set('status', query.status);
+    }
+    if (query.indexToken) {
+        params.set('indexToken', query.indexToken.trim().toLowerCase());
+    }
+    if (query.collateralToken) {
+        params.set('collateralToken', query.collateralToken.trim().toLowerCase());
+    }
+    if (query.limit != null) {
+        params.set('limit', String(query.limit));
+    }
+    if (query.offset != null) {
+        params.set('offset', String(query.offset));
+    }
+    const url = `${apiEndpoint.replace(/\/$/, '')}/trader-positions?${params}`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' },
+    });
+    const body = await res.json();
+    if (!res.ok || !body.success || !body.data) {
+        throw new Error(body.error || body.message || `Failed to fetch trader positions (${res.status})`);
+    }
+    return body.data;
+}
+/** Fetch all pages matching the query (respects optional total `limit`). */
+export async function fetchAllTraderPositions(apiEndpoint, query, maxRows) {
+    const rows = [];
+    let offset = 0;
+    let total = Number.POSITIVE_INFINITY;
+    while (offset < total) {
+        const remaining = maxRows != null ? maxRows - rows.length : DEFAULT_PAGE_LIMIT;
+        if (remaining <= 0) {
+            break;
+        }
+        const pageLimit = Math.min(DEFAULT_PAGE_LIMIT, remaining);
+        const { positions, pagination } = await fetchTraderPositionsPage(apiEndpoint, {
+            ...query,
+            limit: pageLimit,
+            offset,
+        });
+        rows.push(...positions);
+        total = pagination.total;
+        offset += positions.length;
+        if (positions.length === 0 || offset >= total) {
+            break;
+        }
+    }
+    return maxRows != null ? rows.slice(0, maxRows) : rows;
+}
+//# sourceMappingURL=traderPositions.mjs.map

package/dist/traderPositions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"traderPositions.mjs","sourceRoot":"","sources":["../src/traderPositions.ts"],"names":[],"mappings":"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"}

package/docs/api-reference.md

@@ -22,10 +22,55 @@
 - **LP-specific**: `IZLPAPI`, `ISLPAPI`, `IUSDZAPI` for typed usage
 - **Data types**: `IBaseMarketValuationInfo`, `IBaseVaultInfo`, `IBaseSymbolInfo`, `IBasePositionInfo`, `IBaseOrderInfo`, etc.
 
+## Pyth Pro helpers (all APIs)
+
+Available on ZLP / SLP / USDZ API (and DataAPI via the shared oracle base):
+
+| Method | Purpose |
+|--------|---------|
+| `fetchPythProUpdateBytesForTokens(tokens, options?)` | Fetch signed Pyth Pro update bytes for the given token symbols |
+| `getLatestPythProPricesForTokens(tokens, options?)` | Read latest Pyth Pro prices (off-chain; used by valuation) |
+| `initV3OracleTxb(tokens, tx?, options?)` | PTB: verify update + return `OracleInputs` |
+
+Default Pyth Pro channel is `fixed_rate@1000ms` (from zo-oracle config).
+
+## Recommended transaction methods
+
+### Liquidity (auto Pyth Pro valuation)
+
+| Method | Notes |
+|--------|-------|
+| `deposit` / `depositPtb` | Fetches valuation oracle internally |
+| `withdraw` / `withdrawPtb` / `withdrawLpCoinObject` | Same |
+
+### Swap (pass `pythProUpdateBytes`)
+
+| LP | Method | PTB |
+|----|--------|-----|
+| ZLP / USDZ | `swapV3` | `swapV3Ptb` |
+| SLP | `swapV4` | `swapV4Ptb` |
+
+### Trading (pass `pythProUpdateBytes`)
+
+| Action | Methods |
+|--------|---------|
+| Open | `openPositionV3`, `openPositionWithCoinV3`, `openPositionWithSCardV3`, `openPositionWithCoinAndSCardV3` |
+| Decrease | `decreasePositionV3`, `decreasePositionWithSCardV3` |
+| Redeem | ZLP / USDZ: `redeemFromPositionV2` · SLP: `redeemFromPositionV3` |
+
+### Valuation (DataAPI)
+
+| LP | Methods |
+|----|---------|
+| ZLP / USDZ | `valuate` (legacy) · `valuateV2` / `valuateVaultsV2` / `valuateSymbolsV2` (Pyth Pro PTB) |
+| SLP | `valuate` (legacy) · `valuateV3` / `valuateVaultsV3` / `valuateSymbolsV3` (Pyth Pro PTB) |
+| All | `valuateMarket()` – off-chain market valuation (SLP uses Pyth Pro + LST RR × SUI) |
+
 ## Source code
 
 - **Interfaces**: `src/interfaces/` – TypeScript interface definitions
 - **Implementations**: `src/implementations/` – Concrete API implementations
+- **Oracle Pro**: `src/oraclePro.ts`, `src/pythProClient.ts`, `src/storkClient.ts`
 - **Abstract classes**: `src/abstract/` – Shared base functionality
 - **Factory**: `src/factory/SDKFactory.ts` – SDK instance creation
 

package/docs/architecture.md

@@ -2,9 +2,9 @@
 
 The SDK supports multiple LP tokens through a unified interface:
 
-- **ZLP (ZO Liquidity Provider)**: Original ZO Protocol LP token
-- **SLP (Sudo Liquidity Provider)**: Sudo SDK-based LP token
-- **USDZ (USD Stablecoin)**: Stablecoin LP token
+- **ZLP (ZO Liquidity Provider)**: Original ZO Protocol LP token (`zo-core`)
+- **SLP (Sudo Liquidity Provider)**: Sudo SDK-based LP token (`sudo-core`)
+- **USDZ (USD Stablecoin)**: Stablecoin LP token (`zo-core` / USDZ package)
 
 ## Key Components
 
@@ -12,3 +12,21 @@ The SDK supports multiple LP tokens through a unified interface:
 2. **Abstract Base Classes**: Shared logic with delegation to DataAPI (`BaseAPI`, `BaseDataAPI`)
 3. **Concrete Implementations**: LP-specific functionality (`ZLPAPI`, `SLPAPI`, `USDZAPI`)
 4. **Factory Pattern**: Type-safe instance creation via `SDK` (e.g. `SDK.createZLPAPI()`)
+5. **Oracle Pro**: Shared Pyth Pro + Stork helpers (`oraclePro.ts`, `pythProClient.ts`, `storkClient.ts`, `deployments-zo-oracle-mainnet.json`)
+
+## Oracle upgrade (Pyth Pro + Stork)
+
+Newer market entrypoints no longer take per-token legacy Pyth feeder objects on the hot path. Instead:
+
+1. Client fetches **Pyth Pro update bytes** (`fetchPythProUpdateBytesForTokens`)
+2. PTB verifies them via `pyth_lazer::parse_and_verify_le_ecdsa_update_v2`
+3. Calls pass **`PythProUpdate` + `StorkState` + `OracleRegistry`** (and clock where required)
+
+| Surface | ZLP / USDZ | SLP |
+|---------|------------|-----|
+| Valuation PTB | `valuate_*_v2` | `valuate_*_v3` |
+| Swap | `swap_v3` | `swap_v4` |
+| Open / decrease | `*_v3` | `*_v3` |
+| Redeem | `redeem_from_position_v2` | `redeem_from_position_v3` |
+
+Deposit and withdraw still use the market `deposit` / `withdraw` entrypoints; the SDK builds valuation with the Pyth Pro path under the hood.

package/docs/common-operations.md

@@ -2,6 +2,27 @@
 
 These operations work across all LP tokens (ZLP, SLP, USDZ).
 
+## Oracle model (Pyth Pro + Stork)
+
+Newer market methods use **Pyth Pro** update bytes (verified on-chain) plus **Stork** where enabled, instead of per-token legacy Pyth feeder objects.
+
+| Operation | How oracle updates are supplied |
+|-----------|----------------------------------|
+| **Deposit / withdraw** | Fetched automatically inside the SDK (`initValuationOracle`) |
+| **Swap / open / decrease / redeem (v3+)** | Pass `pythProUpdateBytes` from `api.fetchPythProUpdateBytesForTokens(...)` |
+
+```typescript
+// Tokens needed for a trade (collateral + index)
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+// Tokens needed for a vault swap (all vaults are valued)
+const swapUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(
+  Object.keys(zlpAPI.consts.zoCore.vaults) // or sudoCore.vaults for SLP
+)
+```
+
+Legacy `openPositionV2` / `swap` / `swapV2Ptb` paths still exist, but new integrations should use the Pyth Pro methods below.
+
 ## Data / read operations
 
 Use the API or DataAPI; the methods are the same.
@@ -14,11 +35,15 @@ const positionCaps = await zlpAPI.getPositionCapInfoList(ownerAddress)
 const positions = await zlpAPI.getPositionInfoList(positionCaps, ownerAddress)
 ```
 
+`valuateMarket()` on SLP (and similar valuation helpers) resolves vault/symbol USD prices from Pyth Pro, including LST vaults as RR × SUI.
+
 ## Deposit
 
+Deposit builds valuation on-chain with Pyth Pro automatically — no update bytes argument.
+
 ```typescript
 const depositTx = await zlpAPI.deposit(
-  'usdc',             // coin type
+  'nusdc',            // coin type
   ['coinObjectId'],   // coin object IDs
   1000000,            // amount
   0,                  // minimum amount out (optional)
@@ -31,22 +56,45 @@ const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)
 
 ## Withdraw
 
+Same as deposit: valuation oracle is initialized inside the SDK.
+
 ```typescript
 const withdrawTx = await zlpAPI.withdraw(
-  'usdc',
+  'nusdc',
   ['lpCoinObjectId'],
   1000000,
   0
 )
 ```
 
-## Swap
+## Swap (Pyth Pro)
+
+Prefer the Pyth Pro swap methods:
+
+| LP | Method | PTB (returns coin) |
+|----|--------|--------------------|
+| **ZLP / USDZ** | `swapV3` | `swapV3Ptb` |
+| **SLP** | `swapV4` | `swapV4Ptb` |
 
 ```typescript
-const swapTx = await zlpAPI.swap(
-  'usdc',             // from token
-  'sui',              // to token
-  BigInt(1000000),    // amount
-  ['coinObjectId']    // coin objects
+const vaultTokens = Object.keys(zlpAPI.consts.zoCore.vaults)
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
+
+const swapTx = await zlpAPI.swapV3(
+  'nusdc',              // from token
+  'sui',                // to token
+  BigInt(1000000),      // amount
+  ['coinObjectId'],     // coin objects
+  pythProUpdateBytes,
+  0                     // minAmountOut (optional)
+)
+
+// SLP uses swapV4 with the same argument shape
+const slpSwapTx = await slpAPI.swapV4(
+  'usdc',
+  'sui',
+  BigInt(1000000),
+  ['coinObjectId'],
+  await slpAPI.fetchPythProUpdateBytesForTokens(Object.keys(slpAPI.consts.sudoCore.vaults)),
 )
 ```

package/docs/getting-started.md

@@ -46,8 +46,11 @@ const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
 const marketData = await zlpAPI.valuateMarket()
 const marketDataAlt = await zlpAPI.dataAPI.valuateMarket()
 
-// Transaction methods exist only on the API
-const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000)
+// Deposit / withdraw fetch Pyth Pro valuation updates internally
+const depositTx = await zlpAPI.deposit('nusdc', ['coinId'], 1000000)
+
+// Trading / swap (v3+) need update bytes first
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
 ```
 
 **DataAPI** instances are for read-only usage when you don't need to build transactions:
@@ -55,6 +58,8 @@ const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000)
 ```typescript
 const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
 const marketData = await zlpDataAPI.valuateMarket()
-const vaultInfo = await zlpDataAPI.getVaultInfo('usdc')
+const vaultInfo = await zlpDataAPI.getVaultInfo('nusdc')
 // zlpDataAPI.deposit(...) does not exist
 ```
+
+For Pyth Pro trading and swap examples, see [Common Operations](common-operations.md), [Trading Examples](lp-specific-features.md), and [Swap Integration](swap-integration.md).

package/docs/lp-specific-features.md

@@ -14,15 +14,27 @@ When you open or decrease a position, you choose how the order is executed:
 - **Limit**: best when you want a specific price; order stays pending until the price condition is met.
 - **IOC limit**: “fill at my price or not at all” in one block.
 
+## Pyth Pro trading methods
+
+Use **`openPositionV3`** / **`decreasePositionV3`** (and SCard / coin variants) for ZLP, SLP, and USDZ. These take `pythProUpdateBytes` from `fetchPythProUpdateBytesForTokens`.
+
+| Action | Method |
+|--------|--------|
+| Open | `openPositionV3`, `openPositionWithCoinV3`, `openPositionWithSCardV3`, `openPositionWithCoinAndSCardV3` |
+| Decrease | `decreasePositionV3`, `decreasePositionWithSCardV3` |
+| Redeem collateral | ZLP / USDZ: `redeemFromPositionV2` · SLP: `redeemFromPositionV3` |
+
 ---
 
-## ZLP / SLP: Open position (market order)
+## Open position (market order)
 
 Execute immediately with slippage protection:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',             // collateral token
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',            // collateral token
   'btc',              // index token
   BigInt(1000000),    // size
   BigInt(100000),     // collateral amount
@@ -30,7 +42,8 @@ const tx = await zlpAPI.openPositionV2(
   true,               // long position
   BigInt(50000),      // reserve amount
   30000,              // index price (reference)
-  1.5,                // collateral price (reference)
+  1.0,                // collateral price (reference)
+  pythProUpdateBytes, // Pyth Pro update bytes
   false,              // isLimitOrder: false = market order
   false,              // isIocOrder (ignored for market)
   0.003,              // pricesSlippage: 0.3% for market
@@ -41,15 +54,19 @@ const tx = await zlpAPI.openPositionV2(
 )
 ```
 
+The same `openPositionV3` signature works on `slpAPI` and `usdzAPI`.
+
 ---
 
-## ZLP / SLP: Open position (limit order)
+## Open position (limit order)
 
 Pending order at your limit price; use zero or small slippage:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',
   'btc',
   BigInt(1000000),
   BigInt(100000),
@@ -57,7 +74,8 @@ const tx = await zlpAPI.openPositionV2(
   true,                // long
   BigInt(50000),
   30000,               // your limit price (index)
-  1.5,                 // collateral price
+  1.0,                 // collateral price
+  pythProUpdateBytes,
   true,                // isLimitOrder: true = limit order
   false,               // isIocOrder: false = pending until price is met
   0,                   // pricesSlippage: 0 for limit (exact price)
@@ -70,13 +88,15 @@ const tx = await zlpAPI.openPositionV2(
 
 ---
 
-## ZLP / SLP: Open position (IOC limit order)
+## Open position (IOC limit order)
 
 Fill only if the limit can be met immediately; otherwise the order does not execute:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',
   'btc',
   BigInt(1000000),
   BigInt(100000),
@@ -84,7 +104,8 @@ const tx = await zlpAPI.openPositionV2(
   true,
   BigInt(50000),
   30000,
-  1.5,
+  1.0,
+  pythProUpdateBytes,
   true,                // isLimitOrder: true
   true,                // isIocOrder: true = fill now or cancel
   0,
@@ -94,3 +115,59 @@ const tx = await zlpAPI.openPositionV2(
   'senderAddress'
 )
 ```
+
+---
+
+## Decrease position
+
+```typescript
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.decreasePositionV3(
+  positionCapId,
+  'nusdc',             // collateral token
+  'btc',               // index token
+  BigInt(500000),      // decrease amount
+  true,                // long
+  30000,               // index price
+  1.0,                 // collateral price
+  pythProUpdateBytes,
+  false,               // isTriggerOrder
+  true,                // isTakeProfitOrder
+  false,               // isIocOrder
+  0.003,               // pricesSlippage
+  0.5,                 // collateralSlippage
+  BigInt(500),         // relayer fee
+  ['coinObjectId'],    // fee coin objects (or pass sender)
+  false,               // sponsoredTx
+  'senderAddress'
+)
+```
+
+---
+
+## Redeem collateral from a position
+
+```typescript
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+// ZLP / USDZ
+const redeemTx = await zlpAPI.redeemFromPositionV2(
+  positionCapId,
+  'nusdc',
+  'btc',
+  100000,              // amount
+  true,                // long
+  pythProUpdateBytes,
+)
+
+// SLP
+const slpRedeemTx = await slpAPI.redeemFromPositionV3(
+  positionCapId,
+  'usdc',
+  'btc',
+  100000,
+  true,
+  pythProUpdateBytes,
+)
+```

package/docs/swap-integration.md

@@ -1,15 +1,25 @@
 # Swap Integration
 
-This guide covers how to integrate swaps using the ZO SDK. Swaps are supported on **ZLP**, **SLP**, and **USDZ** via `api.swap()`, `api.swapV2Ptb()`, and fee estimation via `dataAPI.calculateSwapFeeBreakdown()`.
+This guide covers how to integrate swaps using the ZO SDK. Swaps are supported on **ZLP**, **SLP**, and **USDZ**.
+
+Prefer the **Pyth Pro** methods:
+
+| LP | Swap (transfer output) | Swap PTB (return coin) |
+|----|------------------------|-------------------------|
+| **ZLP / USDZ** | `swapV3` | `swapV3Ptb` |
+| **SLP** | `swapV4` | `swapV4Ptb` |
+
+Fee estimation is available via `dataAPI.calculateSwapFeeBreakdown()`. Legacy `swap()` / `swapV2Ptb()` remain available but are not recommended for new integrations.
 
 ## Overview
 
 A swap flow typically involves:
 
 1. **Estimate fees** – Get the expected fee breakdown for the swap.
-2. **Set slippage protection** – Compute `minAmountOut` based on expected output and slippage tolerance.
-3. **Build transaction** – Call `api.swap()` to construct the transaction.
-4. **Sign and send** – Sign with the wallet and submit to the network.
+2. **Fetch Pyth Pro update bytes** – Required for vault valuation on the Pyth Pro path.
+3. **Set slippage protection** – Compute `minAmountOut` based on expected output and slippage tolerance.
+4. **Build transaction** – Call `swapV3` (ZLP/USDZ) or `swapV4` (SLP).
+5. **Sign and send** – Sign with the wallet and submit to the network.
 
 ## Amounts and units
 
@@ -27,7 +37,7 @@ const fromAmount = BigInt(100 * 1e6)  // 100_000_000 atomic units
 Before building the swap transaction, you can estimate the fee breakdown to display to the user or compute a safe `minAmountOut`.
 
 ```typescript
-import { SDK, LPToken, Network } from '@zofai/zo-sdk'
+import { SDK, Network } from '@zofai/zo-sdk'
 import { SuiClient } from '@mysten/sui/client'
 
 const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
@@ -58,13 +68,14 @@ console.log(`Total fee: ${feeBreakdown.totalFeeValue.toFixed(4)} USD`)
 console.log(`Fee rate: ${(feeBreakdown.totalFeeRate * 100).toFixed(2)}%`)
 ```
 
-## Build and submit swap transaction
+## Build and submit swap transaction (Pyth Pro)
 
-Use the **API** instance to build the swap transaction. You need:
+You need:
 
 - `fromToken`, `toToken` – token identifiers (e.g. `'usdc'`, `'sui'`).
 - `fromAmount` – amount in atomic units (bigint).
 - `fromCoinObjects` – owned coin object IDs for the source token.
+- `pythProUpdateBytes` – from `fetchPythProUpdateBytesForTokens` over **all vault tokens** (swap values every vault).
 - `minAmountOut` – optional; minimum output amount in atomic units (slippage protection).
 
 ```typescript
@@ -72,39 +83,48 @@ const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
 
 const fromAmount = BigInt(100 * 1e6)  // 100 USDC
 const fromCoinObjects = ['0x...']     // user's USDC coin IDs
+const minAmountOut = 0                // or compute from oracle + slippage
 
-// Optional: set minAmountOut to protect against slippage
-// e.g. 1% slippage: minAmountOut = expectedOut * 0.99
-const minAmountOut = 0  // or compute from oracle + slippage
+const vaultTokens = Object.keys(slpAPI.consts.sudoCore.vaults)
+const pythProUpdateBytes = await slpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
 
-const tx = await slpAPI.swap(
+const tx = await slpAPI.swapV4(
   'usdc',
   'sui',
   fromAmount,
   fromCoinObjects,
+  pythProUpdateBytes,
   minAmountOut
 )
 
+// ZLP / USDZ: use swapV3 with the same argument shape
+// const tx = await zlpAPI.swapV3('nusdc', 'sui', fromAmount, fromCoinObjects, pythProUpdateBytes, minAmountOut)
+
 // Sign with wallet and execute
 // const signed = await signAndExecuteTransaction({ transaction: tx })
 ```
 
-## Swap and return coin to user (swapV2Ptb)
+## Swap and return coin (PTB)
 
-Use `swapV2Ptb()` when you need the output coin returned as a `TransactionObjectArgument`—for example, to pass into another move call or to transfer it within the same transaction. Unlike `swap()`, which consumes the output internally, `swapV2Ptb()` returns the output coin so you can compose it into larger transactions.
+Use `swapV3Ptb` (ZLP/USDZ) or `swapV4Ptb` (SLP) when you need the output coin as a `TransactionObjectArgument`—for example, to pass into another move call or transfer it in the same transaction.
 
 Pass an optional `tx` to compose into an existing transaction; otherwise a new transaction is created (you must sign and execute it via your wallet).
 
 ```typescript
+import { Transaction } from '@mysten/sui/transactions'
+
 const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
+const vaultTokens = Object.keys(slpAPI.consts.sudoCore.vaults)
+const pythProUpdateBytes = await slpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
 
-// Option 1: Standalone swap (tx created internally)
+// Option 1: Standalone swap (tx created / passed in)
 const tx = new Transaction()
-const outputCoin = await slpAPI.swapV2Ptb(
+const outputCoin = await slpAPI.swapV4Ptb(
   'usdc',
   'sui',
   BigInt(100 * 1e6),
   fromCoinObjects,
+  pythProUpdateBytes,
   minAmountOut,
   tx
 )
@@ -112,14 +132,22 @@ const outputCoin = await slpAPI.swapV2Ptb(
 
 // Option 2: Compose with other move calls
 const composedTx = new Transaction()
-const swapCoin = await slpAPI.swapV2Ptb('usdc', 'sui', BigInt(100 * 1e6), fromCoinObjects, minAmountOut, composedTx)
+const swapCoin = await slpAPI.swapV4Ptb(
+  'usdc',
+  'sui',
+  BigInt(100 * 1e6),
+  fromCoinObjects,
+  pythProUpdateBytes,
+  minAmountOut,
+  composedTx
+)
 composedTx.transferObjects([swapCoin], composedTx.pure.address(recipientAddress))
 ```
 
 ## Complete integration example
 
 ```typescript
-import { SDK, LPToken, Network } from '@zofai/zo-sdk'
+import { SDK, Network } from '@zofai/zo-sdk'
 import { SuiClient } from '@mysten/sui/client'
 
 async function swapWithFeeEstimate(
@@ -151,12 +179,16 @@ async function swapWithFeeEstimate(
   const expectedOutAtomic = (netValueUsd * (10 ** toDecimals)) / toPrice
   const minAmountOut = Math.floor(expectedOutAtomic * (1 - slippageBps / 10000))
 
-  // 3. Build transaction
-  const tx = await api.swap(
+  // 3. Fetch Pyth Pro update for all vaults, then build transaction
+  const vaultTokens = Object.keys(api.consts.sudoCore.vaults)
+  const pythProUpdateBytes = await api.fetchPythProUpdateBytesForTokens(vaultTokens)
+
+  const tx = await api.swapV4(
     fromToken,
     toToken,
     BigInt(fromAmountAtomic),
     fromCoinObjects,
+    pythProUpdateBytes,
     minAmountOut
   )
 
@@ -180,4 +212,4 @@ Use `calculateSwapFeeBreakdown` to get the USD value of each component and the t
 
 ## Token identifiers
 
-Tokens are identified by their symbol in the deployment config, e.g. `'sui'`, `'usdc'`, `'usdt'`, `'eth'`, `'btc'`. Ensure the `fromToken` and `toToken` values match those in the LP’s supported tokens.
+Tokens are identified by their symbol in the deployment config, e.g. `'sui'`, `'usdc'`, `'nusdc'`, `'usdt'`, `'eth'`, `'btc'`. Ensure the `fromToken` and `toToken` values match those in the LP’s supported tokens.