dipcoin-cli 0.8.3 → 1.1.0

package/README.md

@@ -1,35 +1,44 @@
-# DipCoin Perpetual Trading SDK & CLI
+# DipCoin Perpetual Trading CLI
 
-TypeScript SDK and CLI for perpetual futures trading on the Sui blockchain.
+TypeScript CLI for perpetual futures trading on the Sui blockchain.
 
-## Installation
+## Usage For AI Agent
 
-**CLI (global):**
+Send the following skill link to your AI Agent, and it will guide you through the rest — including installation, configuration, and trading:
 
-```bash
-npm install -g dipcoin-cli
 ```
+https://raw.githubusercontent.com/dipcoinlab/dipcoin-cli/main/SKILL.md
+```
+
+## Usage For Human
 
-**SDK (as dependency):**
+### Installation
 
 ```bash
-npm install dipcoin-cli
+npm install -g dipcoin-cli
 ```
 
-## CLI Quick Start
-
 ### Configuration
 
-Create a `.env` file in your working directory (or at `~/.config/dipcoin/env` for global config):
+Create a config file at `~/.config/dipcoin/env` (recommended) or `.env` in your working directory:
 
 ```bash
-MNEMONIC=word1 word2 word3 ... word12
-NETWORK=testnet    # or mainnet
+mkdir -p ~/.config/dipcoin
+cat > ~/.config/dipcoin/env << 'EOF'
+DIPCOIN_PRIVATE_KEY=suiprivkey1...
+DIPCOIN_NETWORK=mainnet
+EOF
 ```
 
-Index 0 of the HD derivation path is the main account. Use `--vault-index` for sub-accounts.
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DIPCOIN_PRIVATE_KEY` | One of these | Sui private key (`suiprivkey1...`), supports ED25519/Secp256k1/Secp256r1 |
+| `DIPCOIN_MNEMONIC` | is required | 12-word Sui mnemonic phrase (derives keypair at `m/44'/784'/0'/0'/0'`) |
+| `DIPCOIN_NETWORK` | No | `mainnet` or `testnet` (default: `mainnet`) |
 
-### Basic Workflow
+If both `DIPCOIN_PRIVATE_KEY` and `DIPCOIN_MNEMONIC` are set, the private key takes precedence.
+
+### Quick Start
 
 ```bash
 # Check available pairs
@@ -54,17 +63,16 @@ dipcoin-cli trade sell BTC 0 10x --qty 0.01 --reduce-only
 dipcoin-cli history orders --symbol BTC-PERP
 ```
 
-## CLI Commands
+### Commands
 
-### Global Options
+#### Global Options
 
 | Option | Description |
 |--------|-------------|
 | `--json` | Output in JSON format (machine-readable) |
-| `--vault-index <n>` | Use HD-derived sub-account at index N (placed before subcommand) |
 | `-V, --version` | Show version |
 
-### market
+#### market
 
 ```bash
 dipcoin-cli market pairs                    # List all trading pairs
@@ -75,7 +83,7 @@ dipcoin-cli market oracle <symbol>          # Oracle price
 
 Symbols auto-normalize: `BTC` becomes `BTC-PERP`.
 
-### account
+#### account
 
 ```bash
 dipcoin-cli account info                    # Balance, margin, PnL
@@ -84,13 +92,13 @@ dipcoin-cli account deposit <amount>        # Deposit USDC to exchange
 dipcoin-cli account withdraw <amount>       # Withdraw USDC from exchange
 ```
 
-### balance
+#### balance
 
 ```bash
 dipcoin-cli balance                         # On-chain coin balances
 ```
 
-### trade
+#### trade
 
 ```bash
 # Buy/Sell with USDC margin amount (auto-converts to quantity)
@@ -104,11 +112,15 @@ dipcoin-cli trade buy BTC 100USDC 10x --price 95000
 dipcoin-cli trade buy BTC 100USDC 10x --tp 105000 --sl 90000
 
 # Explicit quantity instead of USDC margin
-dipcoin-cli trade buy BTC 100USDC 10x --qty 0.01
+dipcoin-cli trade buy BTC 0 10x --qty 0.01
 
 # Reduce-only (for closing)
 dipcoin-cli trade sell BTC 0 10x --qty 0.01 --reduce-only
 
+# List open orders
+dipcoin-cli trade orders
+dipcoin-cli trade orders --symbol BTC-PERP
+
 # Cancel orders
 dipcoin-cli trade cancel <symbol> <hash1> [hash2...]
 ```
@@ -122,9 +134,9 @@ dipcoin-cli trade cancel <symbol> <hash1> [hash2...]
 | `--reduce-only` | Reduce-only order |
 | `--tp <price>` | Take profit trigger price |
 | `--sl <price>` | Stop loss trigger price |
-| `--vault <address>` | Vault/creator address (fallback) |
+| `--vault <address>` | Vault/creator address (for trading vault positions) |
 
-### position
+#### position
 
 ```bash
 dipcoin-cli position list                   # List open positions
@@ -145,15 +157,7 @@ dipcoin-cli position margin remove <symbol> <amount>
 
 The `--side` is the **closing side**: use `sell` for long positions, `buy` for short.
 
-### orders
-
-```bash
-dipcoin-cli orders                          # List all open orders
-dipcoin-cli orders --symbol BTC-PERP        # Filter by symbol
-dipcoin-cli orders --vault <address>        # Filter by vault
-```
-
-### vault
+#### vault
 
 On-chain vault operations (DipCoin vault contracts):
 
@@ -162,9 +166,15 @@ dipcoin-cli vault create --name <name> --trader <address> --max-cap <usdc> \
   --min-deposit <usdc> --creator-share <pct> --profit-share <pct> --initial <usdc>
 
 dipcoin-cli vault list                      # List vaults created by wallet
+dipcoin-cli vault list-all                  # List all public vaults (page 1, 10 per page)
+dipcoin-cli vault list-all --page 2 --page-size 20
+dipcoin-cli vault list-all --filter Leading # Filter: All, Leading, Newest, HotDeposit
 dipcoin-cli vault info <vaultId>            # Vault details
+dipcoin-cli vault position <vaultId>       # Your shares & estimated value
+dipcoin-cli vault position <vaultId> --address <addr>  # Query another address
 dipcoin-cli vault deposit <vaultId> <amount>
 dipcoin-cli vault withdraw <vaultId> <shares>
+dipcoin-cli vault withdraw <vaultId> --all # Withdraw all shares
 dipcoin-cli vault fill <vaultId> <requestIDs...> [--markets <ids>]
 dipcoin-cli vault close <vaultId> [--markets <ids>]
 dipcoin-cli vault remove <vaultId>
@@ -177,17 +187,17 @@ dipcoin-cli vault set-min-deposit <vaultId> <amount>
 dipcoin-cli vault set-auto-close <vaultId> [--disable]
 ```
 
-### sub-account
-
-HD-derived sub-account management:
+#### referral
 
 ```bash
-dipcoin-cli sub-account list [--count <n>]  # List derived addresses (default 5)
-dipcoin-cli sub-account setup <index>       # Derive and register sub-account on-chain
-dipcoin-cli sub-account set <subAddress>    # Authorize a sub-account address
+dipcoin-cli referral bind <code>               # Bind a referral code
+dipcoin-cli referral link                      # Get your referral link and invite code
+dipcoin-cli referral change-code <code>        # Change your referral code
+dipcoin-cli referral invitees                  # List your invitees
+dipcoin-cli referral invitees --page 2 --page-size 20
 ```
 
-### history
+#### history
 
 ```bash
 dipcoin-cli history orders [--symbol <s>] [--page <n>] [--size <n>]
@@ -197,210 +207,12 @@ dipcoin-cli history balance [--page <n>] [--size <n>]
 
 All history commands support `--vault <address>` and `--begin-time <ms>`.
 
-## Multi-Vault Workflow
-
-The CLI uses HD key derivation from your mnemonic. Index 0 is the main account, index 1+ are sub-accounts.
-
-```bash
-# List derived addresses
-dipcoin-cli sub-account list
-
-# Register sub-account 1 on-chain
-dipcoin-cli sub-account setup 1
-
-# Deposit to sub-account 1
-dipcoin-cli --vault-index 1 account deposit 100
-
-# Trade on sub-account 1
-dipcoin-cli --vault-index 1 trade buy BTC 50USDC 10x
-
-# Check sub-account 1 positions
-dipcoin-cli --vault-index 1 position list
-```
-
-`--vault-index` is always a **global option** placed before the subcommand.
-
-## SDK Usage
-
-### Initialize
-
-```typescript
-import { initDipCoinPerpSDK } from "dipcoin-cli";
-import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
-
-const keypair = Ed25519Keypair.deriveKeypair("your mnemonic phrase ...");
-const sdk = initDipCoinPerpSDK(keypair, { network: "mainnet" });
-
-// With sub-account for vault trading
-const subKeypair = Ed25519Keypair.deriveKeypair("your mnemonic", "m/44'/784'/1'/0'/0'");
-const vaultSdk = initDipCoinPerpSDK(keypair, { network: "mainnet", subAccountKey: subKeypair });
-```
-
-### Authentication
-
-```typescript
-const authResult = await sdk.authenticate();
-if (authResult.status) {
-  console.log("Authenticated:", authResult.data);
-}
-
-// All API methods auto-authenticate when needed
-```
-
-### Account Info
-
-```typescript
-const info = await sdk.getAccountInfo();
-if (info.status && info.data) {
-  console.log("Balance:", info.data.walletBalance);
-  console.log("Free Collateral:", info.data.freeCollateral);
-}
-```
-
-### Deposit & Withdraw
-
-```typescript
-// On-chain transactions (USDC to/from exchange)
-await sdk.depositToBank(100);    // 100 USDC
-await sdk.withdrawFromBank(50);  // 50 USDC
-```
-
-### Place Order
-
-```typescript
-import { OrderSide, OrderType } from "dipcoin-cli";
-
-// Market order
-const result = await sdk.placeOrder({
-  symbol: "BTC-PERP",
-  side: OrderSide.BUY,
-  orderType: OrderType.MARKET,
-  quantity: "0.1",
-  leverage: "10",
-});
-
-// Limit order
-const limit = await sdk.placeOrder({
-  symbol: "BTC-PERP",
-  side: OrderSide.BUY,
-  orderType: OrderType.LIMIT,
-  quantity: "0.1",
-  price: "95000",
-  leverage: "10",
-});
-
-// With TP/SL
-const withTpSl = await sdk.placeOrder({
-  symbol: "BTC-PERP",
-  side: OrderSide.BUY,
-  orderType: OrderType.MARKET,
-  quantity: "0.1",
-  leverage: "10",
-  tpTriggerPrice: "105000",
-  slTriggerPrice: "90000",
-});
-```
-
-### Position TP/SL
-
-```typescript
-await sdk.placePositionTpSlOrders({
-  symbol: "BTC-PERP",
-  market: "<perpetual-id>",
-  side: OrderSide.SELL,
-  isLong: true,
-  leverage: "10",
-  quantity: "0.1",
-  tp: { triggerPrice: "105000", orderType: OrderType.MARKET, tpslType: "position" },
-  sl: { triggerPrice: "90000", orderType: OrderType.MARKET, tpslType: "position" },
-});
-```
-
-### Market Data
-
-```typescript
-const ticker = await sdk.getTicker("BTC-PERP");
-const orderBook = await sdk.getOrderBook("BTC-PERP");
-const oraclePrice = await sdk.getOraclePrice("BTC-PERP");
-const pairs = await sdk.getTradingPairs();
-```
-
-### Cancel Order
-
-```typescript
-await sdk.cancelOrder({
-  symbol: "BTC-PERP",
-  orderHashes: ["0x1234..."],
-});
-```
-
-### Positions & Open Orders
-
-```typescript
-const positions = await sdk.getPositions();
-const orders = await sdk.getOpenOrders();
-```
-
-### Leverage & Margin
-
-```typescript
-await sdk.adjustLeverage({ symbol: "BTC-PERP", leverage: "10", marginType: "ISOLATED" });
-await sdk.addMargin({ symbol: "BTC-PERP", amount: 5 });
-await sdk.removeMargin({ symbol: "BTC-PERP", amount: 2 });
-```
-
-## Types
-
-```typescript
-enum OrderSide { BUY = "BUY", SELL = "SELL" }
-enum OrderType { MARKET = "MARKET", LIMIT = "LIMIT" }
-
-interface AccountInfo {
-  walletBalance: string;
-  totalUnrealizedProfit: string;
-  accountValue: string;
-  freeCollateral: string;
-  totalMargin: string;
-}
-
-interface Position {
-  symbol: string; side: string; quantity: string;
-  avgEntryPrice: string; leverage: string; margin: string;
-  unrealizedProfit: string; liquidationPrice: string;
-}
-
-interface OpenOrder {
-  hash: string; symbol: string; side: string;
-  orderType: string; price: string; quantity: string;
-  filledQty: string; leverage: string; status: string;
-}
-
-interface SDKResponse<T> {
-  status: boolean;
-  data?: T;
-  error?: string;
-}
-```
-
-## Error Handling
-
-All SDK methods return `SDKResponse<T>`. Check `status` before accessing `data`:
-
-```typescript
-const result = await sdk.placeOrder(/* ... */);
-if (result.status) {
-  console.log(result.data);
-} else {
-  console.error(result.error);
-}
-```
-
 ## Development
 
 ```bash
 npm run cli              # Run CLI in dev mode (tsx)
 npm run build            # Build for distribution
-npm run example          # Run example script
+npm run lint             # Run ESLint
 ```
 
 ## License