Skip to main content

​
What Decibel Is

Decibel is a perpetuals exchange where every order is placed, matched, and settled on the Aptos blockchain. There’s no off-chain server deciding who trades with whom. The matching logic is a smart contract that anyone can verify. Three technical pieces make this work:
  • An on-chain order book: a central-limit order book (CLOB) implemented in Move. How it works.
  • A perp clearinghouse: the clearinghouse_perp module tracks positions, margin, PnL, and liquidations. How it works.
  • Composable DeFi primitives: orders, positions, vaults, and collateral are all on-chain resources that other apps can build on. More on vaults.
You also need to understand how accounts work, which API keys to use, and how to integrate.

​
Accounts and Trading

Decibel separates who logs in, who signs trades, and where collateral lives:
TierWhat it isWhat it does
Login WalletYour normal Aptos account (e.g. Petra)Logs into the web app, creates an API Wallet
API WalletA dedicated keypair for programmatic tradingHolds APT for gas, signs all on-chain transactions. Create one at app.decibel.trade/api.
Trading AccountOn-chain object managed by dex_accountsHolds USDC collateral. All orders, PnL, and margin checks route through here.
The typical flow: Login Wallet -> create API Wallet -> create Trading Account -> deposit USDC -> trade.
In code, Trading Accounts are called subaccount. See Create Trading Account.

​
The On-Chain Orderbook

Decibel uses a central-limit order book (CLOB) implemented in Move:
  • The order book, matching engine, and clearinghouse work together to:
    • Check margin and risk.
    • Route between maker/taker, TWAP, and bulk orders.
    • Execute via Block-STM, so matching and settlement happen in one Aptos transaction.
Three properties to know:
  • Price-time priority: Bids and asks are sorted by (price, unique_idx), so the best-priced, earliest order matches first.
  • Deterministic fairness: No off-chain relay can jump the queue. Matching logic is part of the chain.
  • Atomic settlement: Matching and PnL/collateral updates commit (or abort) in the same transaction.

​
Perpetuals and Risk Controls

Perp contracts live in clearinghouse_perp.move and related modules:
  • Mark price: Median of the oracle price, orderbook mid price, and a basis-adjusted price: median(P_oracle, P_mid, P_basis) where P_basis = P_oracle * EMA_150s(P_mid / P_oracle). Used for PnL and margin checks.
  • Continuous funding: Accrues every second and is realized when positions change or close. See Funding Rates.

​
Margin

Cross margin uses one collateral pool to back all positions. Isolated margin locks collateral per-position. See Margin for full details.

​
Global Risk Controls

  • Price bands: Settlement must stay within a governance-set band around the mark price.
  • Circuit breakers: Can pause matching/withdrawals on extreme oracle deviations.
  • ADL (auto-deleveraging): Last-resort mechanism to protect solvency if insurance funds are exhausted.

​
Vaults

Vaults let you run on-chain strategies that others can deposit into:
  • A vault is a Move resource that:
    • Holds collateral (e.g. USDC).
    • Mints fungible vault shares (a claim on assets).
    • Charges interval-based performance fees (0–10%, crystallized every 30–365 days) in shares.
  • Depositors contribute USDC and receive shares at the current share price.
  • Managers trade via delegated permissions; fees are crystallized periodically as additional shares.
Two types of vaults:
  • Protocol vault: Managed by Decibel, has a 72-hour lockup and stricter risk settings.
  • User vaults: Created and managed by any user; deposits are withdrawable without protocol lockups by default.
Vault shares are fungible tokens on Aptos, so you can trade them or compose them in other DeFi protocols. See Vaults for Traders for contributor details, the Vault Integration Guide for the full developer walkthrough, or Vault Transactions for the underlying Move entry functions.

​
API Keys and Node Access

You’ll see three different “keys” in the docs:
KeyPurposeHow it’s used
Client API key (Geomi)GET endpoints on api.decibel.tradeSent as Authorization: Bearer <CLIENT_API_KEY>
Node API key (Geomi / Aptos Build)SDK connection to Aptos fullnodesPassed as nodeApiKey to DecibelReadDex / DecibelWriteDex
API Wallet private keySigns on-chain transactionsNever commit to Git; store in .env or a secrets manager
Rule of thumb: Reading data needs a Client API key + Node API key. Sending transactions needs a Node API key + API Wallet private key.

​
Integrating with Decibel

There are three layers for interacting with Decibel, each with different read/write access:
LayerAccessWhat it does
TypeScript SDK (@decibeltrade/sdk)Read + WriteHandles ABI, replay protection, gas, and JSON decoding. High-level helpers like placeOrder, placeTwapOrder, depositToVault.
REST & WebSocket APIsReadREST for queries (GET /api/v1/markets, /orders, /positions). WebSocket for streaming prices, depth, trades.
Raw Aptos transactionsWriteCall Move entry functions directly (e.g. dex_accounts_entry::place_order_to_subaccount). Full control over payloads, ABI parsing, and signing.

​
Next Steps

TypeScript Starter Kit

Set up credentials and place your first trade in under 5 minutes

On-Chain Reference

Move entry function signatures and examples for every transaction type

Vault Integration Guide

Create and manage onchain vaults with pooled capital and performance fees