A re-architected TypeScript SDK for interacting with multiple LP tokens on Sui Network: ZLP (ZO Liquidity Provider), SLP (Sudo Liquidity Provider), and USDZ (USD Stablecoin).
npm install zo-sdkA re-architected TypeScript SDK for interacting with multiple LP tokens on Sui Network: ZLP (ZO Liquidity Provider), SLP (Sudo Liquidity Provider), and USDZ (USD Stablecoin).
``bash`
npm install zo-sdkor
yarn add zo-sdk
The SDK has been re-architected to support multiple LP tokens through a unified interface pattern:
- ZLP (ZO Liquidity Provider): Original ZO Protocol LP token
- SLP (Sudo Liquidity Provider): Sudo SDK-based LP token
- USDZ (USD Stablecoin): Stablecoin LP token
1. Common Interfaces: Unified API surface for all LP tokens (IBaseAPI, IBaseDataAPI)BaseAPI
2. Abstract Base Classes: Shared implementation logic (, BaseDataAPI)ZLPAPI
3. Concrete Implementations: LP-specific functionality (, SLPAPI, USDZAPI)SDKFactory
4. Factory Pattern: Type-safe SDK instance creation ()
5. Legacy Compatibility: Backward compatible API for existing integrations
`typescript
import { SDK, LPToken, Network } from 'zo-sdk'
import { SuiClient } from '@mysten/sui/client'
// Initialize 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 LP-specific API instances
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 use generic factory
const api = SDK.createAPI(LPToken.ZLP, network, provider, apiEndpoint, connectionURL)
// Create DataAPI instances for read-only operations
const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
const slpDataAPI = SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)
const usdzDataAPI = SDK.createUSDZDataAPI(network, provider, apiEndpoint, connectionURL)
`
The SDK provides two types of interfaces:
- API Classes (ZLPAPI, SLPAPI, USDZAPI): Full functionality including trading operations that create transactionsZLPDataAPI
- DataAPI Classes (, SLPDataAPI, USDZDataAPI): Read-only operations for querying blockchain state
`typescript
// API instances include both data access and transaction creation
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const marketData = await zlpAPI.dataAPI.valuateMarket() // Data access
const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000) // Transaction creation
// DataAPI instances are for read-only operations only
const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
const marketData = await zlpDataAPI.valuateMarket() // Data access only
`
`typescript
// Market valuation (all LP tokens)
const zlpMarket = await zlpAPI.dataAPI.valuateMarket()
const slpMarket = await slpAPI.dataAPI.valuateMarket()
const usdzMarket = await usdzAPI.dataAPI.valuateMarket()
// Deposit operations (all LP tokens)
const depositTx = await zlpAPI.deposit(
'usdc', // coin type
['coinObjectId'], // coin object IDs
1000000, // amount
0, // minimum amount out
'referralAddress', // optional referral
'senderAddress' // optional sender
)
// Similar for SLP and USDZ
const slpDepositTx = await slpAPI.deposit('usdc', ['coinObjectId'], 1000000)
const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)
// Withdraw operations
const withdrawTx = await zlpAPI.withdraw(
'usdc', // coin to withdraw
['lpCoinObjectId'], // LP coin object IDs
1000000, // amount
0 // minimum amount out
)
// Swap operations
const swapTx = await zlpAPI.swap(
'usdc', // from token
'sui', // to token
BigInt(1000000), // amount
['coinObjectId'], // coin objects
0 // minimum amount out
)
`
`typescript
// ZLP-specific: Advanced trading operations
// Open leveraged position
const openPositionTx = await zlpAPI.openPosition(
'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
1.5, // collateral price
false, // is limit order
false, // is IOC order
0.003, // price slippage
0.5, // collateral slippage
BigInt(500), // relayer fee
'referralAddress', // referral
'senderAddress' // sender
)
// SLP-specific: Sudo SDK operations
// Stake SLP tokens
const stakeTx = await slpAPI.stake(
['slpCoinObjectId'], // LP coin objects
BigInt(1000000), // amount
'poolId' // staking pool
)
// Unstake SLP tokens
const unstakeTx = await slpAPI.unstake(
credentials, // SLP credentials
BigInt(500000), // amount
'poolId' // staking pool
)
// USDZ-specific: Stablecoin operations
// (Similar deposit/withdraw/swap operations optimized for stablecoin use cases)
const usdzSwapTx = await usdzAPI.swap(
'usdc', // from stable
'usdt', // to stable
BigInt(1000000), // amount
['coinObjectId'] // coin objects
)
`
`typescript
import { API, Network } from 'zo-sdk'
import { SuiClient } from '@mysten/sui/client'
// Initialize the API
const provider = new SuiClient({ url: 'https://sui-rpc.url' })
const api = API.getInstance(
Network.MAINNET,
provider,
'https://api-endpoint',
'https://price-feed-url'
)
// Example: Get market information
const marketInfo = await api.getMarketInfo()
// Example: Get oracle price for a token
const price = await api.getOraclePrice('sui')
`
`typescript
// Deposit tokens to get ZLP
const tx = await api.deposit(
'sui', // token
['coinObjectId'], // coin object IDs
1000000, // amount
0 // minimum amount out
)
// Withdraw tokens by burning ZLP
const tx = await api.withdraw(
'sui', // token
['zlpCoinObjectId'], // ZLP coin object IDs
1000000, // amount
0 // minimum amount out
)
// Swap tokens
const tx = await api.swap(
'sui', // from token
'usdc', // to token
BigInt(1000000), // amount
['coinObjectId'] // coin object IDs
)
`
`typescript
// Open a position
const tx = await api.openPosition(
'sui', // collateral token
'btc', // index token
BigInt(1000000), // size
BigInt(100000), // collateral amount
['coinObjectId'], // coin object IDs
true, // long position
BigInt(100000), // reserve amount
30000, // index price
1.5, // collateral price
false, // is limit order
false, // is IOC order
0.003, // price slippage
0.5, // collateral slippage
BigInt(500), // relayer fee
'referralAddress', // referral address
'senderAddress' // sender address
)
// Decrease a position
const tx = await api.decreasePosition(
'positionCapId',
'sui', // collateral token
'btc', // index token
BigInt(500000), // amount to decrease
true, // long position
30000, // index price
1.5, // collateral price
)
// Cancel an order
const tx = await api.cancelOrder(
'orderCapId',
'sui',
'btc',
true, // long position
'OPEN_POSITION' // order type
)
`
`typescript
// Get market information
const marketInfo = await api.getMarketInfo()
// Get oracle price for a token
const price = await api.getOraclePrice('sui')
// Get vault information
const vaultInfo = await api.getVaultInfo('sui')
// Get symbol information
const symbolInfo = await api.getSymbolInfo('btc', true) // true for long
// Get market valuation
const valuation = await api.valuateMarket()
// Get position cap info list
const positionCaps = await api.getPositionCapInfoList('ownerAddress')
// Get order cap info list
const orderCaps = await api.getOrderCapInfoList('ownerAddress')
// Get position information
const positions = await api.getPositionInfoList(positionCaps, 'ownerAddress')
// Get order information
const orders = await api.getOrderInfoList(orderCaps, 'ownerAddress')
`
`typescript
// Stake ZLP tokens
const stakeTx = await api.stake(
['zlpCoinObjectId'], // ZLP coin object IDs
BigInt(1000000), // amount to stake
'poolId' // staking pool ID
)
// Unstake ZLP tokens
const unstakeTx = await api.unstake(
credentials, // staking credentials
BigInt(1000000), // amount to unstake
'poolId' // staking pool ID
)
// Get staked information
const stakedInfo = await api.getStaked('ownerAddress')
`
The SDK is built with TypeScript and provides comprehensive type definitions:
`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 structures
const marketInfo: IBaseMarketValuationInfo = await zlpAPI.dataAPI.valuateMarket()
const vaultInfo: IBaseVaultInfo = await zlpAPI.dataAPI.getVaultInfo('usdc')
`
The SDK throws errors for invalid operations and network issues. Always wrap API calls in try-catch blocks:
`typescript`
try {
const marketInfo = await api.getMarketInfo()
const depositTx = await api.deposit('usdc', ['coinId'], 1000000)
} catch (error) {
console.error('SDK operation failed:', error)
// Handle specific error types
if (error.message.includes('Unsupported LP token')) {
console.error('Invalid LP token type provided')
}
}
If you're upgrading from an older version of the SDK:
`typescript
// Old way (still supported for backward compatibility)
import { API, Network } from 'zo-sdk'
const api = API.getInstance(network, provider, apiEndpoint, connectionURL)
// New way (recommended)
import { SDK, LPToken, Network } from 'zo-sdk'
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
const usdzAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)
`
1. Multi-LP Token Support: The SDK now supports ZLP, SLP, and USDZ tokens
2. Factory Pattern: Use SDK.createXXXAPI() methods instead of singleton instances
3. Separate DataAPI: Read-only operations are available through dedicated DataAPI classes
4. Enhanced Type Safety: Comprehensive TypeScript interfaces for all operations
5. Modular Architecture: Each LP token has its own implementation while sharing common interfaces
- Factory Methods: SDK.createZLPAPI(), SDK.createSLPAPI(), SDK.createUSDZAPI()
- Base Interfaces: , IBaseDataAPI for common operationsIZLPAPI
- LP-Specific Interfaces: , ISLPAPI, IUSDZAPI for specialized featuresIBaseMarketValuationInfo
- Data Types: , IBaseVaultInfo, IBaseSymbolInfo, etc.
For detailed implementation details and advanced usage:
- Interfaces: /src/interfaces/ - TypeScript interface definitions/src/implementations/
- Implementations: - Concrete API implementations/src/abstract/
- Abstract Classes: - Shared base functionality/src/factory/SDKFactory.ts
- Factory: - SDK instance creation/src/api.ts` - Backward compatible API
- Legacy API:
Check the source code comments and type definitions for comprehensive examples of all available methods and their parameters.