openapi: 3.0.3
info:
  title: Phemex Spot Trading API
  description: REST API for spot trading on Phemex, supporting order placement, wallet queries, market data subscriptions, and 24-hour ticker streams.
  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 spot products
      description: Retrieve product information for spot trading pairs.
      operationId: getSpotProducts
      tags:
        - Market Data
      security: []
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /md/orderbook:
    get:
      summary: Get order book
      description: Fetch current spot order book snapshot.
      operationId: getSpotOrderBook
      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: Retrieve recent trades for a spot symbol.
      operationId: getSpotRecentTrades
      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/spot/ticker/24hr:
    get:
      summary: Get 24hr ticker
      description: Query 24-hour ticker metrics for a spot symbol.
      operationId: getSpotTicker24hr
      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/SpotTickerResponse'
  /v1/md/orderbook:
    get:
      summary: Get order book (v1)
      description: Retrieve order book snapshot using v1 endpoint.
      operationId: getSpotOrderBookV1
      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'
  /spot/orders:
    post:
      summary: Place spot order
      description: Place a new spot order with JSON body.
      operationId: placeSpotOrder
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotOrderRequest'
      responses:
        '200':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
    put:
      summary: Modify spot order
      description: Modify an existing spot order.
      operationId: modifySpotOrder
      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
        - name: priceEp
          in: query
          schema:
            type: integer
        - name: baseQtyEv
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Order modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
    delete:
      summary: Cancel spot order
      description: Cancel a specific spot order.
      operationId: cancelSpotOrder
      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'
    get:
      summary: List active orders
      description: List all open orders for a symbol.
      operationId: listSpotActiveOrders
      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'
  /spot/orders/create:
    put:
      summary: Place spot order via query string
      description: Place a new spot order (preferred method) using URL query string.
      operationId: createSpotOrderQueryString
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          schema:
            type: string
        - name: side
          in: query
          required: true
          schema:
            type: string
            enum: [Buy, Sell]
        - name: qtyType
          in: query
          required: true
          schema:
            type: string
            enum: [ByBase, ByQuote]
        - name: baseQtyEv
          in: query
          schema:
            type: integer
        - name: quoteQtyEv
          in: query
          schema:
            type: integer
        - name: priceEp
          in: query
          schema:
            type: integer
        - name: ordType
          in: query
          schema:
            type: string
            enum: [Limit, Market, Stop, StopLimit]
        - name: timeInForce
          in: query
          schema:
            type: string
            enum: [GoodTillCancel, PostOnly, ImmediateOrCancel, FillOrKill]
        - name: clOrdID
          in: query
          schema:
            type: string
        - name: stopPxEp
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /spot/orders/all:
    delete:
      summary: Cancel all spot orders
      description: Cancel all orders for a spot symbol.
      operationId: cancelAllSpotOrders
      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'
  /spot/orders/active:
    get:
      summary: Query specific active order
      description: Query open orders by clOrdID or orderID.
      operationId: getSpotActiveOrder
      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: Active order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /spot/wallets:
    get:
      summary: Get spot wallet balances
      description: Query spot wallet balances.
      operationId: getSpotWallets
      tags:
        - Wallets
      parameters:
        - name: currency
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Wallet balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponse'
  /exchange/spot/order:
    get:
      summary: Query closed orders (deprecated)
      description: Query closed spot orders. This endpoint is deprecated.
      operationId: getSpotClosedOrders
      deprecated: true
      tags:
        - Orders
      parameters:
        - name: symbol
          in: query
          required: true
          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
      responses:
        '200':
          description: Closed orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
  /exchange/spot/order/trades:
    get:
      summary: Query trade history (deprecated)
      description: Query spot trade history. This endpoint is deprecated.
      operationId: getSpotTradeHistory
      deprecated: true
      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
      responses:
        '200':
          description: Trade history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/v2/depositAddress:
    get:
      summary: Get deposit address
      description: Query deposit address by currency and chain.
      operationId: getSpotDepositAddress
      tags:
        - Wallets
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
        - name: chainName
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deposit address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/depositList:
    get:
      summary: Get deposit history
      description: Query recent deposit history.
      operationId: getSpotDepositHistory
      tags:
        - Wallets
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Deposit list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /exchange/wallets/withdrawList:
    get:
      summary: Get withdrawal history
      description: Query recent withdrawal history.
      operationId: getSpotWithdrawHistory
      tags:
        - Wallets
      parameters:
        - name: currency
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Withdrawal list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/spots/funds:
    get:
      summary: Get funds history
      description: Query funds history for a currency.
      operationId: getSpotFundsHistory
      tags:
        - Account
      parameters:
        - name: currency
          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: Funds history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/spots/orders:
    get:
      summary: Get spot order history
      description: Query order history by symbol.
      operationId: getSpotOrderHistory
      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/spots/orders/by-order-id:
    get:
      summary: Get spot orders by ID
      description: Query orders by specific order IDs.
      operationId: getSpotOrdersByOrderId
      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/spots/pnls:
    get:
      summary: Get profit and loss records
      description: Query spot profit/loss records.
      operationId: getSpotPnls
      tags:
        - Account
      parameters:
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: PNL records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /api-data/spots/trades:
    get:
      summary: Get spot trade history
      description: Query trade history by symbol.
      operationId: getSpotTradesHistory
      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/spots/trades/by-order-id:
    get:
      summary: Get spot trades by order ID
      description: Query trades by order IDs.
      operationId: getSpotTradesByOrderId
      tags:
        - Trades
      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: Trade records
          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
    SpotOrderRequest:
      type: object
      required: [symbol, side, qtyType, ordType]
      properties:
        symbol:
          type: string
        clOrdID:
          type: string
        side:
          type: string
          enum: [Buy, Sell]
        qtyType:
          type: string
          enum: [ByBase, ByQuote]
        quoteQtyEv:
          type: integer
        baseQtyEv:
          type: integer
        priceEp:
          type: integer
        stopPxEp:
          type: integer
        trigger:
          type: string
        ordType:
          type: string
          enum: [Limit, Market, Stop, StopLimit]
        timeInForce:
          type: string
          enum: [GoodTillCancel, PostOnly, ImmediateOrCancel, FillOrKill]
    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
            baseQtyEv:
              type: integer
            priceEp:
              type: integer
    OrderListResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            total:
              type: integer
            rows:
              type: array
              items:
                $ref: '#/components/schemas/OrderResponse'
    SpotTickerResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: object
          properties:
            openEp:
              type: integer
            highEp:
              type: integer
            lowEp:
              type: integer
            lastEp:
              type: integer
            bidEp:
              type: integer
            askEp:
              type: integer
            symbol:
              type: string
            volumeEv:
              type: integer
            turnoverEv:
              type: integer
            timestamp:
              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
    WalletResponse:
      type: object
      properties:
        code:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              currency:
                type: string
              balanceEv:
                type: integer
              lockedTradingBalanceEv:
                type: integer
              lockedWithdrawEv:
                type: integer
              lastUpdateTimeNs:
                type: integer