openapi: 3.0.3
info:
  title: Phemex Contract Trading API
  description: REST API for trading perpetual contracts on Phemex, including order placement, position management, account queries, and market data.
  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 product information
      description: Retrieve product information including symbols and scaling factors for contract trading.
      operationId: getContractProducts
      tags:
        - Market Data
      security: []
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'
  /orders:
    post:
      summary: Place order
      description: Place a new contract order with JSON body.
      operationId: placeContractOrder
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractOrderRequest'
      responses:
        '200':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
    delete:
      summary: Bulk cancel orders
      description: Cancel multiple orders by orderID list.
      operationId: bulkCancelContractOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
          description: Trading symbol
        - name: orderID
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated order IDs
      responses:
        '200':
          description: Orders cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /orders/create:
    put:
      summary: Place order via query string
      description: Create order via URL query string parameters (preferred method).
      operationId: createContractOrderQueryString
      tags:
        - Orders
      parameters:
        - name: clOrdID
          in: query
          schema:
            type: string
          description: Client order ID
        - name: symbol
          in: query
          required: true
          schema:
            type: string
          description: Trading symbol
        - name: side
          in: query
          required: true
          schema:
            type: string
            enum: [Buy, Sell]
          description: Order side
        - name: orderQty
          in: query
          required: true
          schema:
            type: integer
          description: Order quantity
        - name: ordType
          in: query
          schema:
            type: string
            enum: [Limit, Market, Stop, StopLimit]
          description: Order type
        - name: priceEp
          in: query
          schema:
            type: integer
          description: Scaled price
        - name: timeInForce
          in: query
          schema:
            type: string
            enum: [GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly]
          description: Time in force
        - name: reduceOnly
          in: query
          schema:
            type: boolean
          description: Reduce-only flag
        - name: closeOnTrigger
          in: query
          schema:
            type: boolean
          description: Close on trigger flag
        - name: stopPxEp
          in: query
          schema:
            type: integer
          description: Scaled stop price
        - name: takeProfitEp
          in: query
          schema:
            type: integer
          description: Scaled take profit price
        - name: stopLossEp
          in: query
          schema:
            type: integer
          description: Scaled stop loss price
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /orders/replace:
    put:
      summary: Modify order
      description: Modify an existing order by orderID or clOrdID.
      operationId: modifyContractOrder
      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: priceEp
          in: query
          schema:
            type: integer
        - name: orderQty
          in: query
          schema:
            type: integer
        - name: stopPxEp
          in: query
          schema:
            type: integer
        - name: takeProfitEp
          in: query
          schema:
            type: integer
        - name: stopLossEp
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Order modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /orders/cancel:
    delete:
      summary: Cancel order
      description: Cancel a single order by orderID or clOrdID.
      operationId: cancelContractOrder
      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 cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /orders/all:
    delete:
      summary: Cancel all orders
      description: Cancel all orders for a symbol.
      operationId: cancelAllContractOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: untriggered
          in: query
          schema:
            type: boolean
        - name: text
          in: query
          schema:
            type: string
      responses:
        '200':
          description: All orders cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /orders/activeList:
    get:
      summary: Get active orders
      description: Retrieve open orders for a symbol.
      operationId: getActiveContractOrders
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Active orders list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /accounts/accountPositions:
    get:
      summary: Get account and positions
      description: Query trading account and positions.
      operationId: getContractAccountPositions
      tags:
        - Account
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
          description: Settlement currency (e.g. BTC, USD)
      responses:
        '200':
          description: Account and positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPositionsResponse'
  /accounts/positions:
    get:
      summary: Get positions with PNL
      description: Query positions with unrealized PNL at mark price.
      operationId: getContractPositions
      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/PositionsResponse'
  /positions/leverage:
    put:
      summary: Set leverage
      description: Modify position leverage for a symbol.
      operationId: setContractLeverage
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: leverage
          in: query
          schema:
            type: number
        - name: leverageEr
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Leverage set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /positions/riskLimit:
    put:
      summary: Set risk limit
      description: Adjust position risk limit.
      operationId: setContractRiskLimit
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: riskLimit
          in: query
          schema:
            type: integer
        - name: riskLimitEv
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Risk limit set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /positions/assign:
    post:
      summary: Assign margin
      description: Allocate balance to isolated margin position.
      operationId: assignContractMargin
      tags:
        - Positions
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: posBalanceEv
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Margin assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/order/list:
    get:
      summary: Get order history
      description: Query closed order history.
      operationId: getContractOrderHistory
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
          description: Start time in milliseconds
        - name: end
          in: query
          schema:
            type: integer
          description: End time in milliseconds
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: ordStatus
          in: query
          schema:
            type: string
        - name: withCount
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Order history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /exchange/order:
    get:
      summary: Get order by ID
      description: Fetch orders by orderID or clOrdID.
      operationId: getContractOrderById
      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'
  /exchange/order/trade:
    get:
      summary: Get trade history
      description: Query user trade execution history.
      operationId: getContractTradeHistory
      tags:
        - Trades
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: tradeType
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: withCount
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Trade history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeListResponse'
  /md/orderbook:
    get:
      summary: Get order book
      description: Fetch current order book snapshot.
      operationId: getContractOrderBook
      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/trade:
    get:
      summary: Get recent trades
      description: Get recent trades for a symbol.
      operationId: getContractRecentTrades
      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/TradeListResponse'
  /exchange/public/md/v2/kline:
    get:
      summary: Get kline data
      description: Retrieve kline/candlestick data.
      operationId: getContractKlines
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: resolution
          in: query
          required: true
          schema:
            type: integer
          description: Kline resolution in seconds
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Kline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlineResponse'
  /v1/md/ticker/24hr:
    get:
      summary: Get 24hr ticker
      description: Query 24-hour ticker data.
      operationId: getContractTicker24hr
      tags:
        - Market Data
      security: []
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ticker data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickerResponse'
  /api-data/futures/funding-fees:
    get:
      summary: Get funding fee history
      description: Query historical funding fee records.
      operationId: getContractFundingFees
      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/futures/orders:
    get:
      summary: Get futures order history
      description: Fetch order history with optional time range.
      operationId: getFuturesOrderHistory
      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/futures/orders/by-order-id:
    get:
      summary: Get futures orders by ID
      description: Retrieve orders by orderID or clOrdID.
      operationId: getFuturesOrderById
      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/futures/trades:
    get:
      summary: Get futures trade history
      description: Query trade execution history.
      operationId: getFuturesTradeHistory
      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/TradeListResponse'
  /api-data/futures/trading-fees:
    get:
      summary: Get trading fee history
      description: Retrieve trading fee history.
      operationId: getFuturesTradingFees
      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 fee history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/transferOut:
    post:
      summary: Transfer to sub-client
      description: Transfer wallet balance to sub-client.
      operationId: contractTransferOut
      tags:
        - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amountEv:
                  type: integer
                currency:
                  type: string
                clientCnt:
                  type: integer
      responses:
        '200':
          description: Transfer result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/transferIn:
    post:
      summary: Transfer from sub-client
      description: Withdraw balance from sub-client wallet.
      operationId: contractTransferIn
      tags:
        - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amountEv:
                  type: integer
                currency:
                  type: string
                clientCnt:
                  type: integer
      responses:
        '200':
          description: Transfer result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/createWithdraw:
    post:
      summary: Create withdrawal
      description: Initiate a withdrawal request.
      operationId: createWithdraw
      tags:
        - Wallets
      parameters:
        - name: otpCode
          in: query
          schema:
            type: string
          description: One-time password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, amountEv, currency]
              properties:
                address:
                  type: string
                amountEv:
                  type: integer
                currency:
                  type: string
      responses:
        '200':
          description: Withdrawal created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/cancelWithdraw:
    post:
      summary: Cancel withdrawal
      description: Cancel a pending withdrawal request.
      operationId: cancelWithdraw
      tags:
        - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Withdrawal cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/withdrawList:
    get:
      summary: Get withdrawal history
      description: List withdrawal history.
      operationId: getWithdrawHistory
      tags:
        - Wallets
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: withCount
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Withdrawal list
          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
    ContractOrderRequest:
      type: object
      required: [symbol, side, orderQty, ordType]
      properties:
        symbol:
          type: string
        clOrdID:
          type: string
        side:
          type: string
          enum: [Buy, Sell]
        priceEp:
          type: integer
          description: Scaled price (price * 10^priceScale)
        orderQty:
          type: integer
        ordType:
          type: string
          enum: [Limit, Market, Stop, StopLimit]
        timeInForce:
          type: string
          enum: [GoodTillCancel, ImmediateOrCancel, FillOrKill, PostOnly]
        reduceOnly:
          type: boolean
        closeOnTrigger:
          type: boolean
        stopPxEp:
          type: integer
        takeProfitEp:
          type: integer
        stopLossEp:
          type: integer
    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
            ordStatus:
              type: string
            cumQty:
              type: integer
            leavesQty:
              type: integer
            priceEp:
              type: integer
            ordType:
              type: string
    OrderListResponse:
      type: object
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: object
          properties:
            total:
              type: integer
            rows:
              type: array
              items:
                $ref: '#/components/schemas/OrderResponse'
    AccountPositionsResponse:
      type: object
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: object
          properties:
            account:
              type: object
              properties:
                accountId:
                  type: integer
                accountBalanceEv:
                  type: integer
                totalUsedBalanceEv:
                  type: integer
            positions:
              type: array
              items:
                type: object
                properties:
                  symbol:
                    type: string
                  side:
                    type: string
                  size:
                    type: integer
                  avgEntryPriceEp:
                    type: integer
                  leverageEr:
                    type: integer
                  liquidationPriceEp:
                    type: integer
    PositionsResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            positions:
              type: array
              items:
                type: object
                properties:
                  symbol:
                    type: string
                  side:
                    type: string
                  size:
                    type: integer
                  unRealisedPnlEv:
                    type: integer
                  markPriceEp:
                    type: integer
    TradeListResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            total:
              type: integer
            rows:
              type: array
              items:
                type: object
                properties:
                  execID:
                    type: string
                  execQty:
                    type: integer
                  execPriceEp:
                    type: integer
                  tradeType:
                    type: string
                  execFeeEv:
                    type: integer
    OrderBookResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            book:
              type: object
              properties:
                asks:
                  type: array
                  items:
                    type: array
                    items:
                      type: integer
                bids:
                  type: array
                  items:
                    type: array
                    items:
                      type: integer
            sequence:
              type: integer
            timestamp:
              type: integer
            symbol:
              type: string
    KlineResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            rows:
              type: array
              items:
                type: array
                items:
                  type: number
    ProductsResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            products:
              type: array
              items:
                type: object
                properties:
                  symbol:
                    type: string
                  priceScale:
                    type: integer
                  ratioScale:
                    type: integer
                  valueScale:
                    type: integer
                  settleCurrency:
                    type: string
    TickerResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            openEp:
              type: integer
            highEp:
              type: integer
            lowEp:
              type: integer
            closeEp:
              type: integer
            volumeEv:
              type: integer
            fundingRateEr:
              type: integer
            markEp:
              type: integer
            indexEp:
              type: integer
            symbol:
              type: string