`: A promise that resolves to a transaction object.
### Usage Example
const tx = await sudoAPI.openPosition(
'USDC', // collateralToken
'SUI', // indexToken
5, // 5x leverage
1000, // 1000 USDC as collateral
myPositionConfig, // check getPositionConfig API
['0x123...', '0x456...'], // coinObjects
true, // long position
2, // indexPrice (SUI price in USD)
1, // collateralPrice (USDC price in USD)
0.001, // pricesSlippage (0.1%)
0.1, // collateralSlippage (10%)
false, // not a limit order
false, // not an IOC order
BigInt(2) // relayerFee
);
### Notes
* Ensure you have sufficient balance and have approved the necessary permissions before calling this function.
* The function uses the current oracle prices for the tokens. Ensure your frontend is updated with the latest prices before calling this function.
* The `pricesSlippage` and `collateralSlippage` parameters allow you to control the maximum allowed price movement. Adjust these based on market volatility and your risk tolerance.
* For limit orders, set `isLimitOrder` to `true`.
* The `relayerFee` is paid in SUI. Adjust this value based on the current network conditions and relayer requirements.
### Error Handling
This function may throw errors if:
* The input parameters are invalid
* There's insufficient balance
* The slippage tolerance is exceeded
* The position size is outside allowed limits
Always wrap the function call in a try-catch block and handle potential errors appropriately in your application.
# Decrease Position
The `decreasePosition` function allows users to reduce the size of an existing position.
#### Function Signature
```typescript
decreasePosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: bigint,
long: boolean,
indexPrice: number,
collateralPrice: number,
isTriggerOrder?: boolean,
isTakeProfitOrder?: boolean,
isIocOrder?: boolean,
pricesSlippage?: number,
collateralSlippage?: number,
relayerFee?: bigint
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to decrease
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount to decrease the position by
* `long`: Boolean indicating if this is a long (true) or short (false) position
* `indexPrice`: The current price of the index token
* `collateralPrice`: The current price of the collateral token
* `isTriggerOrder`: Boolean indicating if this is a trigger order (default: false)
* `isTakeProfitOrder`: Boolean indicating if this is a take profit order (default: true)
* `isIocOrder`: Boolean indicating if this is an IOC (Immediate-or-Cancel) order (default: false)
* `pricesSlippage`: Maximum allowed slippage for prices (default: 0.003 or 0.3%)
* `collateralSlippage`: Maximum allowed slippage for collateral (default: 0.5 or 50%)
* `relayerFee`: Fee paid to the relayer (default: 1)
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.decreasePosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
BigInt(500000), // amount (0.5 BTC if BTC has 6 decimals)
true, // long position
50000, // indexPrice (BTC price in USD)
1, // collateralPrice (USDC price in USD)
false, // not a trigger order
true, // is a take profit order
false, // not an IOC order
0.001, // pricesSlippage (0.1%)
0.1, // collateralSlippage (10%)
BigInt(2) // relayerFee
);
```
# Pledge In Position
The `pledgeInPosition` function allows users to add more collateral to an existing position.
#### Function Signature
```typescript
pledgeInPosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: number,
coinObjects: string[],
long: boolean
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to pledge into
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount of collateral to add
* `coinObjects`: Array of coin object IDs to use for the transaction
* `long`: Boolean indicating if this is a long (true) or short (false) position
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.pledgeInPosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
1000000, // amount (1 USDC if USDC has 6 decimals)
['0x456...', '0x789...'], // coinObjects
true // long position
);
```
# Redeem From Position
The `redeemFromPosition` function allows users to withdraw collateral from an existing position.
#### Function Signature
```typescript
redeemFromPosition(
pcpId: string,
collateralToken: string,
indexToken: string,
amount: number,
long: boolean
): Promise
```
#### Parameters
* `pcpId`: The ID of the position to redeem from
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `amount`: The amount of collateral to withdraw
* `long`: Boolean indicating if this is a long (true) or short (false) position
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.redeemFromPosition(
'0x123...', // pcpId
'USDC', // collateralToken
'BTC', // indexToken
500000, // amount (0.5 USDC if USDC has 6 decimals)
true // long position
);
```
# Cancel Order
The `cancelOrder` function allows users to cancel an existing order.
#### Function Signature
```typescript
cancelOrder(
orderCapId: string,
collateralToken: string,
indexToken: string,
long: boolean,
type: string
): Promise
```
#### Parameters
* `orderCapId`: The ID of the order to cancel
* `collateralToken`: The token used as collateral (e.g., "USDC")
* `indexToken`: The token used as the market index (e.g., "BTC")
* `long`: Boolean indicating if this is a long (true) or short (false) position
* `type`: The type of order ("OPEN\_POSITION" or "DECREASE\_POSITION")
#### Return Value
Returns a `Promise` that resolves to a `TransactionBlock` object.
#### Usage Example
```typescript
const tx = await sudoAPI.cancelOrder(
'0x123...', // orderCapId
'USDC', // collateralToken
'BTC', // indexToken
true, // long position
'OPEN_POSITION' // order type
);
```
###
# getPositionCapInfoList
The `getPositionCapInfoList` function retrieves a list of position cap information for a given owner address.
#### Function Signature
```typescript
getPositionCapInfoList(owner: string): Promise
```
#### Parameters
* `owner`: A string representing the owner's address.
#### Return Value
Returns a `Promise` that resolves to an array of `IPositionCapInfo` objects. Each `IPositionCapInfo` object has the following structure:
```typescript
interface IPositionCapInfo {
positionCapId: string;
symbol0: string;
symbol1: string;
long: boolean;
}
```
* `positionCapId`: The ID of the position cap.
* `symbol0`: The first symbol in the trading pair.
* `symbol1`: The second symbol in the trading pair.
* `long`: A boolean indicating whether the position is long (true) or short (false).
#### Description
This function fetches all position caps owned by the specified address. It filters for objects of type `PositionCap` and extracts relevant information from each position cap.
#### Usage Example
```typescript
const owner = "0x1234..."; // Replace with actual owner address
const sudoAPI = new SudoAPI(network, provider);
try {
const positionCaps = await sudoAPI.getPositionCapInfoList(owner);
console.log("Position Caps:", positionCaps);
} catch (error) {
console.error("Error fetching position caps:", error);
}
```
# getPositionInfoList
The `getPositionInfoList` function retrieves detailed information about positions based on a list of position cap information.
#### Function Signature
```typescript
getPositionInfoList(
positionCapInfoList: IPositionCapInfo[],
owner: string
): Promise
```
#### Parameters
* `positionCapInfoList`: An array of `IPositionCapInfo` objects, typically obtained from `getPositionCapInfoList`.
* `owner`: A string representing the owner's address.
#### Return Value
Returns a `Promise` that resolves to an array of `IPositionInfo` objects. Each `IPositionInfo` object contains detailed information about a position, including:
```typescript
interface IPositionInfo {
id: string;
long: boolean;
owner: string;
version: number;
collateralToken: string;
indexToken: string;
collateralAmount: number;
positionAmount: number;
reservedAmount: number;
positionSize: number;
lastFundingRate: number;
lastReservingRate: number;
reservingFeeAmount: number;
fundingFeeValue: number;
closed: boolean;
openTimestamp: number;
protocol?: string;
}
```
#### Description
This function takes a list of position cap information and fetches detailed data for each position. It calculates additional information such as reserving fee amount and funding fee value for open positions.
#### Usage Example
```typescript
const owner = "0x1234..."; // Replace with actual owner address
const sudoAPI = new SudoAPI(provider);
try {
const positionCaps = await sudoAPI.getPositionCapInfoList(owner);
const positionInfoList = await sudoAPI.getPositionInfoList(positionCaps, owner);
console.log("Position Info List:", positionInfoList);
} catch (error) {
console.error("Error fetching position information:", error);
}
```
#### Notes
* The function sorts the returned positions by `openTimestamp` in ascending order.
* For open positions, the function calculates `reservingFeeAmount` and `fundingFeeValue` using separate API calls.
* If there's an error calculating `reservingFeeAmount` or `fundingFeeValue`, these values are set to 0 and the error is logged.
# getPositionConfig
Retrieves and parses the position configuration for a given index token and position type (long or short).
#### Function Signature
```typescript
getPositionConfig(
indexToken: string
long: boolean
): Promise
```
#### Parameters
* `indexToken` (string): The token for which to retrieve the position configuration.
* `long` (boolean): Indicates whether to retrieve the configuration for a long (true) or short (false) position.
#### Return Value
Returns a `Promise` that resolves to an `IPositionConfig` object. The object contains parsed position configuration, including:
```typescript
interface IPositionConfig {
decreaseFeeBps: number;
liquidationBonus: number;
liquidationThreshold: number;
maxLeverage: number;
minHoldingDuration: number;
openFeeBps: number;
maxReservedMultiplier: number;
minCollateralValue: number;
}
```
#### Description
This method fetches the position configuration data from the blockchain for a specified index token and position type. It performs the following steps:
#### Usage Example
```typescript
const sudoAPI = new SudoAPI(provider);
try {
const positionConfig = await sudoAPI.getPositionConfig('BTC', true);
console.log("Fetched position config:", positionConfig);
} catch (error) {
console.error("Error fetching position config:", error);
}
```
# OracleAPI
This section describes all APIs related to token prices.
# subOraclePrices
Subscribes to price feed updates for specified tokens.
#### Parameters
* `tokens` (string\[]): An array of token identifiers.
* `callback` ((price: PriceFeed) => void): A function to be called with each price update.
#### Returns
* `Promise`: A promise that resolves when the subscription is set up.
#### Description
This method establishes a subscription to price feed updates for the specified tokens. It maps the token identifiers to their corresponding Pyth object IDs and price feed IDs, then sets up a subscription using the Sui Price Service Connection.
When a price update is received, the method modifies the `price.id` to match the token identifier format used in the system, then calls the provided callback function with the updated price information.
#### Example Usage
```typescript
export function useTokenPrice(network: string) {
const [tokenPrice, setTokenPrice] = useState<{ [key: string]: number }>({});
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
if (isLoading) return;
setIsLoading(true);
const oracleAPI = new OracleAPI(network);
Promise.all([
oracleAPI.subOraclePrices(
Array.from(
new Set([...Object.keys(oracleAPI.consts.pythFeeder.feeder)]),
),
priceInfo => {
setTokenPrice(prevPrice => ({
...prevPrice,
[priceInfo.id]: priceInfo
.getPriceUnchecked()
.getPriceAsNumberUnchecked(),
}));
},
),
])
.then(() => {
setIsLoading(false);
})
.catch(err => {
console.error(err);
setError(err.message);
setIsLoading(false);
});
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [network]);
return {
tokenPrice,
isLoading,
error,
};
}
```
# Changelog
### # v0.0.2 -> v0.0.3
### Major Update
* Upgraded from "@mysten/sui.js": "0.54.1" to "@mysten/sui": "1.3.0"
### Key Changes
1. Parameter Updates:
* Removed: `size`, `collateralAmount`, `reserveAmount` (all bigint)
* Added: `leverage` (number), `collateral` (number), `positionConfig` (IPositionConfig)
2. Calculation Approach:
* Position size and reserve amount now calculated internally based on leverage and collateral
3. Return Type:
* Changed from `Promise` to implicit `Promise`
### Impact
* More intuitive position opening with leverage-based calculations
* Increased flexibility with `positionConfig`
* Less pre-processing and calculation required from the caller
* Potential breaking changes due to major Sui SDK upgrade
# Best Practices
When using the Sudo SDK, consider the following best practices:
1. **Error Handling**: Always implement proper error handling to manage potential issues gracefully.
2. **Price Updates**: Ensure you're using the most up-to-date price information when opening positions.
3. **Gas Management**: Be mindful of gas costs, especially when executing multiple transactions.
4. **Testing**: Thoroughly test your integration on a testnet before deploying to mainnet.
5. **Security**: Never expose your private keys. Use secure key management practices.
# Troubleshooting
# Algorithm Balanced Funding Rate (ABFR)
The fundamental principle underlying ABFR is to safeguard the interests of SLP holders by dynamically adapting the funding rate according to the specific direction of a trading pair. When traders exhibit net profitability in a given trading pair, fees are gathered from them and provided as support to LPs. When traders face an overall loss, fees are acquired from LPs and allocated to traders. This mechanism guarantees that the combined unrealized and realized PNL of each trading pair tends to balance out to approximately zero over the long run. In this way, LPs wouldn't experience excessive returns but rather would generate income from fees (transaction fee + borrowing interest). The subsequent steps outline the overall process for calculating these dynamic funding fees.
#### Calculate the total profit and loss of LP at time t on the the trading pair
$$\begin{aligned}sign&=\begin{cases}1\&short\\-1\&long\end{cases}\\\Delta\_t&=openAmount\_t \times price\_t - openSize\_t\pnl\_t&=realizedPnl+fundingFee+sign\times\Delta\_t\end{aligned}$$
{% hint style="info" %}
* Realized PNL signifies the actual profit and loss experienced by LPs due to changes in traders' positions, excluding the influence of fees.
* FundingFee embodies the cumulative funding fees that have been gathered or distributed.
{% endhint %}
When PNL\_t < 0:
$$ABFR\_t=\begin{aligned}min\left{K\_1\times log\left|PNL\_t\right|,R\_x\right}\end{aligned}$$
When PNL\_t > 0:
$$ABFR\_t=\begin{aligned}-min\left{K\_2\times log\left|PNL\_t\right|,R\_y\right}\end{aligned}$$
{% hint style="info" %}
K1, K2 are constant coefficients
{% endhint %}
* The reason for using the logarithm of pnl is to make ABFR change significantly when pnl is small and change slowly when pnl is large
* ABFR has upper and lower bounds, with corresponding upper and lower rate limits Rx, Ry when pnl < 0 and pnl > 0, respectively
If a trader opens a position at time t1 and closes it at time t2, with a position size of ***size*****,** the funding fee to be paid/received by the trader is
$$fundingFee=size\times\int\_{t\_1}^{t\_2}ABFR\_t\ dt$$
When the fee is positive, trader pays the funding fee to the LP
When the fee is negative, LP pays the funding fee to the trader
# Risk control
### Risk Control
Fluctuations in both the value of the collateral token and the token underlying the contract can lead to the potential liquidation of the position. Traders should vigilantly monitor both the position's profit and loss and any changes in the collateral's value.
A trader is required to establish a maximum margin size for the counterparty, which would also be the highest feasible profit excluding fees. If the position reaches this maximum profit, further profit won't be generated.
Opting for a larger counterparty margin also entails higher position maintenance fees. This is slightly different from the approach taken by other centralized exchanges. Those exchanges usually involve a contract borrow fee that is more closely tied to the position's value, influenced by its leverage. In contrast, Zo's borrowing fee for perpetual contracts is predominantly determined by the potential maximum profit/loss of the position.
# FAQ
# Roadmap
#### ~~Milestone 1: Contract Implementation~~
* ~~Validate the feasibility of innovation points and implement smart contracts.~~
* ~~Expected Completion Date: 8/15/2023~~
* ~~Deliverables:~~
* ~~Feasibility of innovation points verified.~~
* ~~Smart contracts implemented.~~
#### ~~Milestone 2: Testnet launch~~
* ~~Launch Sudo on Sui Testnet~~
* ~~Expected Completion Date: 10/15/2023~~
* ~~Deliverables:~~
* ~~Make sudo available for testing on testnet to every degen~~
#### ~~Milestone 3: Mainnet launch~~
* ~~Launch Sudo on Mainnet~~
* ~~Expected Completion Date: 12/15/2023~~
* ~~Deliverables:~~
* ~~Mainnet launch completed.~~
* ~~Smart contract audited.~~
* ~~Onboarding documentation for sudo~~
* ~~Referral and loyalty program~~
* ~~Trading competition~~
~~2024 Q1 Milestone~~
* ~~Reach $10M in trading volume~~
* ~~Make over $50k in trading fee~~
* ~~Grow Users to 500+~~
* ~~Launch 10+ trading pairs~~
* ~~TVL $300k+~~
~~2024 Q2 Milestone~~
* ~~Reach $30M in trading volume~~
* ~~Make over $200k in trading fee~~
* ~~Grow Users to 800+~~
* ~~Launch 20+ trading pairs~~
* ~~Launch "S" Card~~
* ~~Launch "S" Card rebate~~
~~2024 Q3 Milestone~~
* ~~Reach $50M intrading volume~~
* ~~Make over $500k in trading fee~~
* ~~Grow Users to 1500+~~
* ~~Launch referral feature~~
* ~~Launch Sudo SDK~~
# On-chain program
Original Package:
{% embed url="" %}
Latest Package:
{% embed url="" %}
Audit Partner: MoveBit
Audit Report:
{% file src="/files/Vyar3aa9aRfThteydJE1" %}
# Referral Program
Earn rebates through the Zo referral program.
### How it works
To create a referral code:
* Go to the Referrals page
* Link your wallet and copy your referral link
* Send your referral link to social media platforms.
* Fee rebate percentage: 10%
Once you've created your code, click on the copy icon next to the code to get your referral link, it should look something like this: [https://app.zofai.io/trade?referral=](https://www.zofinance.io/app/trade?referral=)\.
You can share this link on any platform, e.g. Twitter, Telegram. When a user clicks on your link, your referral code would be stored with the user's account. When the user makes a trade you would earn rebates from their trading fees. You will continue to earn rebates even if the user uses another device later on as the referral code is stored on the contract the first time the user makes a trade.
# ZO Terms and Conditions
Terms and Conditions
Last modified: Feb 24th, 2025
Welcome to zofinance.io ("we," "us," or "our"), the informational resource for ZO Protocol, as defined below. zofinance.io provides information and resources about the fundamentals of the decentralized non-custodial protocol called the ZO Protocol (the "ZO Protocol," "Protocol," or "ZO DApp"). zofinance.io is not an available access point to the ZO Protocol. These Terms and Conditions and any other documents incorporated herein by reference (collectively, these "Terms") to you or the company or other legal entity you represent ("you" or "your") explains the terms and conditions by which you may access zofinance.io ("the Site") and app.zofinance.io ("the Interface"). Please do not use the Site or Interface if you disagree with any of these Terms.
1. USE OF THE SITE AND THE INTERFACE
The zofinance.io site is for informational purposes only. zofinance.io is not part of any transaction on the blockchain networks underlying the ZO Protocol; we do not have possession, custody, or control over any crypto assets appearing on the Interface; and we do not have possession, custody, or control over any user's funds. Further, we do not store, send, or receive any crypto assets. You understand that when you interact with any ZO Protocol smart contracts, you always retain control over your crypto assets. We do not have access to your private keys.
* 1.1. As a condition to accessing or using the Site or Interface, you represent and warrant to zofinance.io the following:
* * 1.1.1. If you are an individual person, then you are of legal age in the jurisdiction in which you reside, and you have the legal capacity to enter into these Terms and be bound by them;
* 1.1.2. If you are an entity, then you must have the legal authority to accept these Terms on that entity's behalf, in which case "you" (except as used in this paragraph) will mean that entity;
* 1.1.3. You are not a U.S. Person;
* 1.1.4. You are not a resident, national, or agent of any country to which the United States, the United Kingdom, or the European Union embargoes goods or imposes similar sanctions (collectively, "Restricted Territories");
* 1.1.5. You are not subject to economic or trade sanctions administered or enforced by any governmental authority; or otherwise, you are not a member of any sanctions list or equivalent maintained by the United States government, the United Kingdom government, the European Union, or the United Nations, including without limitation the U.S. Office of Foreign Asset Control Specifically Designated Nationals and Blocked Person List (collectively, "Sanctions Lists Persons");
* 1.1.6. You do intend to transact with any Restricted Person or Sanctions List Person;
* 1.1.7. You do not, and will not, use VPN software or any other privacy or anonymization tools or techniques, or other means, to circumvent, or attempt to circumvent, any restrictions that apply; and
* 1.1.8. Your access is not (a) prohibited by and does not otherwise violate or assist you in violating any domestic or foreign law, rule, statute, regulation, by-law, order, protocol, code, decree, letter, or another directive, requirement, guidance, or guideline, published or in force that applies to or is otherwise intended to govern or regulate any person, property, transaction, activity, event or other matter, including any rule, letter, order, judgment, directive or other requirements, guidance, or guideline issued by any domestic or foreign federal, provincial or state, municipal, local or other governmental, regulatory, judicial or administrative authority having jurisdiction over zofinance.io or you as otherwise duly enacted, enforceable by law, the common law or equity (collectively, "Applicable Laws"); or (b) contribute to or facilitate any illegal activity.
* 1.2. As a condition to accessing or using the Site or the Interface, you acknowledge, understand, and agree to the following:
* * 1.2.1. From time to time, the Site or the Interface may be inaccessible or inoperable for any reason, including, but not limited to: (a) equipment malfunctions; (b) periodic maintenance procedures or repairs that zofinance.io or any of its suppliers or contractors may undertake from time to time; (c) causes beyond zofinance.io's control or that zofinance.io could not reasonably foresee; (d) disruptions and temporary or permanent unavailability of underlying blockchain infrastructure; or (e) unavailability of third-party service providers or external partners for any reason;
* 1.2.2. We reserve the right to disable or modify access to the Site at any time in the event of any breach of these Terms, including, without limitation, if we reasonably believe any of your representations and warranties may be untrue or inaccurate, and we will not be liable to you for any losses or damages you may suffer as a result of or in connection with the Site or the Interface being inaccessible to you at any time or for any reason;
* 1.2.3. The Interface may evolve, which means third parties may apply changes, replace, or discontinue (temporarily or permanently) the access at any time in their sole discretion;
* 1.2.4. The pricing information provided on the Site or the Interface does not represent an offer, a solicitation of an offer, or any advice regarding, or recommendation to enter into, a transaction with zofinance.io;
* 1.2.5. zofinance.io does not act as a broker or advisor for you;
* 1.2.6. You are solely responsible for your use of the Site or the Interface, including all of your transfers of digital assets;
* 1.2.7. To the fullest not prohibited by Applicable Law, we owe no fiduciary duties or liabilities to you or any other party, and that to the extent any such duties or liabilities may exist at law or in equity, you hereby irrevocably disclaim, waive, and eliminate those duties and liabilities;
* 1.2.8. You are solely responsible for reporting and paying any taxes applicable to your use of the Interface; and
* 1.2.9. We have no control over, or liability for, the delivery, quality, safety, legality, or any other aspect of any digital assets that you may transfer to or from a third party, and we are not responsible for ensuring that an entity with whom you transact completes the transaction or is authorized to do so. If you experience a problem with any transactions in digital assets using the Site or the Interface, you bear the entire risk.
1. FEES
You are required to pay all fees for transactions involving certain blockchain networks. These fees may include gas costs and all other fees reflected on the Interface at your use, including trading-related fees. zofinance.io does not receive fees for any blockchain transactions or using the Site or the Interface.
1. NO PROFESSIONAL ADVICE OR FIDUCIARY DUTIES
Nothing herein constitutes legal, financial, business, or tax advice, and you are strongly advised to consult an advisor(s) before engaging in any activity in connection herewith. All information provided by the Site is for informational purposes only and should not be construed as professional advice. You should not take, or refrain from taking, any action based on any information contained on the Site or any other information that we make available at any time, including, without limitation, blog posts, articles, links to third-party content, discord content, news feeds, tutorials, tweets, and videos. The Terms are not intended to, and do not, create or impose any fiduciary duties on us.
1. PROPRIETARY RIGHT
* 4.1. zofinance.io owns all rights, names, logos, and other marks used on the Site and the Interface, including, without limitation, any copyrights in and to any content, code, data, or other materials that you may access or use on or through the Site or the Interface; however, the code for the Zo Protocol and the Interface (app.zofinance.io) deployed on IPFS is open-sourced. Except as expressly set forth herein, your use of or access to the Site or the Interface does not grant you any ownership or other rights therein.
* 4.2. zofinance.io may use and share your comments, bug reports, ideas, or other feedback that you may provide, including suggestions about how we might improve. You agree that zofinance.io is free to use or not use any feedback we receive from you as we see fit, including copying and sharing such feedback with third parties, without any obligation to you.
1. MODIFICATION, SUSPENSION, AND TERMINATION
* 5.1. zofinance.io reserve the right, at our sole discretion, from time to time and with or without prior notice to you, to modify, suspend or disable (temporarily or permanently) the Site or our subdomain to the Interface, in whole or in part, for any reason whatsoever, including, without limitation. Upon termination of your access, your right to use the Site or the Interface from our subdomain will immediately cease. However, it would still be accessible via a third party since we do not host or own its code. zofinance.io will not be liable for any losses suffered by you resulting from any modification to the Site or the Interface or from any modification, suspension, or termination, for any reason, of your access to all or any portion of the Site or the Interface.
* 5.2. zofinance.io may revise these Terms from time to time. We will notify you by updating the date at the top of the Terms and maintaining a current version. The most current version of the Terms will always be at . All modifications will be effective when they are posted. By continuing to access or use the Site or the Interface after those revisions become effective, you agree to be bound by the revised Terms.
1. RISKS
* 6.1. The use of technology related to blockchain, smart contracts, and cryptocurrencies, among others, entails a risk that by accessing transactions, you are assuming. zofinance.io does not own or control any underlying software through which blockchain networks are formed. The software underlying blockchain networks are open-source so anyone can use, copy, modify, and distribute it. By using the Interface, you acknowledge and agree:
* * 6.1.1. That zofinance.io is not responsible for the operation of the open-source software and networks underlying the Interface;
* 6.1.2. That there exists no guarantee of the functionality, security, or availability of that software and networks; and
* 6.1.3. That the underlying networks are subject to sudden changes in operating rules, such as those commonly referred to as "forks," which may materially affect the Interface. You are responsible for securing your private key(s). We do not have access to your private key(s); losing control of your private key(s) will permanently and irreversibly deny you access to any blockchain-based network. Neither zofinance.io nor any other person or entity will be able to retrieve or protect your digital assets. If your private key(s) are lost, you will not be able to transfer your digital assets to any blockchain address or wallet. If this occurs, you will not be able to realize any value or utility from the digital assets you may hold.
* 6.2. zofinance.io is not responsible for the content of any third party, including, but not limited to, information, materials, products, or services that zofinance.io does not own or control. In addition, third parties may offer promotions related to your access and use of the Interface. zofinance.io does not endorse or assume any responsibility for such resources or promotions. Suppose you access any such resources or participate in any such promotions. In that case, you do so at your own risk and understand that these Terms do not apply to your dealings or relationships with any third parties. You expressly relieve zofinance.io of all liability arising from using such resources or participating in such promotions.
* 6.3. You understand that the Sui network blockchain remains under development, which creates technological and security risks when using the Interface, in addition to uncertainty relating to digital assets and transactions therein. You acknowledge that the cost of transacting on the Sui network blockchain is variable and may increase at any time, causing an impact on any activities taking place on these blockchains, which may result in price fluctuations or increased costs when using the Interface.
* 6.4. Transactions entered into in connection with the Interface are irreversible and final, and there are no refunds. You acknowledge and agree that you will access and use the Interface at your own risk.
* 6.5. We must comply with Applicable Law, which may require us to, upon request by government agencies, take certain actions or provide information that may not be in your best interests.
* 6.6. You hereby assume and agree that zofinance.io will have no responsibility or liability for the risks in Section 9. You hereby irrevocably waive, release and discharge all claims, whether known or unknown to you, against zofinance.io, its affiliates, and their respective shareholders, members, directors, officers, employees, agents, representatives, suppliers, and contractors related to any of the risks set forth in this Section 6.
1. PROHIBITED USES
* 7.1 You agree not to engage in the prohibited uses set forth below. The specific activities set forth below are representative but not exhaustive. By using the Site or the Interface, you confirm that you will not do any of the following:
* * 7.1.1. Promote or facilitate illegal activities, including but not limited to money laundering, terrorist financing, tax evasion, buying or selling illegal drugs, contraband, counterfeit goods, or illegal weapons;
* 7.1.2. Engage in transactions involving items that infringe or violate any copyright, trademark, right of publicity, privacy, or any other proprietary right of zofinance.io;
* 7.1.3. Engage in improper or abusive trading practices, including but not limited to (a) any fraudulent act or scheme to defraud, deceive, trick, or mislead; (b) trading ahead of another user of the Site or the Interface or front-running; (c) fraudulent trading; (d) accommodation trading; (e) fictitious transactions; (f) pre-arranged or non-competitive transactions; or (g) cornering;
* 7.1.4. Uploading or transmitting viruses, worms, Trojan horses, time bombs, cancelbots, spiders, malware, or any other type of malicious code that will or may be used in any way that will affect the functionality or operation of the Site or the Interface;
* 7.1.5. Use the Site or Interface in any way that is, in our sole discretion, libelous, defamatory, profane, obscene, pornographic, sexually explicit, indecent, lewd, vulgar, suggestive, harassing, stalking, hateful, threatening, offensive, discriminatory, bigoted, abusive, inflammatory, fraudulent, deceptive, or otherwise objectionable or likely or intended to incite, threaten, facilitate, promote, or encourage hate, racial intolerance, or violent acts against others;
* 7.1.6. Harass, abuse, or harm another person or entity, including zofinance.io's collaborator and service providers;
* 7.1.7. Impersonate another user of the Site or the Interface or otherwise misrepresent yourself; or
* 7.1.8. Engage or attempt to engage or encourage, induce or assist any third party, or yourself attempt, to engage in any of the activities prohibited under this Section 4 or any other provision of these Terms.
1. DISCLOSURES; DISCLAIMERS
zofinance.io is an informational site for the Zo Protocol. zofinance.io does not operate an exchange platform or offer trade execution or clearing services and has no oversight, involvement, or control concerning your transactions using the Interface. All transactions between users of the Interface are executed peer-to-peer directly between the users' blockchain addresses through a third-party developed open-source smart contract.You are responsible for complying with all Applicable Laws that govern your Perpetual Contracts. As a result of restrictions under the Commodity Exchange Act and the regulations promulgated thereunder by the U.S. Commodity Futures Trading Commission ("CFTC"), no U.S. Person may enter into Perpetual Contracts using the Interface.You understand that zofinance.io is not registered or licensed by any regulatory agency or authority. No such agency or authority has reviewed or approved the use of the Site or the Interface.You agree that the Site and the Interface are provided on an "AS IS" and "AS AVAILABLE" basis. zofinance.io makes no guarantees of any kind or connection with the Site or the Interface.
1. LIMITATION OF LIABILITY
In no event shall zofinance.io, its affiliates, its suppliers and contractors, and its affiliates', suppliers' and contractors' respective stockholders, members, directors, officers, managers, employees, attorneys, agents, representatives, suppliers, and contractors shall be liable for any direct, indirect, incidental, special, punitive, consequential or similar damages or liabilities whatsoever (including, without limitation, damages for loss of fiat, assets, data, information, revenue, opportunities, use, goodwill, profits or other business or financial benefit) arising out of or in connection with the Site or the Interface, or other item provided by or on behalf of zofinance.io, whether under contract, tort (including negligence), civil liability, statute, strict liability, breach of warranties, or under any other theory of liability, and whether or not we have been advised of, knew of or should have known of the possibility of such damages and notwithstanding any failure of the essential purpose of these Terms or any limited remedy hereunder nor is zofinance.io in any way responsible for the execution or settlement of transactions between users of the Interface.In no event shall zofinance.io's aggregate liability arising out of or in connection with the Site or Interface exceed one thousand Singapore Dollars (1,000.00 SGD).
1. INDEMNIFICATION
You will defend, indemnify, and hold harmless zofinance.io, its affiliates, members, member, managers, employees, attorneys, representatives, suppliers, and contractors from any claim, demand, lawsuit, action, proceeding, investigation, liability, damage, loss, cost or expense, including without limitation reasonable attorneys' fees, arising out of or relating to (a) your use of or conduct in connection with the Site or the Interface (b) your violation of these Terms; or (c) your misuse of the Site or the Interface, or any smart contract and/or script related thereto; (d) your violation of any laws, rules, regulations, codes, statutes, ordinances, or orders of any governmental or quasi-governmental authorities; (e) your violation of the rights of any third party, including any intellectual property right, publicity, confidentiality, property, or privacy right; (f) your use of a third-party product, service, and/or website; or (g) any misrepresentation made by you. We reserve the right to assume, at your expense, the exclusive defense, and control of any matter subject to indemnification by you. You agree to cooperate with our defense of any claim. You will not, in any event, settle any claim without.
1. DISPUTE RESOLUTION & ARBITRATION
zofinance.io will use its best efforts to resolve potential disputes through informal, good faith negotiations. If a potential dispute arises, you must contact us by sending a written notice of your claim ("Notice") to zofinance.io on any of our official channels. The notice must (a) describe the nature and basis of the claim and (b) set forth the specific relief sought. Our notice to you will be similar in form to that described above. If you and zofinance.io cannot reach an agreement to resolve the claim within sixty (60) days of your email, then you and zofinance.io agree to resolve the potential dispute according to the process set forth below\.Any claim or controversy arising out of or relating to the Site, the Interface, or these Terms, or any other acts or omissions for which you may contend that we are liable, including (but not limited to) any claim or controversy as to arbitrability ("Dispute"), shall be finally and exclusively settled by arbitration under the Corte Civil y Mercantil de Arbitraje (CIMA). You understand that you are required to resolve all Disputes by binding arbitration. The arbitration shall be confidential before a single arbitrator, who shall be selected pursuant to the CIMA rules. The arbitration will be held in Madrid, Spain, unless you and we both agree to hold it elsewhere. Unless we agree otherwise, the arbitrator may not consolidate your claims with those of any other party. Any judgment on the award rendered by the arbitrator may be entered in any court of competent jurisdiction.Any claim arising out of or related to these Terms or the Site or the Interface must be filed within one year after such claim arose; otherwise, the claim is permanently barred, which means that you and zofinance.io will not have the right to assert the claim.
1. GOVERNING LAW
The interpretation and enforcement of these Terms, and any dispute related to these Terms, the Site, or the Interface, will be governed by and construed and enforced under the laws of the Bahamas, as applicable.
1. GENERAL INFORMATION
* 13.1. Any right or remedy of zofinance.io set forth in these Terms is in addition to, and not in lieu of, any other right or remedy whether described in these Terms, under Applicable Law, at law, or in equity. The failure or delay of zofinance.io in exercising any right, power, or privilege under these Terms shall not operate as a waiver thereof.
* 13.2. The following sections of these Terms will survive any termination of your access to the Site or the Interface, regardless of the reasons for its expiration or termination, in addition to any other provision which by law or by its nature should survive: Sections 3 through 12.
* 13.3. The invalidity or unenforceability of any of these Terms shall not affect the validity or enforceability of any other of these Terms, all of which shall remain in full force and effect.
* 13.4. zofinance.io will have no responsibility or liability for any failure or delay in performance of the Site or the Interface, or any loss or damage that you may incur, due to any circumstance or event beyond our control, including without limitation any flood, extraordinary weather conditions, earthquake, or other act of God, fire, war, insurrection, riot, labor dispute, accident, any law, order regulation, direction, action or request of the government, communications, power failure, or equipment or software malfunction.
* 13.5. You may not assign or transfer any right to use the Site, the Interface, or any of your rights or obligations under these Terms, without our express prior written consent, including by operation of law or in connection with any change of control. We may assign or transfer any or all of our rights or obligations under these Terms, in whole or part, without notice or obtaining your consent or approval.
* 13.6. These Terms contain the entire agreement between you and zofinance.io and supersede all prior and contemporaneous understandings between the parties regarding the Interface and the Site or the Interface.
* 13.7. In the event of any conflict between these Terms and any other agreement you may have with us, these Terms will control unless the other agreement specifically identifies these Terms and declares that the other agreement supersedes these Terms.
* 13.8. You agree that, except as otherwise expressly provided in these Terms, there shall be no third-party beneficiaries to the Terms other than the Indemnified Parties.
CONTACT INFORMATION
If you have any questions about these Terms, the Site, or the Interface, please get in touch with zofinance.io on any of our official channels.
# Zo Referral Program
Last modified: Feb 24th, 2025
Welcome to Zo.fi ("we," "us," or "our"), the informational resource for Zo Protocol, as defined below\.Zo.fi provides information and resources about the fundamentals of the decentralized non-custodial protocol called the Zo Protocol (the "Zo Protocol," "Zo," or "Zo DApp"). Zo.fi is not an available access point to Zo Protocol.These Terms and Conditions and any other documents incorporated herein by reference (collectively, these "Terms") to you or the company or other legal entity you represent ("you," "your," "the Referrer," "the Affiliate"), explains the terms and conditions by which you may use the Zo Referral Program ("Referral Program") as defined below\.Please do not use the Referral Program if you disagree with any of these Terms.
* USE OF THE REFERRAL PROGRAM
All this content is for informational purposes only.The Referral Program allows you to advertise the Zo DApp, thereby driving traffic to it, whereby you may earn a portion of the fees generated ("Rebates") if a person that is not you ("Trader," "Referred User") trades in the Zo DApp after being referred to it from a hyperlink ("Link") or manually input code ("Referral Code"). The Trader will benefit from a fee discount ("Discount") associated with the Referrer's tier.After being referred to the Zo DApp from a Link, the Trader's browser will save your Referral Code, which will be assigned to the Trader on his first trade.A Trader can also manually enter your Referral Code in the Traders section and change it at any time.
* OBLIGATIONS
2.1 As an Affiliate, Zo DApp provides you with the Links and Referral Codes necessary to promote the Zo Protocol. You acknowledge and agree it is your sole responsibility to indicate your correct Referral Code. You may promote the Zo Protocol offers in any manner you choose unless it misleads someone about the Zo Protocol.2.2 Zo.fi is not responsible for (i) lost sales or lost opportunity to earn Rebates due to any cause, such as technical difficulties or over-capacity, including system overload in the Sui network blockchains; (ii) tracking Rebates, Discounts, or any other data, as this is handled by independent, smart contracts.2.3 You will be excluded from the Referral Program, following the directives of the ABX tokenholders: (i) if you use any language libelous, defamatory, profane, obscene, pornographic, sexually explicit, indecent, lewd, vulgar, suggestive, harassing, stalking, hateful, threatening, offensive, discriminatory, bigoted, abusive, inflammatory, fraudulent, deceptive, or otherwise objectionable or likely or intended to incite, threaten, facilitate, promote, or encourage hate, racial intolerance, or violent acts against others; (ii) if you try any form of gaming through self-referrals.
* REBATES AND DISCOUNTS
Referrers will receive rebates based on a sliding percentage of fees paid by Referred Users. Rebates will never be retroactive.zofinance.io is under no obligation for Rebates or Discounts to any Referrer or Trader. Rebates and Discounts are handled following the directives of the ABX tokenholders.The Rebates and Discounts percentages for the default tier Tier 1, and instructions to upgrade to Tier 2 and Tier 3, are contained in[ ](https://abex-protocol.gitbook.io/abex/terms-and-conditions/abex-terms-and-conditions/abex-referral-program)
* LIMITATION OF LIABILITY
Under no circumstances shall zofinance.io be liable for any direct, indirect, incidental, punitive, special, consequential damages, or similar damages or liabilities whatsoever for any reason whatsoever related to these Terms, your use or inability to use our web site(s), or the materials and content of the web site(s) or any other web sites linked to such web site(s) or your provision of any personally identifiable information to a backend service provider or any third party. This limitation applies regardless of whether the alleged liability is based on contract, tort, warranty, negligence, strict liability, or any other basis, even if we have been advised of the possibility of such damages or such damages were reasonably foreseeable.In no event shall zofinance.io's aggregate liability arising out of or in connection with the Site exceed five hundred Singapore Dollars (500 SGD).
* INDEMNIFICATION
You will defend, indemnify, and hold harmless abexfi, its affiliates, members, member, managers, employees, attorneys, representatives, suppliers, and contractors from any claim, demand, lawsuit, action, proceeding, investigation, liability, damage, loss, cost or expense, including without limitation reasonable attorneys' fees, arising out of or relating to arising under these Terms, the service(s) provided by zofinance.io, or your use of the service(s) provided by zofinance.io, including, without limitation, an infringement by you, or by anyone else using such service(s) we provide to you, of any intellectual property or other proprietary rights of any person or entity, or from the violation of any of our operating rules or policies relating to the service(s) provided. When we may be involved in a suit involving a third party and which is related to our service(s) to you under these Terms, we may seek written assurances from you in which you promise to defend, indemnify and hold us harmless from the costs and liabilities described in this paragraph. Such written assurances may include, in our sole discretion, the posting of a performance bond(s) or other guarantees reasonably calculated to guarantee payment. We may consider your failure to provide such assurances a breach of these Terms by you. The terms of this paragraph will survive any termination or cancellation of the Terms.
* MODIFICATION, SUSPENSION, AND TERMINATION
The Referral Program runs independently from zofinance.io, which the token holders of ABX determine. Due to this, from time to time and with or without prior notice to you, the Referral Program could be subject to modifications, suspensions, or disabilities, in whole or in part, for any reason whatsoever.zofinance.io will not be liable for any losses suffered by you resulting from any modification to the Referral Program or from any modification, suspension, or termination, for any reason, of your access to all or any portion of the Interface or the Protocol.zofinance.io may revise these Terms from time to time. We will notify you by updating the date at the top of the Terms and maintaining a current version. The most current version of the Terms will always be at[ https://zofinance.io/referral-terms](https://abex-protocol.gitbook.io/abex/terms-and-conditions/abex-terms-and-conditions/abex-referral-program). All modifications will be effective when they are posted. By using the Referral Program after those revisions become effective, you agree to be bound by the revised Terms.
* GOVERNING LAW
The interpretation and enforcement of these Terms, and any dispute related to these Terms, the Site, or the Interface, will be governed by and construed and enforced under the laws of the Singapore, as applicable.
* GENERAL
8.1 These Terms, including other policies or agreements incorporated herein, constitute the entire and only agreement between you and zofinance.io concerning the subject matter of these Terms and supersede all prior or contemporaneous agreements, representations, warranties, and understandings, written or oral, concerning the subject matter of these Terms. Any failure by us to exercise or enforce any right or provision of the Terms shall not constitute a waiver of such right or provision.8.2 You must legally be able to enter into the Terms. Using the Referral Program, you represent and warrant that you meet the eligibility requirement. If you do not meet the requirement, you must not access the Referral Program.8.3 Nothing contained herein will be construed to create the relationship of principal and agent, employer and employee, partners or joint venturers. Each party shall ensure that the foregoing persons shall not represent to the contrary, either expressly, implicitly, by appearance, or otherwise.8.4 If any provision of these Terms shall be unenforceable or invalid under any applicable law or be held by any applicable court decision, such unenforceability or invalidity shall not render these Terms unenforceable or invalid as a whole. zofinance.io will amend or replace such provision with one that is valid and enforceable and which achieves, to the extent possible, our original objectives and intent as reflected in the original provision.8.5 You may not assign or transfer any right to use the Referral Program, or any of your rights or obligations under these Terms, without our express prior written consent, including by operation of law or in connection with any change of control. zofinance.io may assign or transfer any or all of our rights or obligations under these Terms, in whole or part, without notice or obtaining your consent or approval.8.6 zofinance.io will have no responsibility or liability for any failure or delay in performance of the Site, or any loss or damage that you may incur, due to any circumstance or event beyond our control, including without limitation any flood, extraordinary weather conditions, earthquake, or other act of God, fire, war, insurrection, riot, labor dispute, accident, any law, order regulation, direction, action or request of the government, communications, power failure, or equipment or software malfunction.
CONTACT INFORMATION
If you have any questions about these Terms, the Site, or the Interface, please get in touch with zofinance.io on any of our official channels.
# Building on ZO
Enable perpetuals trading and earn rebates using our SDK
### Summary
* [ZO SDK](/building-on-zo/zo-sdk): Typescript ZO SDK for perpetuals trading and LP operations
* [Trading Widget](/building-on-zo/trading-widget): React Perpetual Trading Widget
* [Automated Trading Bot](/building-on-zo/automated-trading-bot): Example Trading Bot that leverages zo-sdk
# ZO SDK
Integrate ZO with our Typescript SDK
## Summary
* [Introduction](/building-on-zo/zo-sdk/introduction)
* [Architecture](/building-on-zo/zo-sdk/architecture)
* [Getting Started](/building-on-zo/zo-sdk/getting-started)
* [Common Operations](/building-on-zo/zo-sdk/common-operations)
* [Trading Examples](/building-on-zo/zo-sdk/trading-examples)
* [Swap Examples](/building-on-zo/zo-sdk/swap-examples)
* [Type Safety](/building-on-zo/zo-sdk/type-safety)
* [Error Handling](/building-on-zo/zo-sdk/error-handling)
* [API Reference](/building-on-zo/zo-sdk/api-reference)
### NPM
{% embed url="" %}
# 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 @zofai/zo-sdk
# or
yarn add @zofai/zo-sdk
# or
pnpm add @zofai/zo-sdk
```
For the full guide, see Getting Started.
# Architecture
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
### Key Components
1. **Common Interfaces**: Unified API surface for all LP tokens (`IBaseAPI`, `IBaseDataAPI`)
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()`)
# 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 '@zofai/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.zofinance.io'
const connectionURL = 'https://hermes.pyth.network'
// 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
```
# Common Operations
These operations work across all LP tokens (ZLP, SLP, USDZ).
### Data / read operations
Use the API or DataAPI; the methods are the same.
```typescript
const zlpMarket = await zlpAPI.valuateMarket()
const slpMarket = await slpAPI.getMarketInfo()
const vaultInfo = await usdzAPI.getVaultInfo('usdc')
const positionCaps = await zlpAPI.getPositionCapInfoList(ownerAddress)
const positions = await zlpAPI.getPositionInfoList(positionCaps, ownerAddress)
```
### Deposit
```typescript
const depositTx = await zlpAPI.deposit(
'usdc', // coin type
['coinObjectId'], // coin object IDs
1000000, // amount
0, // minimum amount out (optional)
'referralAddress', // optional referral
'senderAddress' // optional sender
)
const slpDepositTx = await slpAPI.deposit('usdc', ['coinObjectId'], 1000000)
const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)
```
### Withdraw
```typescript
const withdrawTx = await zlpAPI.withdraw(
'usdc',
['lpCoinObjectId'],
1000000,
0
)
```
### Swap
```typescript
const swapTx = await zlpAPI.swap(
'usdc', // from token
'sui', // to token
BigInt(1000000), // amount
['coinObjectId'] // coin objects
)
```
# 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'
)
```
# Swap Examples
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()`.
### 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.
### Amounts and units
* `fromAmount` is in **atomic units** (raw token units), e.g. `1_000_000` for 1 USDC (6 decimals).
* `minAmountOut` is in **atomic units** of the destination token.
* `calculateSwapFeeBreakdown(fromAmount)` expects atomic units for the source token.
```typescript
// Example: swap 100 USDC (6 decimals) for SUI
const fromAmount = BigInt(100 * 1e6) // 100_000_000 atomic units
```
### Estimate swap fees
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 { SuiClient } from '@mysten/sui/client'
const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
const network = Network.MAINNET
const apiEndpoint = 'https://api.zofinance.io'
const connectionURL = 'https://hermes.pyth.network'
const slpDataAPI = SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)
// fromAmount in atomic units (e.g. 100 USDC = 100 * 1e6)
const fromToken = 'usdc'
const toToken = 'sui'
const fromAmount = 100 * 1e6
const feeBreakdown = await slpDataAPI.calculateSwapFeeBreakdown(fromToken, toToken, fromAmount)
// feeBreakdown contains:
// - swapValue: notional in USD
// - totalVaultsValue: total vault value in USD
// - rebaseFeeInRate, rebaseFeeOutRate: rates for swap-in and swap-out
// - rebaseFeeInValue, rebaseFeeOutValue: rebase fee amounts in USD
// - swapImpactFeeValue: swap impact fee in USD
// - emaVolatilityFeeValue: EMA volatility fee in USD
// - totalFeeValue: sum of all fee components
// - totalFeeRate: totalFeeValue / swapValue
console.log(`Total fee: ${feeBreakdown.totalFeeValue.toFixed(4)} USD`)
console.log(`Fee rate: ${(feeBreakdown.totalFeeRate * 100).toFixed(2)}%`)
```
### Build and submit swap transaction
Use the **API** instance to build the swap transaction. 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.
* `minAmountOut` – optional; minimum output amount in atomic units (slippage protection).
```typescript
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
const fromAmount = BigInt(100 * 1e6) // 100 USDC
const fromCoinObjects = ['0x...'] // user's USDC coin IDs
// Optional: set minAmountOut to protect against slippage
// e.g. 1% slippage: minAmountOut = expectedOut * 0.99
const minAmountOut = 0 // or compute from oracle + slippage
const tx = await slpAPI.swap(
'usdc',
'sui',
fromAmount,
fromCoinObjects,
minAmountOut
)
// Sign with wallet and execute
// const signed = await signAndExecuteTransaction({ transaction: tx })
```
### Swap and return coin to user (swapV2Ptb)
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.
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
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
// Option 1: Standalone swap (tx created internally)
const tx = new Transaction()
const outputCoin = await slpAPI.swapV2Ptb(
'usdc',
'sui',
BigInt(100 * 1e6),
fromCoinObjects,
minAmountOut,
tx
)
// tx is modified in place; sign and execute tx
// Option 2: Compose with other move calls
const composedTx = new Transaction()
const swapCoin = await slpAPI.swapV2Ptb('usdc', 'sui', BigInt(100 * 1e6), fromCoinObjects, minAmountOut, composedTx)
composedTx.transferObjects([swapCoin], composedTx.pure.address(recipientAddress))
```
### Complete integration example
```typescript
import { SDK, LPToken, Network } from '@zofai/zo-sdk'
import { SuiClient } from '@mysten/sui/client'
async function swapWithFeeEstimate(
fromToken: string,
toToken: string,
fromAmountAtomic: number,
fromCoinObjects: string[],
slippageBps: number = 50, // 0.5%
) {
const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
const api = SDK.createSLPAPI(
Network.MAINNET,
provider,
'https://api.zofinance.io',
'https://hermes.zofinance.io'
)
// 1. Estimate fees
const feeBreakdown = await api.dataAPI.calculateSwapFeeBreakdown(
fromToken,
toToken,
fromAmountAtomic
)
// 2. Compute minAmountOut from fee breakdown (net value after fees) and slippage
const toPrice = (await api.getOraclePrice(toToken)).getPriceUnchecked().getPriceAsNumberUnchecked()
const toDecimals = 9 // use deployment consts or lookup
const netValueUsd = feeBreakdown.swapValue - feeBreakdown.totalFeeValue
const expectedOutAtomic = (netValueUsd * (10 ** toDecimals)) / toPrice
const minAmountOut = Math.floor(expectedOutAtomic * (1 - slippageBps / 10000))
// 3. Build transaction
const tx = await api.swap(
fromToken,
toToken,
BigInt(fromAmountAtomic),
fromCoinObjects,
minAmountOut
)
return {
transaction: tx,
feeBreakdown,
}
}
```
### Fee components
| Component | Description |
| ---------------------- | ------------------------------------------------------------------------- |
| **Rebase fee (in)** | Fee on the source token when swapping in; depends on vault utilization. |
| **Rebase fee (out)** | Fee on the destination token when swapping out. |
| **Swap impact fee** | Fee from `SwapImpactConfig`; scales with `swapValue / totalVaultsValue`. |
| **EMA volatility fee** | Fee from `EmaVolatilityFeeConfig`; scales with price divergence from EMA. |
Use `calculateSwapFeeBreakdown` to get the USD value of each component and the total fee before executing the swap.
### 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.
# 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')
```
# Error Handling
The SDK throws errors for invalid operations and network issues. Always wrap API calls in try-catch blocks:
```typescript
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
try {
const marketInfo = await zlpAPI.getMarketInfo()
const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000)
} catch (error) {
console.error('SDK operation failed:', error)
if (error.message.includes('Unsupported LP token')) {
console.error('Invalid LP token type provided')
}
}
```
# API Reference
### Factory methods
**API (full – transactions + data):**
* `SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createAPI(LPToken, network, provider, apiEndpoint, connectionURL)`
**DataAPI (read-only):**
* `SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createUSDZDataAPI(network, provider, apiEndpoint, connectionURL)`
* `SDK.createDataAPI(LPToken, network, provider, apiEndpoint, connectionURL)`
### Interfaces
* **Base**: `IBaseAPI`, `IBaseDataAPI` for common operations
* **LP-specific**: `IZLPAPI`, `ISLPAPI`, `IUSDZAPI` for typed usage
* **Data types**: `IBaseMarketValuationInfo`, `IBaseVaultInfo`, `IBaseSymbolInfo`, `IBasePositionInfo`, `IBaseOrderInfo`, etc.
### Source code
* **Interfaces**: `src/interfaces/` – TypeScript interface definitions
* **Implementations**: `src/implementations/` – Concrete API implementations
* **Abstract classes**: `src/abstract/` – Shared base functionality
* **Factory**: `src/factory/SDKFactory.ts` – SDK instance creation
See the type definitions and source for detailed method signatures and parameters.
# Trading Widget
#### Overview
The ZO Trading Widget (@zofai/trading-widget) is an embeddable perpetuals trading UI for ZO Finance on Sui.It lets you drop a full-featured trading interface into your dapp:
* Market header – Symbol selector, mark price, funding rate
* Price chart – Pyth-powered OHLC with live updates
* Recent trades – Live trade feed
* Trade panel – Open/close positions (market & limit) on ZLP / SLP / USDZ
* Positions / Orders / History – Bottom tabs, each with a countdown to next refresh
* RPC settings – Predefined or custom RPC URL with latency checks
* Wallet – Sui wallet connect via @mysten/dapp-kit-react and an account sidebar
You can either:
* Use the full widget as a single component, or
* Compose custom layouts using the exported components and hooks.
# Requirements
#### Installation
Install the widget from your package registry:
`pnpm add @zofai/trading-widget` or `npm install @zofai/trading-widget` or `yarn add @zofai/trading-widget`
NPM:
{% embed url="" %}
### Peer dependencies
Your app must install:
* `react` & `react-dom` (≥18)
* `jotai` (≥2)
* `@tanstack/react-query` (≥5)
* `@mysten/dapp-kit-react` (≥1) & `@mysten/sui` (≥2)
* `zo-sdk` (≥0.1)
#### Styling
The widget uses Tailwind-compatible utility classes (e.g. `flex`, `text-white`, `rounded-lg`). Either:
* Use **Tailwind CSS** or **UnoCSS** in your app so those classes resolve, or
* Import the bundled CSS once in your app: `import '@zofai/trading-widget/style.css'` . This file contains the compiled UnoCSS used by the widget.
# Quick Start
### Full Widget Layout
1. **Wrap your app** with the required providers (order matters):
```tsx
import { appStore } from '@zofai/trading-widget'
import { Provider as JotaiProvider } from 'jotai'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { DAppKitProvider } from '@mysten/dapp-kit-react'
// Your dapp-kit instance (Sui wallet + network)
import { dAppKit } from './dapp-kit'
const queryClient = new QueryClient({
defaultOptions: {
queries: { staleTime: 60_000, retry: 2 },
},
})
export function Root() {
return (
)
}
```
2. **Render the widget** where you want the trading UI:
```tsx
import { TradingWidget } from '@zo/trading-widget'
export function App() {
return (
{/* Your navbar, connect button, etc. */}
)
}
```
**TradingWidget props**
| Prop | Type | Description |
| ----------- | -------- | ----------------------------------- |
| `symbol` | `string` | Initial symbol (default `"BTC"`) |
| `className` | `string` | Extra class on the widget container |
The default `` contains:
* Header – MarketHeader
* Symbol dropdown (index tokens from ZLP / SLP)
* Mark price
* 1h funding rate
* Main area
* PriceChart (Pyth candlesticks + streaming)
* RecentTrades (live trades)
* TradePanel (open positions, leverage, collaterals)
* Bottom tabs – BottomTabs
* PositionsList
* OrdersList
* HistoryList
* Each tab shows a circular countdown to the next auto-refresh.
* Dialogs & toasts
* Confirmation and success dialogs (open / close / adjust)
* Toast notifications via react-hot-toast.
Use this when you want the fastest integration path.
# Custom Layout
### Custom layout
Use **`TradingWidgetProvider`** and the sub-components to build your own layout:
```tsx
import {
TradingWidgetProvider,
MarketHeader,
PriceChart,
RecentTrades,
TradePanel,
BottomTabs,
CustomConnectButton,
RpcSettings,
} from '@zofai/trading-widget'
export function CustomTradePage() {
return (
)
}
```
Ensure your app is wrapped with **Jotai** (`appStore`), **React Query**, and **DAppKit** as in Quick start.
# Components
#### All-in-one
* **`TradingWidget`** – Full layout: header, chart, recent trades, trade panel, bottom tabs (positions/orders/history), dialogs and toasts.
#### Layout & header
* **`TradingWidgetProvider`** – Sui + React Query + Jotai setup. Use when building a custom layout so sub-components have the same context.
* **`MarketHeader`** – Symbol dropdown (from ZLP/SLP index tokens), mark price, funding rate.
#### Market data
* **`PriceChart`** – Pyth-backed candlestick chart (history + streaming).
* **`RecentTrades`** – Recent trades for the selected symbol.
#### Trading & account
* **`TradePanel`** – Long/short, market/limit, leverage, collateral selector; opens positions on ZLP/SLP/USDZ.
* **`CustomConnectButton`** – Connect wallet; when connected opens the account sidebar instead of a dropdown.
#### Tables (bottom section)
* **`BottomTabs`** – Tabs: Positions, Orders, History; each shows a circular countdown to next refresh.
* **`PositionsList`** – Open positions with PnL, adjust/close.
* **`OrdersList`** – Open orders with cancel.
* **`HistoryList`** – Trade history.
#### Settings
* **`RpcSettings`** – Dropdown: choose predefined RPC or enter custom URL; shows latency. Persists to `localStorage` so the widget’s provider uses the selected RPC.
# Hooks & Store
For custom UIs that need widget data or actions:
**Hooks**
* `useEssential()` – wallet, network, consts (zo/sudo/usdz), accountData, refreshAccount
* `useWallet()`, `useNetwork()` – wallet and current network
* `usePosition(address, network)` – positions list, refresh, `dataUpdatedAt`
* `useOrder(address, network)` – orders list, refresh, `dataUpdatedAt`
* `useHistories(address, network)` – trade history
* `useFundingRate(symbol, network, lpToken)` – funding rate
* `usePositionConfig(network, { symbols })` – position config (fees, etc.)
* `useSymbolInfo(network)` – symbol info map (ZLP/SLP/USDZ)
* `useRpc()` – RPC list, custom URL, latency; used by `RpcSettings`
* `useSponsoredGasAvailability(address, network)` – gas sponsorship
**Store (Jotai)**
* `appStore` – same store instance must be used for the widget and your app (see Quick start).
* `currentSymbolAtom` – `{ symbolId, unit, icon }`; set when user picks a market.
* `tokenPriceAtom` – `{ tokenPrice: Record, isLoading, error }` (Pyth oracle prices).
# RPC and Wallet
* **RPC** – The widget reads RPC from `localStorage`: `is-custom-rpc`, `custom-rpc-url`, `custom-rpc-index`. Use **`RpcSettings`** in your header (or elsewhere) so users can pick a predefined RPC or set a custom URL. After changing RPC, a full page refresh is recommended.
* **Wallet** – Uses **Sui dapp-kit**. Your app must create a `dAppKit` (e.g. with `createDAppKit`) and wrap the tree in `DAppKitProvider`. **`CustomConnectButton`** triggers the kit’s connect flow; when connected, it opens the widget’s account sidebar.
# Example Integration
### Example app
This [repo](https://github.com/zofinance/zo-integration-examples/tree/main/react-ui) includes an example app that integrates the widget
### Stack
* **React 18** + **TypeScript** + **Vite**
* **@zofai/trading-widget** – ZO trading UI and components
* **@mysten/dapp-kit-react** + **@mysten/sui** – Sui wallet connection (mainnet)
* **UnoCSS** – styling (Tailwind-style utilities + shadcn preset)
* **Jotai** – state (via widget `appStore`)
* **TanStack Query** – data fetching
### Setup
```
pnpm install
```
### Scripts
| Command | Description |
| -------------- | ------------------------ |
| `pnpm dev` | Start dev server (Vite) |
| `pnpm build` | Production build |
| `pnpm preview` | Preview production build |
### Project structure
* `src/main.tsx` – App bootstrap: Jotai, React Query, DAppKit, and root ``
* `src/App.tsx` – Layout with header (brand, RPC settings, connect button) and full-height ``
* `src/dapp-kit.ts` – Mysten dApp Kit config (Sui mainnet/testnet gRPC URLs and type registration)
### Requirements
* The widget expects to run inside the providers set up in `main.tsx`: `JotaiProvider` (with `appStore`), `QueryClientProvider`, and `DAppKitProvider`.
* Import the widget styles: `@zofai/trading-widget/style.css`
# Automated Trading Bot
## ZO Trading Bot
Example bot that trades on [ZO Finance](https://zofai.io) using the **zo-sdk**. Supports market orders with take-profit/stop-loss (TPSL), and a grid bot.
{% embed url="" %}
### Prerequisites
* **Node.js** (v18+)
* **pnpm** (or npm)
* A **Sui wallet** with a private key you can export (for automated signing)
* **SUI** on the target network (mainnet/testnet) for gas and trading
### Quick start
#### 1. Install dependencies
```bash
pnpm install
```
#### 2. Configure environment
Copy the example env file and set your secrets (never commit `.env`):
```bash
cp .env.example .env
```
Edit `.env`:
| Variable | Required | Description |
| --------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `NETWORK` | No | `mainnet` or `testnet`. Default: `mainnet`. |
| `SUI_MAINNET_RPC_URL` | No | Sui mainnet RPC. Default: public fullnode. |
| `SUI_TESTNET_RPC_URL` | No | Sui testnet RPC. Default: public fullnode. |
| `PRIVATE_KEY` | **Yes** | Sui private key in **Bech32** format (e.g. `suiprivkey1...`). Used to sign transactions. |
**Getting your Bech32 private key**
* From **Sui CLI**: export the key for your key identity (Bech32 is one of the supported formats).
* From **Sui wallet**: use the wallet’s export feature if it supports Bech32; otherwise you may need to convert.
The app uses `decodeSuiPrivateKey(privateKeyBech32)` from `@mysten/sui/cryptography`, so the key must be in a format that function accepts (e.g. Bech32 `suiprivkey1...`).
#### 3. Run the bot
**Market / TPSL bot** (entry point: `index.ts`):
```bash
pnpm start
```
**Grid bot** (entry point: `grid-bot-run.ts`):
```bash
pnpm run grid
```
Before running, edit the config in the corresponding file (see below).
***
### Integration overview
#### How the bot connects to ZO
1. **Connection** (`connection.ts`)
* Builds a `SuiClient` from `SUI_MAINNET_RPC_URL` or `SUI_TESTNET_RPC_URL` and `NETWORK`.
* Uses **zo-sdk** `SDKFactory` to create API and DataAPI instances for ZLP, SLP, and USDZ pools.
* ZO API endpoint: `https://api.zofinance.io`. Pyth price connection: `https://hermes.pyth.network`.
2. **Keypair** (`keypair.ts`)
* Loads `PRIVATE_KEY` from env and creates an `Ed25519Keypair` via `decodeSuiPrivateKey` + `Ed25519Keypair.fromSecretKey`.
* Used for signing all Sui transactions (opens/closes positions, places/cancels orders).
3. **Trade config**
* You choose pool (`LPToken.ZLP`, `LPToken.SLP`, or `LPToken.USDZ`), index token (e.g. `btc`), collateral (e.g. `nusdc`), sizes, and (for TPSL) take-profit/stop-loss percentages.
#### Config for market / TPSL bot
Edit `index.ts` and set `TradeConfig` (and optionally switch between `tradeWithMarketOrder` and `tradeWithTPSL`):
* `indexToken`, `collateralToken`, `pool`, `long`
* `minSize` / `maxSize` (in index token base units, e.g. 1e8 for BTC) or fixed `size`
* `collateralAmount` (in collateral base units, e.g. 6 decimals for USDC)
* `takeProfitPercentage`, `stopLossPercentage`
* `tradeInterval` (ms), `tradeMode`: `'Market'` or `'TPSL'`
* `createOpposite`: whether to open the opposite position after closing.
#### Config for grid bot
Edit `grid-bot-run.ts` and set the grid config object:
* `indexToken`, `collateralToken`, `pool`
* `gridLowerPrice`, `gridUpperPrice`, `gridLevels`
* `orderSize` (index token base units), `collateralAmount` (collateral base units)
* `pollIntervalMs`, optional `maxVolumeUSD`
Then run:
```bash
pnpm run grid
```
#### Project layout
| File | Purpose |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `index.ts` | Market / TPSL bot entry; defines `TradeConfig` and calls `tradeWithMarketOrder` or `tradeWithTPSL`. |
| `grid-bot-run.ts` | Grid bot entry; defines grid config and calls `runGridBot`. |
| `grid-bot.ts` | Grid bot logic (place/cancel orders, rebalance grid). |
| `trade.ts` | Core trading: open/close positions, TPSL and market flows. |
| `connection.ts` | Sui client and ZO SDK API/DataAPI instances (ZLP/SLP/USDZ). |
| `keypair.ts` | Loads `PRIVATE_KEY` from env and returns Ed25519 keypair. |
| `network.ts` | Reads `NETWORK` from env (mainnet/testnet). |
| `order.ts` | Order caps and order key parsing. |
| `position.ts` | Position helpers. |
| `utils.ts` | Relayer fee, reserve amount, coin helpers. |
| `constants.ts` | Slippage, relayer fee, trade-level constants. |
| `deployments.ts` | Uses `zo-sdk` `getConsts(NETWORK)` for contract addresses. |
#### Dependencies
* **zo-sdk** – ZO protocol API and types (pools, positions, orders).
* **@mysten/sui** – Sui client, keypair, transactions.
* **dotenv** – Loads `.env` into `process.env`.
* **bignumber.js** – Numeric handling for sizes and fees.