decibel

---
name: decibel
description: Decibel on-chain perpetual futures trading platform on Aptos. Covers trading engine, orderbook, TypeScript SDK, REST APIs, WebSocket streams, market data, position management, TWAP orders, and vault operations. Triggers on Decibel, perpetual futures, Aptos trading, on-chain trading, perps, orderbook, TWAP, market data, trading API.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: raintree
  version: "1.0"
---

# Decibel Trading Platform Expert

Decibel is a fully on-chain perpetual futures trading platform built on Aptos blockchain.

## When to Use

- Integrating with Decibel trading APIs
- Building trading bots or applications
- Understanding on-chain orderbook mechanics
- Market data queries (prices, orderbook, trades)
- Position and order management

## Platform Overview

**Base URLs:**
- REST API: `https://api.netna.aptoslabs.com/decibel`
- WebSocket: `wss://api.netna.aptoslabs.com/decibel`

**Core Features:**
- Perpetual futures trading
- Fully on-chain orderbook
- TWAP (Time-Weighted Average Price) orders
- Real-time WebSocket streams
- Subaccount support
- Vault strategies

## TypeScript SDK

### Installation

```bash
npm install @decibel/sdk
```

### Client Setup

```typescript
import { DecibelClient } from "@decibel/sdk";

const client = new DecibelClient({
  apiKey: process.env.DECIBEL_API_KEY,
  network: "mainnet",
});
```

### Market Data

```typescript
// Get available markets
const markets = await client.getMarkets();

// Get current prices
const prices = await client.getPrices();

// Get orderbook depth
const orderbook = await client.getOrderbook("BTC-PERP", { depth: 10 });

// Get recent trades
const trades = await client.getRecentTrades("BTC-PERP", { limit: 50 });

// Get OHLC/candlesticks
const candles = await client.getCandles("BTC-PERP", {
  interval: "1h",
  limit: 100,
});
```

### Order Management

```typescript
// Place limit order
const order = await client.placeOrder({
  market: "BTC-PERP",
  side: "buy",
  type: "limit",
  price: 50000,
  size: 0.1,
});

// Place market order
const marketOrder = await client.placeOrder({
  market: "BTC-PERP",
  side: "sell",
  type: "market",
  size: 0.1,
});

// Cancel order
await client.cancelOrder(orderId);

// Cancel all orders
await client.cancelAllOrders({ market: "BTC-PERP" });
```

### Position Management

```typescript
// Get open positions
const positions = await client.getPositions();

// Get specific position
const position = await client.getPosition("BTC-PERP");

// Close position
await client.closePosition("BTC-PERP");

// Set take-profit/stop-loss
await client.setTPSL("BTC-PERP", {
  takeProfit: 55000,
  stopLoss: 48000,
});
```

### TWAP Orders

```typescript
// Place TWAP order (reduces slippage)
const twapOrder = await client.placeTWAPOrder({
  market: "BTC-PERP",
  side: "buy",
  size: 1.0,
  duration: 3600, // 1 hour in seconds
  intervals: 12,  // Execute every 5 minutes
});

// Get active TWAP orders
const activeTWAPs = await client.getActiveTWAPOrders();

// Cancel TWAP order
await client.cancelTWAPOrder(twapOrderId);
```

## REST API

### Market Data (Unauthenticated)

```bash
# Get markets
GET /market-data/markets

# Get prices
GET /market-data/prices

# Get orderbook
GET /market-data/orderbook?market=BTC-PERP&depth=10

# Get recent trades
GET /market-data/trades?market=BTC-PERP&limit=50

# Get candlesticks
GET /market-data/candles?market=BTC-PERP&interval=1h&limit=100
```

### User Endpoints (Authenticated)

```bash
# Get account overview
GET /user/account
Headers: Authorization: Bearer {token}

# Get positions
GET /user/positions

# Get open orders
GET /user/orders

# Get order history
GET /user/orders/history

# Get trade history
GET /user/trades

# Get funding rate history
GET /user/funding-history
```

### Transaction Endpoints

```bash
# Place order
POST /transactions/place-order
Body: { market, side, type, price?, size }

# Cancel order
POST /transactions/cancel-order
Body: { orderId }

# Deposit to subaccount
POST /transactions/deposit
Body: { amount, subaccountId? }

# Withdraw from subaccount
POST /transactions/withdraw
Body: { amount, subaccountId? }
```

## WebSocket Streams

### Connection

```javascript
const ws = new WebSocket("wss://api.netna.aptoslabs.com/decibel");

ws.onopen = () => {
  // Subscribe to channels
  ws.send(JSON.stringify({
    type: "subscribe",
    channels: ["trades:BTC-PERP", "orderbook:BTC-PERP"],
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};
```

### Available Channels

| Channel | Description |
|---------|-------------|
| `trades:{market}` | Real-time trades |
| `orderbook:{market}` | Orderbook updates |
| `ticker:{market}` | Price ticker |
| `account` | Account updates (authenticated) |
| `orders` | Order updates (authenticated) |
| `positions` | Position updates (authenticated) |
| `fills` | Fill notifications (authenticated) |

### Authenticated Subscription

```javascript
ws.send(JSON.stringify({
  type: "auth",
  token: "your-api-token",
}));

ws.send(JSON.stringify({
  type: "subscribe",
  channels: ["account", "orders", "positions", "fills"],
}));
```

## Account Management

### Subaccounts

```typescript
// Create subaccount
const subaccount = await client.createSubaccount({
  name: "Trading Bot 1",
});

// List subaccounts
const subaccounts = await client.getSubaccounts();

// Deposit to subaccount
await client.deposit({
  amount: 1000,
  subaccountId: subaccount.id,
});

// Withdraw from subaccount
await client.withdraw({
  amount: 500,
  subaccountId: subaccount.id,
});
```

### Delegations

```typescript
// Delegate trading authority
await client.createDelegation({
  delegatee: "0x...",
  permissions: ["trade", "cancel"],
  expiry: Date.now() + 30 * 24 * 60 * 60 * 1000,
});

// Revoke delegation
await client.revokeDelegation(delegationId);
```

## Error Handling

```typescript
try {
  const order = await client.placeOrder({...});
} catch (error) {
  if (error.code === "INSUFFICIENT_MARGIN") {
    console.log("Not enough margin for this order");
  } else if (error.code === "INVALID_PRICE") {
    console.log("Price outside allowed range");
  } else if (error.code === "RATE_LIMITED") {
    await sleep(1000);
    // Retry
  }
}
```

## Best Practices

**DO:**
- Use WebSocket for real-time data
- Implement proper error handling
- Use TWAP for large orders
- Monitor positions and margin
- Set TP/SL for risk management

**DON'T:**
- Poll REST API for real-time data
- Ignore rate limits
- Trade without sufficient margin
- Skip order confirmation

## Resources

- **API Docs:** https://docs.decibel.trade
- **SDK:** `@decibel/sdk`
- **Package Address:** `0xb8a5788314451ce4d2fbbad32e1bad88d4184b73943b7fe5166eab93cf1a5a95`