REST API Overview

The Decibel REST API provides HTTP endpoints under /api/v1 for market data, account data, history, analytics, rewards, and referral workflows.

Authentication Scope

Most production traffic is expected to include:

Authorization: Bearer <KEY>
Origin: <your app origin>

See Authentication for credential setup. Implementation note: authentication and access control can be enforced at multiple layers (gateway and service). Treat endpoint-level access policy as deployment-configurable rather than assuming the same behavior in every environment.

Base URL

Network	Base URL
Testnet	`https://api.testnet.aptoslabs.com/decibel`
Mainnet	`https://api.mainnet.aptoslabs.com/decibel`

Request Format

Endpoints are rooted at /api/v1/...
Current public methods are GET and POST
Most endpoints use query/path parameters; no generic request body format applies globally

Extensible Enums

Enum values in responses may grow over time. Clients must accept values they don’t recognize instead of rejecting the response or dropping the row. Campaign endpoints only return campaign types beyond the original set (fee_rebate through affiliate) when the request sends Prefer: include-unknown-enum-members. When honored, the response echoes Preference-Applied: include-unknown-enum-members.

Spot and Perp Coverage

Some endpoints return both perpetual and spot rows. Mixed responses use asset_type with values perp or spot.

Endpoint	Spot behavior
`/api/v1/markets`	Returns perp and spot markets together; each market carries `asset_type`
`/api/v1/open_orders`	Returns perp and spot orders by default; filter with `?asset_type=perp` or `?asset_type=spot`
`/api/v1/order_history`	Returns perp and spot order history by default; filter with `?asset_type=perp` or `?asset_type=spot`; `market` is one concrete market address
`/api/v1/trade_history`	Returns perp and spot trade history by default; filter with `?asset_type=perp` or `?asset_type=spot`; `market` is one concrete market address
`/api/v1/orders`	Looks up perp and spot order IDs by default for one concrete market address; `client_order_id` is perp-only
`/api/v1/bulk_orders`	Returns perp and spot bulk-order state by default; filter with `?asset_type=perp` or `?asset_type=spot`; `market` is one concrete market address
`/api/v1/bulk_order_fills`	Returns perp and spot bulk-order fills by default; filter with `?asset_type=perp` or `?asset_type=spot`; `market` is one concrete market address
`/api/v1/bulk_order_status`	Defaults to perp; pass `?asset_type=spot` for spot status; `market` is one concrete market address
`/api/v1/orderbook`	Accepts one perp or spot market address; the request resolves to exactly one market
`/api/v1/trades`	Accepts one perp or spot market address; spot rows are returned from the taker’s perspective
`/api/v1/candlesticks`	Accepts one perp or spot market address; spot candles are aggregated from spot trades
`/api/v1/spot/asset_contexts`	Spot-only 24h stats plus live book mid for registered spot markets

Market-address filters never mean “all BTC products”. A spot BTC market and a perp BTC market are different markets with different addresses, so request the product-specific market you want. /api/v1/prices, /api/v1/funding_rate_history, /api/v1/asset_contexts, /api/v1/daily_stats, positions, and account-margin endpoints are perp-only. Spot markets do not have oracle price, mark price, funding, open interest, or positions; use /api/v1/spot/asset_contexts, /api/v1/orderbook, or the all_spot_mids / depth:{marketAddr} WebSocket topics for spot display prices.

Spot DTO Notes

Spot /api/v1/markets rows use asset_type="spot", sz_decimals from the base asset, and px_decimals from the quote asset. Perp-only fields such as max_leverage, max_open_interest, unrealized_pnl_haircut_bps, category, and is_isolated_only use neutral defaults.
Spot OrderDto rows use time_in_force for GTC, POST_ONLY, or IOC. Spot has no client_order_id, reduce-only flag, TP/SL, parent chain, or trigger condition, so those fields are empty, false, or null.
Spot TradeDto rows use action="Buy" or "Sell" from the row account’s perspective. Spot has no position PnL or funding, so realized_pnl_amount and realized_funding_amount are zero. fee_amount is the side’s actual fee, and fee_asset identifies whether that fee is denominated in the base or quote asset.
Spot bulk-order and bulk-order-fill DTOs share the perp response shape, carry asset_type="spot", and normalize prices/sizes with the spot market’s quote/base decimals.

Example Request

curl -H "Origin: https://testnet-app.decibel.trade/trade" \
     -H "Authorization: Bearer <KEY>" \
     "https://api.testnet.aptoslabs.com/decibel/api/v1/prices"

Example Response

[
  {
    "market": "0x...",
    "oracle_px": 97250.5,
    "mark_px": 97248.3,
    "mid_px": 97249.0,
    "funding_rate_bps": 0.12,
    "is_funding_positive": true,
    "transaction_unix_ms": 1718000000000,
    "open_interest": 5200000.0
  }
]

Available Endpoints

The list below is aligned to runtime routes in rust/trading-api/src/http/routes.rs.

Market Data

Endpoint	Description
`GET /api/v1/markets`	List available perp and spot markets
`GET /api/v1/candlesticks`	Perp and spot OHLCV candlestick data for one market address
`GET /api/v1/prices`	Latest perp prices/funding/open interest
`GET /api/v1/trades`	Recent trades for one perp or spot market address
`GET /api/v1/dex`	DEX registration/metadata
`GET /api/v1/contracts`	Contract metadata
`GET /api/v1/contract_specs`	Contract spec metadata
`GET /api/v1/orderbook`	One perp or spot order book snapshot by market address
`GET /api/v1/spot/asset_contexts`	Spot 24h stats plus live book mid

Account and Trading

Endpoint	Description
`GET /api/v1/account_positions`	Perp account positions
`GET /api/v1/open_orders`	Open perp and spot orders
`GET /api/v1/orders`	Order lookup across perp and spot for one market address; `client_order_id` is perp-only
`GET /api/v1/account_overviews`	Perp account overview and margins
`GET /api/v1/subaccounts`	Subaccounts
`GET /api/v1/user_fee_rates`	Current maker/taker rates, fee tier, full fee schedule, and 30-day daily volume history

History

Endpoint	Description
`GET /api/v1/trade_history`	Perp and spot trade history
`GET /api/v1/order_history`	Perp and spot order history
`GET /api/v1/funding_rate_history`	Perp funding rate history
`GET /api/v1/account_fund_history`	Account funding history
`GET /api/v1/asset_contexts`	Perp asset context snapshots
`GET /api/v1/withdraw_queue`	Withdrawal queue history/state

TWAP and Bulk Orders

Endpoint	Description
`GET /api/v1/active_twaps`	Active TWAP orders
`GET /api/v1/twap_history`	TWAP order history
`GET /api/v1/bulk_orders`	Perp and spot bulk-order states; market filter is one concrete market
`GET /api/v1/bulk_order_fills`	Perp and spot bulk-order fill history; market filter is one concrete market
`GET /api/v1/bulk_order_status`	Bulk-order status for one concrete market; defaults to perp, supports `asset_type=spot`

Vaults

Endpoint	Description
`GET /api/v1/vaults`	List all vaults
`GET /api/v1/account_owned_vaults`	Vaults owned by account
`GET /api/v1/account_vault_performance`	Vault performance for an account

Analytics and Points

Endpoint	Description
`GET /api/v1/leaderboard`	Trading leaderboard
`GET /api/v1/points_leaderboard`	Points leaderboard
`GET /api/v1/portfolio_chart`	Portfolio chart
`GET /api/v1/delegations`	Delegation info
`GET /api/v1/daily_stats`	Perp daily stats
`GET /api/v1/predeposits/rewards`	Predeposit rewards
`GET /api/v1/points/trading/account`	Trading points for account
`GET /api/v1/points/trading/amps`	Trading amps for account
`GET /api/v1/points/tier`	User tier info
`GET /api/v1/points/amps`	Owner amps summary
`GET /api/v1/points/global`	Global points stats
`GET /api/v1/streaks/account`	Account streak stats

Referral and Affiliate

Endpoint	Description
`GET /api/v1/referrals/account/{account}`	Referral info by account
`GET /api/v1/referrals/users`	User referrals
`GET /api/v1/referrals/stats/{account}`	Referral stats by account
`GET /api/v1/referrals/code/{code}`	Validate referral code
`POST /api/v1/referrals/redeem`	Redeem referral code
`GET /api/v1/affiliates/codes/{account}`	Affiliate codes owned by account
`GET /api/v1/affiliates/earnings/{account}`	Affiliate earnings by account

Backward-Compatible Aliases

Endpoint	Canonical Endpoint
`GET /api/v1/user_positions`	`/api/v1/account_positions`
`GET /api/v1/user_fund_history`	`/api/v1/account_fund_history`
`GET /api/v1/user_owned_vaults`	`/api/v1/account_owned_vaults`
`GET /api/v1/user_vault_performance`	`/api/v1/account_vault_performance`

SDK Alternative

For most application use cases, prefer the TypeScript SDK. See TypeScript SDK Overview.

Authentication

Credential setup and auth headers

Error Handling

Status codes and error payloads

Overview

User

Account

Vaults

TWAP

Affiliates

Market Data

Borrow/Lend

Bulk Orders

Campaigns

Analytics

Points

Tier

Trading Points

Trading Hz

Predeposit Rewards

Referrals

Streaks

Transfers

REST API Overview

Authentication Scope

Base URL

Request Format

Extensible Enums

Spot and Perp Coverage

Spot DTO Notes

Example Request

Example Response

Available Endpoints

Market Data

Account and Trading

History

TWAP and Bulk Orders

Vaults

Analytics and Points

Referral and Affiliate

Backward-Compatible Aliases

SDK Alternative

Authentication

Error Handling

​Authentication Scope

​Base URL

​Request Format

​Extensible Enums

​Spot and Perp Coverage

​Spot DTO Notes

​Example Request

​Example Response

​Available Endpoints

​Market Data

​Account and Trading

​History

​TWAP and Bulk Orders

​Vaults

​Analytics and Points

​Referral and Affiliate

​Backward-Compatible Aliases

​SDK Alternative

​Related

Authentication

Error Handling

Authentication Scope

Base URL

Request Format

Extensible Enums

Spot and Perp Coverage

Spot DTO Notes

Example Request

Example Response

Available Endpoints

Market Data

Account and Trading

History

TWAP and Bulk Orders

Vaults

Analytics and Points

Referral and Affiliate

Backward-Compatible Aliases

SDK Alternative

Related