@zofai/zo-sdk 0.1.92

package/docs/getting-started.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+## 1. Create an API or DataAPI instance
+
+Use the **SDK** factory (exported as `SDK` from `zo-sdk`) to create LP-specific instances. You need a Sui client, network, API endpoint, and connection URL.
+
+```typescript
+import { SDK, LPToken, Network } from 'zo-sdk'
+import { SuiClient } from '@mysten/sui/client'
+
+const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
+const network = Network.MAINNET
+const apiEndpoint = 'https://api.zo.xyz'
+const connectionURL = 'wss://api.zo.xyz/ws'
+
+// Create API instances (transactions + data)
+const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
+const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
+const usdzAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)
+
+// Or create by LP token enum
+const api = SDK.createAPI(LPToken.ZLP, network, provider, apiEndpoint, connectionURL)
+
+// Create DataAPI instances (read-only; no transaction methods)
+const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
+const slpDataAPI = SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)
+const usdzDataAPI = SDK.createUSDZDataAPI(network, provider, apiEndpoint, connectionURL)
+
+// Or create DataAPI by LP token
+const dataAPI = SDK.createDataAPI(LPToken.SLP, network, provider, apiEndpoint, connectionURL)
+```
+
+## 2. API vs DataAPI
+
+| Use case | Class | Use |
+|----------|--------|-----|
+| **Build transactions + read data** | **API** (`ZLPAPI`, `SLPAPI`, etc.) | Deposit, withdraw, open/close positions, stake, and also call data methods (market info, vaults, positions, etc.). |
+| **Read-only** | **DataAPI** (`ZLPDataAPI`, `SLPDataAPI`, etc.) | Only query chain/API state (market valuation, vault info, positions, orders, history). No transaction building. |
+
+**API** instances expose both transaction methods and data methods. Data methods (e.g. `getMarketInfo`, `valuateMarket`, `getVaultInfo`) are implemented by delegating to the internal `dataAPI`, so you can call them directly on the API or via `api.dataAPI`:
+
+```typescript
+const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
+
+// Data methods are available directly on the API (same result either way)
+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)
+```
+
+**DataAPI** instances are for read-only usage when you don't need to build transactions:
+
+```typescript
+const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
+const marketData = await zlpDataAPI.valuateMarket()
+const vaultInfo = await zlpDataAPI.getVaultInfo('usdc')
+// zlpDataAPI.deposit(...) does not exist
+```

package/docs/introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+ZO SDK is a TypeScript SDK for interacting with multiple LP tokens on Sui Network: **ZLP** (ZO Liquidity Provider), **SLP** (Sudo Liquidity Provider), and **USDZ** (USD Stablecoin).
+
+## Installation
+
+```bash
+npm install zo-sdk
+# or
+yarn add zo-sdk
+# or
+pnpm add zo-sdk
+```
+
+For the full guide, see [Getting Started](getting-started.md).

package/docs/lp-specific-features.md

@@ -0,0 +1,96 @@
+# Trading Examples
+
+## Limit order vs. market order
+
+When you open or decrease a position, you choose how the order is executed:
+
+| Type | `isLimitOrder` | `isIocOrder` | Behavior |
+|------|----------------|--------------|----------|
+| **Market order** | `false` | — | Execute immediately at market. Use **slippage** (`pricesSlippage`, `collateralSlippage`) to bound worst price. |
+| **Limit order** | `true` | `false` | Stored as a pending order; executes when the price condition is met. Typically use **zero or small slippage** (`pricesSlippage: 0`). |
+| **IOC limit order** | `true` | `true` | Fill only if the limit can be met immediately; otherwise cancel (no partial fill). |
+
+- **Market**: best for “get in/out now”; you accept some slippage.
+- **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.
+
+---
+
+## ZLP / SLP: Open position (market order)
+
+Execute immediately with slippage protection:
+
+```typescript
+const tx = await zlpAPI.openPositionV2(
+  'usdc',             // collateral token
+  'btc',              // index token
+  BigInt(1000000),    // size
+  BigInt(100000),     // collateral amount
+  ['coinObjectId'],   // coin objects
+  true,               // long position
+  BigInt(50000),      // reserve amount
+  30000,              // index price (reference)
+  1.5,                // collateral price (reference)
+  false,              // isLimitOrder: false = market order
+  false,              // isIocOrder (ignored for market)
+  0.003,              // pricesSlippage: 0.3% for market
+  0.5,                // collateralSlippage: 50% for market
+  BigInt(500),        // relayer fee
+  'referralAddress',
+  'senderAddress'
+)
+```
+
+---
+
+## ZLP / SLP: Open position (limit order)
+
+Pending order at your limit price; use zero or small slippage:
+
+```typescript
+const tx = await zlpAPI.openPositionV2(
+  'usdc',
+  'btc',
+  BigInt(1000000),
+  BigInt(100000),
+  ['coinObjectId'],
+  true,                // long
+  BigInt(50000),
+  30000,               // your limit price (index)
+  1.5,                 // collateral price
+  true,                // isLimitOrder: true = limit order
+  false,               // isIocOrder: false = pending until price is met
+  0,                   // pricesSlippage: 0 for limit (exact price)
+  0.5,                 // collateralSlippage
+  BigInt(500),
+  'referralAddress',
+  'senderAddress'
+)
+```
+
+---
+
+## ZLP / SLP: 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',
+  'btc',
+  BigInt(1000000),
+  BigInt(100000),
+  ['coinObjectId'],
+  true,
+  BigInt(50000),
+  30000,
+  1.5,
+  true,                // isLimitOrder: true
+  true,                // isIocOrder: true = fill now or cancel
+  0,
+  0.5,
+  BigInt(500),
+  'referralAddress',
+  'senderAddress'
+)
+```

package/docs/type-safety.md

@@ -0,0 +1,29 @@
+# Type Safety
+
+The SDK is built with TypeScript and provides comprehensive type definitions.
+
+## Interfaces
+
+```typescript
+import type {
+  IBaseAPI,
+  IBaseDataAPI,
+  IZLPAPI,
+  ISLPAPI,
+  IUSDZAPI,
+  IBaseMarketValuationInfo,
+  IBaseVaultInfo,
+  IBaseSymbolInfo,
+  IBasePositionInfo,
+  IBaseOrderInfo
+} from 'zo-sdk'
+
+// All APIs implement their respective interfaces
+const zlpAPI: IZLPAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
+const slpAPI: ISLPAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
+const usdzAPI: IUSDZAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)
+
+// Type-safe data: call data methods directly on the API or via .dataAPI
+const marketInfo: IBaseMarketValuationInfo = await zlpAPI.valuateMarket()
+const vaultInfo: IBaseVaultInfo = await zlpAPI.getVaultInfo('usdc')
+```

package/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig } from 'eslint-config-hyoban'
+
+export default defineConfig({
+  react: 'vite',
+  restrictedSyntax: ['jsx', 'tsx'],
+  strict: true,
+}, {
+  rules: {
+    'react-hooks/rules-of-hooks': 'error',
+    'react-hooks/exhaustive-deps': 'error',
+    'react-refresh/only-export-components': 'off',
+    'max-params': 'off',
+
+    '@typescript-eslint/no-explicit-any': 'warn',
+    'unicorn/expiring-todo-comments': 'off',
+    '@eslint-react/jsx-no-undef': 'off',
+  },
+})

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zofai/zo-sdk",
+  "type": "module",
+  "version": "0.1.92",
+  "author": "zo",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@mysten/bcs": "^1.1.0",
+    "@mysten/kiosk": "^0.12.17",
+    "@mysten/sui": "^1.36.0",
+    "@pythnetwork/pyth-sui-js": "2.2.0",
+    "decimal.js": "10.4.3"
+  },
+  "devDependencies": {
+    "@ts-bridge/cli": "^0.6.3",
+    "eslint": "^9.32.0",
+    "eslint-config-hyoban": "^4.0.9",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "scripts": {
+    "build": "ts-bridge build --project ./tsconfig.json --clean",
+    "pub": "pnpm build && npm publish",
+    "serve": "tsx dist/index.js",
+    "start": "tsx src/index.ts",
+    "test": "vitest"
+  }
+}