@waterx/perp-sdk

TypeScript SDK for the WaterX perpetual protocol on Sui: build PTBs with gRPC (@mysten/sui), run read-only simulateTransaction queries, and optional Pyth helpers.

ABI note: PTB entry points follow contracts/waterx_perp in this repo. Read-only view::* helpers resolve the module package from each shared object’s on-chain type (so Market / WlpPool can sit on a newer publish than GlobalConfig / AccountRegistry). BCS layouts for MarketSummary, PositionInfo, and TokenPoolSummary match the deployed view structs (see contracts/waterx_perp/package_summaries/waterx_perp/view.json). Pin WaterXConfig to your environment’s package and object IDs.

Install & build

pnpm install
pnpm build

Consumers:

pnpm add @waterx/perp-sdk @mysten/sui

Breaking changes (WLP high-level builders)

buildMintWlpTx and buildSettleRedeemWlpTx are async and return Promise<Transaction> (they resolve deposit / redeem coin oracle wiring). Callers must await:

const tx = await buildMintWlpTx(client, params);
const tx2 = await buildSettleRedeemWlpTx(client, { requestId: 1n });

Naming: collateral on an open position

Move entry points are deposit_collateral_request / withdraw_collateral_request. The SDK exposes depositCollateral / withdrawCollateral as the preferred names; increaseCollateral / releaseCollateral remain as deprecated aliases (same parameters). High-level helpers: buildDepositCollateralTx / buildWithdrawCollateralTx (deprecated: buildIncreaseCollateralTx / buildReleaseCollateralTx).

Withdraw paths take collateralAmount for the size to pull from margin; amount is a deprecated alias (if both are passed, collateralAmount wins).

UserAccount address in PTB params

Trading (openPosition, closePosition, …), account helpers (depositToAccount, delegates, …), high-level build*Tx, and orders (placeOrder, cancelOrder) all use accountObjectAddress: the UserAccount object id (hex). Trading paths pass it as tx.pure.address; registry calls use tx.pure.id. It is not a numeric registry index.

getAccountsByOwner returns accountObjectAddress on each AccountInfo row.

High-level build*Tx helpers also accept optional collateralTokenType (defaults to WaterXConfig.usdcType). Only token types wired in resolveTokenPriceFeed (src/tx-builders.ts) get automatic Pyth updates; extend there when the protocol adds collaterals.

---

Initialize the client

All network I/O uses gRPC (SuiGrpcClient). Trading helpers require bucketFrameworkPackageId (Bucket bucket_v2_framework package) so the PTB can call account::request.

Testnet (built-in constants):

import { WaterXClient } from "@waterx/perp-sdk";

const client = WaterXClient.testnet();
// optional: custom fullnode gRPC URL
// const client = WaterXClient.testnet({ grpcUrl: "https://fullnode.testnet.sui.io:443" });

Custom config (any network):

import { WaterXClient, createTestnetConfig, type WaterXConfig } from "@waterx/perp-sdk";

const config: WaterXConfig = {
  ...createTestnetConfig(),
  packageId: "0x...", // your deployed waterx_perp package
  globalConfig: "0x...",
  // ...all other object IDs and token type strings
};
const client = new WaterXClient(config);

---

Examples

Read-only: pool summary & WLP metrics

Uses gRPC simulateTransaction + BCS (no signer).

import { WaterXClient, getPoolSummary, getWlpTotalSupply, getWlpTvlUsd } from "@waterx/perp-sdk";

const client = WaterXClient.testnet();

const pool = await getPoolSummary(client);
console.log("LP supply (raw):", pool.totalLpSupply.toString());
console.log("TVL (u128):", pool.tvlUsd.toString());

const supply = await getWlpTotalSupply(client);
const tvl = await getWlpTvlUsd(client);

Read-only: accounts & position

import {
  WaterXClient,
  getAccountsByOwner,
  getPosition,
  positionExists,
} from "@waterx/perp-sdk";

const client = WaterXClient.testnet();
const owner = "0x..."; // Sui address

const accounts = await getAccountsByOwner(client, owner);
const accountObjectAddress = accounts[0]!.accountObjectAddress;

const market = client.config.btcMarket;
const has = await positionExists(client, market, 0n);
if (has) {
  const pos = await getPosition(client, market, 0n);
  // `accountObjectAddress` = on-chain `user_address`; `marketIndex` = pool row index (not Market object id).
  console.log(pos.accountObjectAddress, pos.marketIndex, pos.sizeAmount);
}

High-level PTB: open position (Pyth + testnet IDs wired in)

Returns a Transaction you sign and execute with the same client.

import { WaterXClient, buildOpenPositionTx } from "@waterx/perp-sdk";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";

const client = WaterXClient.testnet();
// Use your own keypair or any @mysten/sui Signer (e.g. wallet adapter).
const keypair = Ed25519Keypair.generate();

const tx = await buildOpenPositionTx(client, {
  accountObjectAddress: "0x...", // UserAccount object id (hex), not a numeric id
  base: "BTC",
  isLong: true,
  leverage: 10,
  collateralAmount: 1_000_000_000n, // 1000 USDC if 6 decimals
});

const result = await client.signAndExecuteTransaction({
  transaction: tx,
  signer: keypair,
});
console.log(result.digest);

Low-level PTB: same flow, your oracle wiring

Create a Transaction, append Pyth / aggregator calls (updatePythPrices, buildPythRuleFeedCalls from this package — mirror src/tx-builders.ts), then call openPosition(client, tx, openPositionParams) (or any other builder in src/user/). Params are typed as OpenPositionParams, ClosePositionParams, etc.

---

API overview

Core

Export	Purpose
WaterXClient	gRPC client, simulate(), signAndExecuteTransaction()
createTestnetConfig()	Default testnet package/object/token IDs + Pyth config
WaterXConfig	Full config; must include bucketFrameworkPackageId for trading PTBs

Transaction builders (append to Transaction)

Group	Functions
Shared	accountSenderRequest(tx, client)
Trading	openPosition, closePosition, increasePosition, decreasePosition, depositCollateral, withdrawCollateral (increaseCollateral / releaseCollateral deprecated), liquidate, matchOrders, updateFundingRate
Orders	placeOrder, cancelOrder
WLP	mintWlp, requestRedeemWlp, cancelRedeemWlp, settleRedeemWlp
Account	createAccount, depositToAccount, receiveCoin, transferAccount, addDelegate, removeDelegate, updateDelegatePermissions
Referral	setReferralCode, useReferralCode, registerReferralCode, bindReferral

Param types: OpenPositionParams, IncreasePositionParams, DecreasePositionParams, etc. (see src/index.ts).

Read-only queries (simulate + BCS)

Area	Functions
Account	getAccountsByOwner, getAccountDelegates, getAccountObjectId (deprecated — use accountObjectAddress directly), getAccountCoins, getAccountBalance, selectCoinsForAmount
Market / pool	getMarketSummary (view::market_summary<LP> — optional typeArgs: LP type string or { lpTokenType? } only), getPoolSummary, getWlpTotalSupply, getWlpTvlUsd, getTokenPoolSummary
Position	getPosition, positionExists (same LP type-arg rules as getMarketSummary)

View return shapes: MarketSummary includes marketIndex (on-chain index). PositionInfoView exposes marketIndex (bigint) and accountObjectAddress (from user_address). getTokenPoolSummary maps TokenPoolSummary.lastPriceRefreshTimestamp when the return payload includes it; older 72-byte deployments surface 0n (see parseTokenPoolSummaryReturn in fetch.ts).

High-level PTB helpers

buildOpenPositionTx, buildClosePositionTx, buildIncreasePositionTx, buildDecreasePositionTx, buildDepositCollateralTx, buildWithdrawCollateralTx (buildIncreaseCollateralTx / buildReleaseCollateralTx deprecated), buildPlaceOrderTx, buildCancelOrderTx (all async, Pyth-backed). buildMintWlpTx and buildSettleRedeemWlpTx are also async (deposit / redeem coin oracle). buildRequestRedeemWlpTx (requires recipient), buildCancelRedeemWlpTx.

Constants & Pyth

Permission bits, order tags, testnet IDs, Pyth feeds: src/constants.ts.
On testnet, TESTNET_TYPES.WLP is the LP type wired to the live WlpPool / Market (wlp_token::WLP_TOKEN); TESTNET_PACKAGE_IDS.WLP_STANDALONE points at the standalone contracts/wlp publish for reference.
Oracle wiring: fetchPriceFeedsUpdateData, updatePythPrices, buildPythRuleFeedCalls, PythCache, etc. in src/utils/pyth.ts.

---

Development

Command	Use
pnpm typecheck	Typecheck
pnpm test	Tests
pnpm lint / pnpm format	Prettier
pnpm codegen	Regenerate src/generated from Move