Skip to main content
A streamlined quick-start for the Decibel TypeScript starter kit: set up fast, then customize.

Part 1: Get Your First Trade under 5 min

Follow the exact steps to install, configure, and place your first order.

Part 2: Mental Model & Architecture

Understand Decibel’s three-tier account model, execution queue, and funding.

Part 3: Make It Yours

Customize markets, order logic, and Trading Accounts for your own strategy.

​
Part 1: Get Your First Trade under 5 min

Follow these steps exactly to get your first trade running.

​
1. Prerequisites

​
2. Get Your Credentials

You need two things: an API Wallet (for signing transactions) and an API Key (for authenticated API requests).

​
Create API Wallet

  1. Go to app.decibel.trade/api
  2. Connect your Petra Wallet or “Continue with Google”
  3. Click “Create API Wallet”
Create API Wallet Example
  1. Copy the Private Key immediately (you only see it once)
  2. Also save the Wallet Address shown on the same screen
Store your private key securely! Anyone with this key can access your funds.

​
Create API Key (Bearer Token)

The API Key is used for authenticated requests to the Decibel REST API. You’ll get this from Geomi (Aptos Build).
  1. Sign up or log in at geomi.dev
    • Click “Continue with Google” or enter your email
  2. Create or select a project
    • If you’re new, you’ll see “No resources yet”, that’s fine!
    • Your project dashboard will show available resources
  3. Add an API Key resource Geomi Dashboard
    • Click the “API Key” card (find it under “Add more resources to your project”)
  4. Fill out the API Key form: Create API Key Form
    • API Key Name: Choose a name (e.g., decibel or my-trading-bot)
    • Network: Select “Decibel Devnet” from the dropdown (important!)
    • Description: Optional, add a note about what this key is for (150 chars max)
    • Client usage: Leave this OFF (unless you’re building a web/mobile app)
    • Click “Create New API Key”
  5. Copy your Bearer Token Get Bearer Token
    • After creation, you’ll see your API key in the “API Keys” table
    • Find the “Key secret” column, this is your Bearer token
    • Click the copy icon next to the masked key (shows as *****...*****)
This “Key secret” is your API_BEARER_TOKEN. It’s the full Bearer token, not just the key name.

​
3. Configure the Project

# Clone the repo
git clone https://github.com/tippi-fifestarr/testetna.git
cd testetna

# Install dependencies
npm install

# Create env file
cp .env.example .env
Open .env and paste your credentials:
.env
API_WALLET_PRIVATE_KEY=0xYOUR_COPIED_KEY_HERE
API_WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_HERE
API_BEARER_TOKEN=YOUR_BEARER_TOKEN_HERE
Quick checklist:
  • API_WALLET_PRIVATE_KEY: From Decibel App (Create API Wallet)
  • API_WALLET_ADDRESS: From Decibel App (Create API Wallet)
  • API_BEARER_TOKEN: From Geomi (Create API Key, “Key secret” column)

​
4. Run the “Quick Win”

This script handles everything: funding (via private faucet), account creation, minting USDC, depositing, and placing a trade. 
npm run quick-win
If you see ”🎉 Order Placement Complete!”, congratulations. The code works.

​
Part 2: Mental Model & Architecture 🏗️

Trading on Decibel has specific mechanics that differ from CEXs and many DEXs. Here are 5 key concepts for API traders.
Jump to Part 3 if you’re ready to start customizing your code. You can always come back here later.

​
1. The Three-Tier Account Model

Decibel uses a three-tier account structure for programmatic trading:
TierDescription
Primary WalletYour login account. Used to access Decibel App and create API Wallets.
API WalletA separate wallet for API trading. Holds APT for gas fees and signs all trading transactions. This is your API_WALLET_ADDRESS.
Trading AccountCreated from your API Wallet. Holds USDC for trading collateral. Address is extracted from transaction events and written to .env as SUBACCOUNT_ADDRESS.
Flow: Primary Wallet → Create API Wallet → Create Trading Account → Deposit USDC → Trade. Three-tier account model
For API traders, you primarily interact with the API Wallet (not the Primary Wallet). Most users will have a single Trading Account, though you can create multiple for different strategies.

​
2. Async Execution (The Queue)

Decibel is an on-chain CLOB (Central Limit Order Book).
PlatformBehavior
CEXresponse = placeOrder() → Returns “Filled”
Decibelresponse = placeOrder() → Returns “Transaction Hash” (Ticket to the Queue)
Execution is asynchronous. The REST response confirms submission, not fill. Use the WebSocket stream for execution updates.

​
3. “Lazy” Continuous Funding

  • Traditional: Pay funding every 8 hours
  • Decibel: Funding ticks every second (continuous accrual)
You only “pay” (settle) funding when you modify or close the position.
Your Unrealized PnL includes accrued funding debt. Watch it closely to avoid liquidation.

​
4. Reduce-Only Logic

Decibel implements strict “Close First” logic. A Reduce-Only order will never flip your position (e.g., Long 1 → Short 1). It caps execution at your current size, preventing accidental exposure when closing positions aggressively. See Place Order for implementation details.

​
5. Bulk Orders (Unique Optimization)

For Market Makers and HFTs: You can update multiple orders in a single transaction, saving gas and getting atomic updates for spread management. See Place Bulk Order for implementation details.

​
Part 3: Make It Yours

Now that you have a working baseline, here’s how to adapt this code for your actual strategy.

​
How to Trade a Different Market

Open src/5-place-order.ts. Find the “Configuration” section. Change this: 
const marketName = config.MARKET_NAME || 'BTC/USD';
To this: 
const marketName = 'ETH/USD'; // or SOL/USD, APT/USD, etc.
Run npm run setup to see a list of all available market names. Market names use the format SYMBOL/USD (not SYMBOL-PERP).

​
How to Change Your Order Logic

Open src/5-place-order.ts. Find the “Order Parameters” section. Change this: 
const userPrice = 50000;
const userSize = 0.001;
const isBuy = true;
To your own logic: 
// Example: A simple moving average bot might look like this
const userPrice = calculatedMovingAverage;
const userSize = riskManagementSize;
const isBuy = signal === 'BULLISH';

​
Focus on Order Management

After running quick-win, you have a funded Trading Account ready to use. You can now focus on:
  • src/5-place-order.ts: Customize your trading strategy
  • src/6-query-order.ts: Check order status
You don’t need to create a new Trading Account for every trade. Once you have USDC deposited (from quick-win), you can run 5-place-order and 6-query repeatedly using the same Trading Account.

​
How to Use a Different Trading Account

If you want to use a specific Trading Account (e.g., for a different strategy):
  1. Create a new one: npm run create-subaccount
  2. The script automatically updates your .env file with the new SUBACCOUNT_ADDRESS
  3. Run npm run deposit-usdc to fund it
How the Trading Account script works:
  • Calls create_new_subaccount, which creates a non-primary Trading Account (random address)
  • Extracts the Trading Account address from the SubaccountCreatedEvent in the transaction events
  • Verifies the address via the API (with up to 5 retries for indexer lag)
  • Writes the address to your .env file
To manually select a different Trading Account:
  • After running create-subaccount, check the list of Trading Accounts it prints
  • Manually edit .env and set SUBACCOUNT_ADDRESS to the address you want
  • Or modify src/2-create-subaccount.ts to change the selection logic

​
Part 4: What’s Next? 🚀

1

Monitor Risk

Build a script to track Unrealized PnL + Accrued Funding to avoid liquidation.
2

Market Making

Use src/7-websocket-updates.ts to listen to the orderbook and place Maker orders.
3

Explore Order Types

Look into Post-Only and Reduce-Only params in the API docs for advanced control.

​
Resources

Full Documentation

Complete Decibel documentation

Placing Your First Order

Alternative guide with Netna and Testnet examples

Discord Community

Get help from the community

Netna Faucet

Staging network faucet

​
Network Support

This starter kit is tested and configured for Netna staging network only.
The getExplorerLink() function in utils/client.ts generates explorer URLs for Netna transactions. For other networks, you need to manually select the network from the explorer dropdown.