openapi: 3.0.3
info:
  title: Phemex Hedged Perpetual API
  description: REST API for hedged perpetual contract trading on Phemex, enabling both long and short positions simultaneously with independent leverage settings per side.
  version: 1.0.0
  contact:
    name: Phemex Support
    url: https://phemex.com/help-center
servers:
  - url: https://api.phemex.com
    description: Production
  - url: https://testnet-api.phemex.com
    description: Testnet
security:
  - HmacAuth: []
paths:
  /public/products:
    get:
      summary: Get hedged perpetual products
      description: Query product information including hedged mode products.
      operationId: getHedgedProducts
      tags:
        - Market Data
      security: []
      responses:
        '200':
          description: Product list including hedged perpetuals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-orders:
    post:
      summary: Place hedged order
      description: Place order with JSON body for hedged perpetual trading.
      operationId: placeHedgedOrder
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HedgedOrderRequest'
      responses:
        '200':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
    delete:
      summary: Bulk cancel hedged orders
      description: Cancel multiple hedged orders at once.
      operationId: bulkCancelHedgedOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: orderID
          in: query
          schema:
            type: string
        - name: posSide
          in: query
          schema:
            type: string
            enum: [Long, Short]
      responses:
        '200':
          description: Orders cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-orders/create:
    put:
      summary: Place hedged order via query string
      description: Place order with arguments in URL query string (preferred method).
      operationId: createHedgedOrderQueryString
      tags:
        - Orders
      parameters:
        - name: clOrdID
          in: query
          schema:
            type: string
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: side
          in: query
          required: true
          schema:
            type: string
            enum: [Buy, Sell]
        - name: posSide
          in: query
          required: true
          schema:
            type: string
            enum: [Long, Short]
        - name: orderQtyRq
          in: query
          required: true
          schema:
            type: string
          description: Real quantity (not scaled)
        - name: ordType
          in: query
          schema:
            type: string
            enum: [Limit, Market, Stop, StopLimit]
        - name: priceRp
          in: query
          schema:
            type: string
          description: Real price (not scaled)
        - name: timeInForce
          in: query
          schema:
            type: string
            enum: [GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly]
        - name: reduceOnly
          in: query
          schema:
            type: boolean
        - name: closeOnTrigger
          in: query
          schema:
            type: boolean
        - name: stopPxRp
          in: query
          schema:
            type: string
        - name: takeProfitRp
          in: query
          schema:
            type: string
        - name: stopLossRp
          in: query
          schema:
            type: string
        - name: triggerType
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /g-orders/replace:
    put:
      summary: Modify hedged order
      description: Modify an existing hedged order by orderID.
      operationId: modifyHedgedOrder
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: orderID
          in: query
          schema:
            type: string
        - name: origClOrdID
          in: query
          schema:
            type: string
        - name: clOrdID
          in: query
          schema:
            type: string
        - name: priceRp
          in: query
          schema:
            type: string
        - name: orderQtyRq
          in: query
          schema:
            type: string
        - name: stopPxRp
          in: query
          schema:
            type: string
        - name: takeProfitRp
          in: query
          schema:
            type: string
        - name: stopLossRp
          in: query
          schema:
            type: string
        - name: posSide
          in: query
          schema:
            type: string
            enum: [Long, Short]
      responses:
        '200':
          description: Order modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /g-orders/cancel:
    delete:
      summary: Cancel hedged order
      description: Cancel a single hedged order by orderID.
      operationId: cancelHedgedOrder
      tags:
        - Orders
      parameters:
        - name: orderID
          in: query
          required: true
          schema:
            type: string
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: posSide
          in: query
          schema:
            type: string
            enum: [Long, Short]
      responses:
        '200':
          description: Order cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /g-orders/all:
    delete:
      summary: Cancel all hedged orders
      description: Cancel all orders for a hedged perpetual symbol.
      operationId: cancelAllHedgedOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: untriggered
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: All orders cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-orders/activeList:
    get:
      summary: Get active hedged orders
      description: Query open orders for a hedged perpetual symbol.
      operationId: getActiveHedgedOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Active orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /g-accounts/accountPositions:
    get:
      summary: Get hedged account positions
      description: Query account positions and balances for hedged perpetuals.
      operationId: getHedgedAccountPositions
      tags:
        - Account
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
        - name: symbol
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Account and positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPositionsResponse'
  /g-accounts/positions:
    get:
      summary: Get hedged positions with PNL
      description: Query positions with unrealized PNL at mark price.
      operationId: getHedgedPositions
      tags:
        - Account
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Positions with PNL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-positions/switch-pos-mode-sync:
    put:
      summary: Switch position mode
      description: Switch between OneWay and Hedged position modes.
      operationId: switchPositionMode
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: targetPosMode
          in: query
          required: true
          schema:
            type: string
            enum: [OneWay, Hedged]
      responses:
        '200':
          description: Mode switched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-positions/leverage:
    put:
      summary: Set hedged leverage
      description: Set leverage for hedged positions — supports separate long/short leverage.
      operationId: setHedgedLeverage
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: leverageRr
          in: query
          schema:
            type: string
          description: Leverage for one-way mode
        - name: longLeverageRr
          in: query
          schema:
            type: string
          description: Leverage for long positions
        - name: shortLeverageRr
          in: query
          schema:
            type: string
          description: Leverage for short positions
      responses:
        '200':
          description: Leverage set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /g-positions/assign:
    post:
      summary: Assign balance to position
      description: Assign balance to a specific hedged position side.
      operationId: assignHedgedMargin
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: posSide
          in: query
          required: true
          schema:
            type: string
            enum: [Long, Short]
        - name: posBalanceRv
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Balance assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/order/v2/orderList:
    get:
      summary: Get closed orders
      description: Query closed hedged orders with filters.
      operationId: getHedgedClosedOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          schema:
            type: string
        - name: currency
          in: query
          schema:
            type: string
        - name: ordStatus
          in: query
          schema:
            type: string
        - name: ordType
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: withCount
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Closed orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /exchange/order/v2/tradingList:
    get:
      summary: Get user trades
      description: Query user trades by hedged perpetual symbol.
      operationId: getHedgedTrades
      tags:
        - Trades
      parameters:
        - name: symbol
          in: query
          schema:
            type: string
        - name: currency
          in: query
          schema:
            type: string
        - name: execType
          in: query
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: withCount
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Trade list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /md/v2/orderbook:
    get:
      summary: Get hedged order book
      description: Query current order book snapshot for hedged perpetuals.
      operationId: getHedgedOrderBook
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookResponse'
  /md/v2/trade:
    get:
      summary: Get recent hedged trades
      description: Query recent trades for a hedged perpetual symbol.
      operationId: getHedgedRecentTrades
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Recent trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /md/v2/ticker/24hr:
    get:
      summary: Get 24hr hedged ticker
      description: Query 24-hour ticker statistics for hedged perpetuals.
      operationId: getHedgedTicker24hr
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 24hr ticker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickerResponse'
  /exchange/public/md/v2/kline/last:
    get:
      summary: Get latest klines
      description: Query latest klines with specified resolution.
      operationId: getHedgedKlineLast
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: resolution
          in: query
          required: true
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Kline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/public/md/v2/kline/list:
    get:
      summary: Get klines by time range
      description: Query klines between from and to timestamps.
      operationId: getHedgedKlineList
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: true
          schema:
            type: integer
        - name: to
          in: query
          required: true
          schema:
            type: integer
        - name: resolution
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Kline list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/g-futures/funding-fees:
    get:
      summary: Get funding fee history
      description: Query historical funding fees for hedged perpetuals.
      operationId: getHedgedFundingFees
      tags:
        - Account
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Funding fee history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/g-futures/orders:
    get:
      summary: Get hedged order history
      description: Query order history for hedged perpetuals.
      operationId: getHedgedOrderHistory
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Order history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /api-data/g-futures/orders/by-order-id:
    get:
      summary: Get hedged orders by ID
      description: Query orders by orderID or clOrdID for hedged perpetuals.
      operationId: getHedgedOrderById
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: orderID
          in: query
          schema:
            type: string
        - name: clOrdID
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /api-data/g-futures/trades:
    get:
      summary: Get hedged trade history
      description: Query trade history for hedged perpetuals.
      operationId: getHedgedTradeHistory
      tags:
        - Trades
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Trade history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/g-futures/trading-fees:
    get:
      summary: Get trading fee history
      description: Query trading fees history for hedged perpetuals.
      operationId: getHedgedTradingFees
      tags:
        - Account
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Trading fees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: x-phemex-access-token
      description: HMAC SHA256 signed request. Also requires x-phemex-request-expiry and x-phemex-request-signature headers.
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: object
    HedgedOrderRequest:
      type: object
      required: [symbol, side, posSide, orderQtyRq, ordType]
      properties:
        clOrdID:
          type: string
        symbol:
          type: string
        orderQtyRq:
          type: string
          description: Real quantity (not scaled)
        ordType:
          type: string
          enum: [Limit, Market, Stop, StopLimit]
        priceRp:
          type: string
          description: Real price (not scaled)
        side:
          type: string
          enum: [Buy, Sell]
        posSide:
          type: string
          enum: [Long, Short]
        timeInForce:
          type: string
          enum: [GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly]
        reduceOnly:
          type: boolean
        stopPxRp:
          type: string
        takeProfitRp:
          type: string
        stopLossRp:
          type: string
        triggerType:
          type: string
    OrderResponse:
      type: object
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: object
          properties:
            orderID:
              type: string
            clOrdID:
              type: string
            symbol:
              type: string
            side:
              type: string
            posSide:
              type: string
            ordStatus:
              type: string
            ordType:
              type: string
            priceRp:
              type: string
            orderQtyRq:
              type: string
    OrderListResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            total:
              type: integer
            rows:
              type: array
              items:
                $ref: '#/components/schemas/OrderResponse'
    AccountPositionsResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            account:
              type: object
              properties:
                accountBalanceRv:
                  type: string
                totalUsedBalanceRv:
                  type: string
            positions:
              type: array
              items:
                type: object
                properties:
                  symbol:
                    type: string
                  posSide:
                    type: string
                  size:
                    type: string
                  avgEntryPriceRp:
                    type: string
                  leverageRr:
                    type: string
                  unRealisedPnlRv:
                    type: string
    OrderBookResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            asks:
              type: array
              items:
                type: array
                items:
                  type: string
            bids:
              type: array
              items:
                type: array
                items:
                  type: string
            symbol:
              type: string
            timestamp:
              type: integer
            sequence:
              type: integer
    TickerResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            symbol:
              type: string
            openRp:
              type: string
            highRp:
              type: string
            lowRp:
              type: string
            closeRp:
              type: string
            volumeRq:
              type: string
            markPriceRp:
              type: string
            indexPriceRp:
              type: string
            fundingRateRr:
              type: string