> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decibel.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Mental model for building on Decibel: accounts, orderbook, perps, vaults, and APIs.

## 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.](#the-on-chain-orderbook)
* **A perp clearinghouse:** the `clearinghouse_perp` module tracks positions, margin,
  PnL, and liquidations. [How it works.](#perpetuals-and-risk-controls)
* **Composable DeFi primitives:** orders, positions, vaults, and collateral are all
  on-chain resources that other apps can build on. [More on vaults.](#vaults)

You also need to understand [how accounts work](#accounts-and-trading),
[which API keys to use](#api-keys-and-node-access), and
[how to integrate](#integrating-with-decibel).

## Accounts and Trading

Decibel separates who logs in, who signs trades, and where collateral lives:

| Tier                | What it is                                   | What it does                                                                               |
| ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Login Wallet**    | Your normal Aptos account (e.g. Petra)       | Logs into the web app, creates an API Wallet                                               |
| **API Wallet**      | A dedicated keypair for programmatic trading | Holds APT for gas, signs all on-chain transactions. Create one at `app.decibel.trade/api`. |
| **Trading Account** | On-chain object managed by `dex_accounts`    | Holds 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.

<Tip>
  In code, Trading Accounts are called `subaccount`. See [Create Trading Account](/developer-hub/on-chain/account-management/create-subaccount).
</Tip>

## 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](https://aptos.dev/network/blockchain/execution#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](/for-traders/funding-rates).

### Margin

Cross margin uses one collateral pool to back all positions. Isolated margin locks collateral per-position. See [Margin](/for-traders/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-traders/vaults) for contributor details, the [Vault Integration Guide](/developer-hub/guides/vaults) for the full developer walkthrough, or [Vault Transactions](/developer-hub/on-chain/vault/create-and-fund) for the underlying Move entry functions.

## API Keys and Node Access

You'll see three different "keys" in the docs:

| Key                                                          | Purpose                                                      | How it's used                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------- |
| **Client API key** ([Geomi](https://geomi.dev/))             | GET endpoints on `https://api.mainnet.aptoslabs.com/decibel` | Sent as `Authorization: Bearer <CLIENT_API_KEY>`               |
| **Node API key** ([Geomi](https://geomi.dev/) / Aptos Build) | SDK connection to Aptos fullnodes                            | Passed as `nodeApiKey` to `DecibelReadDex` / `DecibelWriteDex` |
| **API Wallet private key**                                   | Signs on-chain transactions                                  | Never 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:

| Layer                                    | Access       | What it does                                                                                                                                     |
| ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **TypeScript SDK** (`@decibeltrade/sdk`) | Read + Write | Handles ABI, replay protection, gas, and JSON decoding. High-level helpers like `placeOrder`, `placeTwapOrder`, `depositToVault`.                |
| **REST & WebSocket APIs**                | Read         | REST for queries (`GET /api/v1/markets`, `/orders`, `/positions`). WebSocket for streaming prices, depth, trades.                                |
| **Raw Aptos transactions**               | Write        | Call Move entry functions directly (e.g. `dex_accounts_entry::place_order_to_subaccount`). Full control over payloads, ABI parsing, and signing. |

## Next Steps

<CardGroup cols={3}>
  <Card title="TypeScript Starter Kit" icon="code" href="/quickstart/typescript-starter-kit">
    Set up credentials and place your first trade in under 5 minutes
  </Card>

  <Card title="On-Chain Reference" icon="link" href="/developer-hub/on-chain/overview/index">
    Move entry function signatures and examples for every transaction type
  </Card>

  <Card title="Vault Integration Guide" icon="vault" href="/developer-hub/guides/vaults">
    Create and manage onchain vaults with pooled capital and performance fees
  </Card>
</CardGroup>