raintree-technology/decibel

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

npm install @decibel/sdk

Client Setup

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

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

Market Data

// 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

// 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

// 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

// 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)

# 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)

# 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

# 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

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

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

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

Account Management

Subaccounts

// 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

// 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

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