@decibeltrade/sdk 0.1.1

package/readme.md

@@ -0,0 +1,257 @@
+# @decibeltrade/sdk
+
+TypeScript SDK for interacting with Decibel, a fully on-chain trading engine built on Aptos.
+
+**📚 [View Full Documentation →](https://docs.decibel.trade)**
+
+## Overview
+
+The Decibel TypeScript SDK provides a clean, typed interface to interact with Decibel on Aptos:
+
+- **Read operations** (`DecibelReadDex`) — Query markets, depth, prices, trades, positions, orders, subaccounts, vaults
+- **Write operations** (`DecibelWriteDex`) — Place/cancel orders, manage positions and subaccounts, vault operations, delegation
+
+## Installation
+
+```bash
+npm install @decibeltrade/sdk @aptos-labs/ts-sdk zod
+```
+
+```bash
+yarn add @decibeltrade/sdk @aptos-labs/ts-sdk zod
+```
+
+```bash
+pnpm add @decibeltrade/sdk @aptos-labs/ts-sdk zod
+```
+
+For TypeScript in Node.js environments, you may also want:
+
+```bash
+npm install -D @types/ws
+```
+
+## Quick Start
+
+### Read: Market and Account Data
+
+```typescript
+import { DecibelReadDex, NETNA_CONFIG } from "@decibeltrade/sdk";
+
+const read = new DecibelReadDex(NETNA_CONFIG, {
+  nodeApiKey: process.env.APTOS_NODE_API_KEY, // required
+});
+
+// Get all markets
+const markets = await read.markets.getAll();
+
+// Get account overview
+const account = await read.accountOverview.getByAddr("0x...account");
+
+// Get market prices
+const prices = await read.marketPrices.getAll();
+
+// Get order book depth
+const depth = await read.marketDepth.getBySymbol("BTC-PERP", { depth: 10 });
+```
+
+### Write: Submit Transactions
+
+```typescript
+import { DecibelWriteDex, NETNA_CONFIG } from "@decibeltrade/sdk";
+import { Ed25519Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";
+
+const account = new Ed25519Account({
+  privateKey: new Ed25519PrivateKey(process.env.PRIVATE_KEY!),
+});
+
+const write = new DecibelWriteDex(NETNA_CONFIG, account, {
+  nodeApiKey: process.env.APTOS_NODE_API_KEY, // optional
+});
+
+// Place an order
+const order = await write.placeOrder({
+  subaccountAddr: "0x...",
+  marketAddr: "0x...",
+  price: 5670000000, // 5.67 with 9 decimals
+  size: 1000000000, // 1.0 with 9 decimals
+  isBuy: true,
+  timeInForce: 0, // GoodTillCanceled
+});
+```
+
+## Documentation
+
+### Getting Started
+
+- [SDK Overview](https://docs.decibel.trade/typescript-sdk/overview) - Introduction to the TypeScript SDK
+- [Installation](https://docs.decibel.trade/typescript-sdk/installation) - Install and configure the SDK
+- [Configuration](https://docs.decibel.trade/typescript-sdk/configuration) - Network configuration and presets
+
+### Read SDK
+
+- [Read SDK Guide](https://docs.decibel.trade/typescript-sdk/read-sdk) - Query market data and account information
+  - Market data (prices, depth, trades, candlesticks)
+  - Account overview and positions
+  - Order history and open orders
+  - Subaccounts and delegations
+  - Vault information
+
+### Write SDK
+
+- [Write SDK Guide](https://docs.decibel.trade/typescript-sdk/write-sdk) - Build and submit transactions
+  - Place and cancel orders
+  - TWAP and bulk orders
+  - Position management (TP/SL)
+  - Subaccount management
+  - Vault operations
+  - Delegation
+
+### Advanced
+
+- [Advanced Usage](https://docs.decibel.trade/typescript-sdk/advanced) - Advanced SDK features and patterns
+
+## Configuration
+
+The SDK supports multiple network configurations:
+
+```typescript
+import { NETNA_CONFIG, TESTNET_CONFIG, LOCAL_CONFIG } from "@decibeltrade/sdk";
+
+// Netna (devnet)
+const read = new DecibelReadDex(NETNA_CONFIG);
+
+// Testnet
+const read = new DecibelReadDex(TESTNET_CONFIG);
+
+// Local development
+const read = new DecibelReadDex(LOCAL_CONFIG);
+```
+
+### Custom Configuration
+
+```typescript
+import { DecibelConfig } from "@decibeltrade/sdk";
+import { Network } from "@aptos-labs/ts-sdk";
+
+const customConfig: DecibelConfig = {
+  network: Network.CUSTOM,
+  fullnodeUrl: "https://api.testnet.aptoslabs.com/v1",
+  tradingHttpUrl: "https://api.testnet.aptoslabs.com/decibel",
+  tradingWsUrl: "wss://api.testnet.aptoslabs.com/decibel/ws",
+  // ... other config options
+};
+```
+
+## When to Use Which
+
+- **Use `DecibelReadDex`** when you need market data, order/position history, or account state. No private keys required.
+- **Use `DecibelWriteDex`** for on-chain actions and trading. In browsers, avoid embedding private keys — prefer session keys or a wallet and pass `accountOverride` for specific calls.
+
+## WebSocket Subscriptions
+
+The SDK supports real-time WebSocket subscriptions:
+
+```typescript
+import { DecibelReadDex, NETNA_CONFIG } from "@decibeltrade/sdk";
+
+const read = new DecibelReadDex(NETNA_CONFIG);
+
+// Subscribe to market prices
+const subscription = read.subscribe("all_market_prices", (data) => {
+  console.log("Market prices:", data);
+});
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+## Examples
+
+### Get Market Data
+
+```typescript
+const markets = await read.markets.getAll();
+const btcMarket = await read.markets.getBySymbol("BTC-PERP");
+const prices = await read.marketPrices.getAll();
+const depth = await read.marketDepth.getBySymbol("BTC-PERP", { depth: 20 });
+```
+
+### Get Account Information
+
+```typescript
+const account = await read.accountOverview.getByAddr(accountAddress);
+const positions = await read.userPositions.getByAddr(accountAddress);
+const openOrders = await read.userOpenOrders.getByAddr(accountAddress);
+const subaccounts = await read.userSubaccounts.getByAddr(accountAddress);
+```
+
+### Place an Order
+
+```typescript
+const order = await write.placeOrder({
+  subaccountAddr: subaccountAddress,
+  marketAddr: marketAddress,
+  price: 5670000000, // 5.67 with 9 decimals
+  size: 1000000000, // 1.0 with 9 decimals
+  isBuy: true,
+  timeInForce: 0, // GoodTillCanceled
+  isReduceOnly: false,
+});
+```
+
+### Place a TWAP Order
+
+```typescript
+const twapOrder = await write.placeTwapOrder({
+  subaccountAddr: subaccountAddress,
+  marketAddr: marketAddress,
+  totalSize: 10000000000, // 10.0 with 9 decimals
+  duration: 3600, // 1 hour in seconds
+  interval: 60, // 1 minute intervals
+  isBuy: true,
+});
+```
+
+## API Reference
+
+### DecibelReadDex
+
+- `markets` - Market information and listings
+- `marketPrices` - Real-time and historical prices
+- `marketDepth` - Order book depth
+- `marketTrades` - Recent trades
+- `candlesticks` - OHLCV candlestick data
+- `accountOverview` - Account summary and equity
+- `userPositions` - User positions
+- `userOpenOrders` - Open orders
+- `userOrderHistory` - Order history
+- `userTradeHistory` - Trade history
+- `userSubaccounts` - Subaccount management
+- `userVaults` - Vault positions
+- `vaults` - Public vault information
+- `subscribe()` - WebSocket subscriptions
+
+### DecibelWriteDex
+
+- `placeOrder()` - Place a limit or market order
+- `cancelOrder()` - Cancel an order
+- `placeTwapOrder()` - Place a TWAP order
+- `cancelTwapOrder()` - Cancel a TWAP order
+- `placeBulkOrder()` - Place multiple orders
+- `cancelBulkOrder()` - Cancel multiple orders
+- `placeTpSlOrder()` - Place TP/SL orders
+- `updateTpOrder()` - Update take profit order
+- `updateSlOrder()` - Update stop loss order
+- `createSubaccount()` - Create a new subaccount
+- `deposit()` - Deposit funds
+- `withdraw()` - Withdraw funds
+- `delegateTrading()` - Delegate trading permissions
+
+## Resources
+
+- 📚 [Full Documentation](https://docs.decibel.trade) - Complete API and transaction documentation
+- 🔌 [REST API](https://docs.decibel.trade/api-reference/user/get-account-overview) - REST API reference
+- 🔌 [WebSocket API](https://docs.decibel.trade/api-reference/websockets/bulkorderfills) - WebSocket API reference
+- 💬 [Discord](https://discord.gg/decibel) - Join our community for support
+- 🌐 [Trading Platform](https://app.decibel.trade) - Access the Decibel trading platform