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

# Get user trade history

> Retrieve perp trade history for a specific user with optional filtering by one
perp market address, order ID, side, and timestamp range. Returns executed
trades with price, size, PnL, and fee details.
Supports sorting by timestamp (default: descending) and pagination. Page size is capped at 200.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/trade_history
openapi: 3.1.0
info:
  title: Decibel Trading API
  description: >-
    RESTful API for Decibel. Provides read-only endpoints for market data,
    trading operations, positions, and analytics.
  contact:
    name: Decibel Team
    url: https://decibel.trade/
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.mainnet.aptoslabs.com/decibel
    description: Mainnet
  - url: https://api.testnet.aptoslabs.com/decibel
    description: Testnet
security:
  - bearerAuth: []
tags:
  - name: Market Data
    description: Market information and real-time data endpoints
  - name: User
    description: User information and account management
  - name: Account
    description: Account-specific endpoints and data
  - name: Trades
    description: Trading operations and history
  - name: Positions
    description: User position management
  - name: Orders
    description: Order management and history
  - name: TWAP
    description: Time-weighted average price orders
  - name: Bulk Orders
    description: Bulk order management
  - name: Vaults
    description: Vault operations and management
  - name: Analytics
    description: Analytics and performance metrics
  - name: Points
    description: Points-related account metrics
  - name: Trading Points
    description: Trading points endpoints
  - name: Trading Hz
    description: Trading Hz endpoints
  - name: Tier
    description: Tier information endpoints
  - name: Streaks
    description: User streak tracking endpoints
  - name: Predeposit Rewards
    description: Season 0 predeposit USDC rewards
  - name: Referrals
    description: Referral code management and tracking
  - name: Affiliates
    description: Affiliate code and earnings endpoints
  - name: Campaigns
    description: On-chain reward campaign endpoints
paths:
  /api/v1/trade_history:
    get:
      tags:
        - Account
      summary: Get user trade history
      description: >-
        Retrieve perp trade history for a specific user with optional filtering
        by one

        perp market address, order ID, side, and timestamp range. Returns
        executed

        trades with price, size, PnL, and fee details.

        Supports sorting by timestamp (default: descending) and pagination. Page
        size is capped at 200.
      operationId: handle_account_trade_history
      parameters:
        - name: account
          in: query
          description: User account address (`user` query alias is also accepted)
          required: true
          schema:
            type: string
        - name: order_id
          in: query
          description: Filter by specific order ID (requires market to also be provided)
          required: false
          schema:
            type: string
        - name: market
          in: query
          description: Filter by market address
          required: false
          schema:
            type: string
        - name: side
          in: query
          description: Filter by side
          required: false
          schema:
            $ref: '#/components/schemas/SideFilter'
        - name: asset_type
          in: query
          description: Filter by product ("perp" | "spot"); omit to include both
          required: false
          schema:
            $ref: '#/components/schemas/AssetType'
        - name: limit
          in: query
          description: Page size
          required: false
          schema:
            type: integer
            format: int32
            default: 10
            maximum: 200
            minimum: 0
          example: 100
        - name: offset
          in: query
          description: Page offset
          required: false
          schema:
            type: integer
            format: int32
            default: 0
            maximum: 10000
            minimum: 0
          example: 0
        - name: start_timestamp
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: end_timestamp
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: sort_key
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/HistorySortKey'
        - name: sort_dir
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SortDir'
      responses:
        '200':
          description: Trade history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_TradeDto'
        '400':
          description: Invalid parameters (order_id requires market)
        '500':
          description: Database error
components:
  schemas:
    SideFilter:
      type: string
      description: >-
        Order side filter: buy or sell. Product-independent: a buy is a bid on

        both venues, whether or not it opens a perp long.

        For perp orders, maps to the `is_buy` column; for spot orders, `is_bid`.

        For perp trades/funding, maps to `action IN ('OpenLong','CloseShort')`
        (buy)

        or `action IN ('CloseLong','OpenShort')` (sell); for spot trades, to

        `is_taker_bid` resolved against whether the account is the taker or
        maker.
      enum:
        - buy
        - sell
    AssetType:
      type: string
      description: >-
        Discriminator carried on DTOs that can mix perp and spot rows (markets,

        orders, trades, bulk orders, bulk order fills, and WebSocket payloads).

        Also accepted as a query parameter on REST endpoints that can filter to
        one

        product.


        Wire format is lowercase (`"perp"` / `"spot"`) and accepted

        case-insensitively on the request side via
        [`impl_case_insensitive_deserialize`].
      enum:
        - perp
        - spot
    HistorySortKey:
      type: string
      description: Sort key for history endpoints
      enum:
        - timestamp
    SortDir:
      type: string
      enum:
        - ASC
        - DESC
    PaginatedResponse_TradeDto:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - asset_type
              - account
              - market
              - action
              - source
              - trade_id
              - size
              - price
              - is_profit
              - realized_pnl_amount
              - realized_funding_amount
              - is_rebate
              - fee_amount
              - order_id
              - client_order_id
              - transaction_unix_ms
              - transaction_version
              - counter_party_account
            properties:
              account:
                type: string
                description: User's account address
                example: '0x1234567890abcdef1234567890abcdef12345678'
              action:
                type: string
                description: >-
                  Trade action type. Perp: position-centric ("OpenLong",
                  "CloseShort",

                  "Net", ...). Spot: side from this row's perspective ("Buy" /
                  "Sell").
                example: buy
              asset_type:
                $ref: '#/components/schemas/AssetType'
                description: >-
                  Which product this trade belongs to ("perp" or "spot").
                  Responses can

                  mix products; this per-row tag lets clients demux.
              client_order_id:
                type: string
                description: Client-specified order ID
                example: client_order_abc
              counter_party_account:
                type: string
                description: >-
                  Counter party account on the other leg of the fill. For
                  liquidation /

                  ADL / delisting fills this is the backstop liquidator. Empty
                  string for

                  pre-V2 historical trades that did not carry counter party
                  on-chain.
                example: >-
                  0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210
              fee_amount:
                type: number
                format: double
                description: >-
                  Fee paid by this row's account, normalized. Perp: always in
                  the

                  collateral asset (USDC). Spot: charged in the asset this side

                  RECEIVED (protocol + builder fee combined); see `fee_asset`.
              fee_asset:
                type:
                  - string
                  - 'null'
                description: >-
                  FA metadata address of the asset `fee_amount` is denominated
                  in.

                  Spot only (base asset for the buyer, quote for the seller);
                  absent

                  for perp rows, where the fee is implicitly the collateral
                  asset.
              is_profit:
                type: boolean
                description: Whether trade was profitable
              is_rebate:
                type: boolean
                description: Whether trade received rebate
              market:
                type: string
                description: Market identifier address
                example: 0xmarket123456789abcdef
              order_id:
                type: string
                description: Order ID associated with trade
                example: '12345'
              price:
                type: number
                format: double
                description: Trade price
                example: 50000.25
              realized_funding_amount:
                type: number
                format: double
                description: >-
                  Realized funding amount in USDC

                  - Negative value: trader PAID funding (e.g., long position
                  with positive funding rate)

                  - Positive value: trader RECEIVED funding (e.g., short
                  position with positive funding rate)

                  - Zero: no funding accrued
                example: -15.5
              realized_pnl_amount:
                type: number
                format: double
                description: Realized PnL amount
              size:
                type: number
                format: double
                description: Trade size
                example: 100.5
              source:
                type: string
                description: >-
                  Trade source (e.g., "OrderFill", "MarginCall",
                  "BackStopLiquidation", "ADL", "MarketDelisted")
                example: OrderFill
              trade_id:
                type: string
                description: Trade ID
                example: '3647276'
              transaction_unix_ms:
                type: integer
                format: int64
                description: Transaction timestamp in milliseconds
                example: 1634567890000
              transaction_version:
                type: integer
                format: int64
                description: Transaction version
                example: 3647276285
                minimum: 0
          description: The items in the current page
        total_count:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            The total number of items across all pages.

            Optional: history endpoints omit this field to avoid expensive
            COUNT(*) queries.
          minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token from Geomi. See
        [Authentication](/api-reference/rest/authentication) for setup
        instructions.

````