Rho Protocol User Data API

openapi: 3.2.0
info:
  description: ''
  title: Rho Exchange Market Data User Data API
  contact: {}
  version: development
servers:
- url: /api/v1
tags:
- name: User Data
paths:
  /margin-accounts:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns all margin accounts, positions, orders, etc. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve all margin accounts for a user
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.MarginAccountsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /margin-accounts/{marginAccount}:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns margin account, positions, orders, etc. Rate limit weight: 1'
      tags:
      - User Data
      summary: Retrieve a single margin account
      parameters:
      - description: Margin Account ID
        name: marginAccount
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.MarginAccount'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /margin-accounts/{marginAccount}/candles:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns historical margin snapshots. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve user margin account candles
      parameters:
      - description: Margin Account ID
        name: marginAccount
        in: path
        required: true
        schema:
          type: string
      - description: Candle interval
        name: interval
        in: query
        required: true
        schema:
          type: string
          enum:
          - 1h
          - 1d
      - description: Start time (ISO8601 / RFC3339)
        name: startTime
        in: query
        schema:
          type: string
      - description: End time (ISO8601 / RFC3339)
        name: endTime
        in: query
        schema:
          type: string
      - description: Number of candles (default=1000)
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserMarginAccountCandlesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/account:
    get:
      security:
      - Bearer: []
      description: 'Returns total account value, total P&L, etc. Rate limit weight: 1'
      tags:
      - User Data
      summary: Retrieve total user account info
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserTotalAccountResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/account/candles:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns historical values snapshots. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve user total account candles
      parameters:
      - description: Candle interval
        name: interval
        in: query
        required: true
        schema:
          type: string
          enum:
          - 1h
          - 1d
      - description: Start time (ISO8601 / RFC3339)
        name: startTime
        in: query
        schema:
          type: string
      - description: End time (ISO8601 / RFC3339)
        name: endTime
        in: query
        schema:
          type: string
      - description: Number of candles (default=1000)
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserAccountCandlesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/balances:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns user balances across all margin accounts or for a specific margin account. Rate limit weight: 1'
      tags:
      - User Data
      summary: Retrieve user balances
      parameters:
      - description: Margin Account ID (optional)
        name: marginAccount
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserBalances'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/balances/withdrawable:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns user balances breakdown and other relevant information for withdrawl for a specific margin account. Rate limit weight: 1'
      tags:
      - User Data
      summary: Retrieve user withdrawable balances
      parameters:
      - description: Margin Account ID
        name: marginAccount
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserWithdrawableBalances'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/orders:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns all orders across all margin accounts, or just those for a specified margin account. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve user's orders.
      parameters:
      - description: Margin Account ID (optional)
        name: marginAccount
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserOrders'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/positions:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns open positions across all margin accounts, or the specified margin account. Rate limit weight: 1'
      tags:
      - User Data
      summary: Retrieve user's open positions.
      parameters:
      - description: Margin Account ID (optional)
        name: marginAccount
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserPositions'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/trades:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns last N trades that belong to that user. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve recent trades for a user
      parameters:
      - description: Number of trades (default=100, max=1000)
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserTradesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/transfers:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns last N transfers for the user. Rate limit weight: 2'
      tags:
      - User Data
      summary: Retrieve recent transfers for a user
      parameters:
      - description: Number of updates (default=100, max=1000)
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.UserTransfersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
  /users/withdrawals:
    post:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Submits a withdrawal request. If marginAccount is specified, funds are deallocated before withdrawal. Rate limit weight: 1'
      tags:
      - User Data
      summary: Request withdrawal
      responses:
        '202':
          description: Withdrawal request accepted for processing
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.ExternalError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.RestWithdrawalRequest'
        description: Withdrawal request payload
        required: true
components:
  schemas:
    dto.MarginAccount:
      type: object
      properties:
        baseCurrency:
          type: string
        dv01:
          type: string
        dv100:
          type: string
        initialMarginRequirement:
          type: string
        leverage:
          type: string
        liquidationFees:
          type: string
        maintenanceMarginRequirement:
          type: string
        marginAccount:
          type: string
        realizedPnl:
          type: string
        riskDirection:
          type: string
        seqId:
          type: string
          example: '0'
        supportedCurrencies:
          type: array
          items:
            type: string
        totalMargin:
          type: string
        totalPnl:
          type: string
        tradingFees:
          type: string
        userId:
          type: string
        withdrawableBalance:
          type: string
    dto.CurrencyBalance:
      type: object
      properties:
        currency:
          type: string
        marginAccount:
          type: string
        netBalance:
          type: number
        realizedPnl:
          type: number
    dto.Transfer:
      type: object
      properties:
        chainAddress:
          type: string
        chainId:
          type: string
        chainTxHash:
          type: string
        cmdSeqId:
          type: string
          example: '0'
        currencyId:
          type: string
        custodianType:
          type: string
        deadline:
          type: string
        delta:
          type: string
        fee:
          type: string
        marginAccount:
          type: string
        newAccountFreeBalance:
          type: string
        newMarginAccountBalance:
          type: string
        time:
          type: string
        transferEntitySeqId:
          type: string
          example: '0'
        transferExecSeqId:
          type: string
          example: '0'
        transferStatus:
          type: string
          enum:
          - pending
          - confirmed
          - canceled
        transferType:
          type: string
          enum:
          - deposit
          - withdrawal
          - allocation-to-margin-account
          - deallocation-from-margin-account
          - exchange-fees-credit
          - delegation-from-custodian
          - undelegation-to-custodian
        unwrapNativeToken:
          type: boolean
        userCustodyAccountId:
          type: string
        userId:
          type: string
    dto.Position:
      type: object
      properties:
        avgPrice:
          type: string
        closedFixedTokens:
          type: string
        closedFloatTradeValue:
          type: string
        currentOpenPositionClosedFixedTokens:
          type: string
        currentOpenPositionClosedFloatTradeValue:
          type: string
        currentOpenPositionLiquidationFees:
          type: string
        currentOpenPositionRealizedPnL:
          type: string
        currentOpenPositionTradingFees:
          type: string
        dv01:
          type: string
        dv100:
          type: string
        isFinalized:
          type: boolean
        isMatured:
          type: boolean
        liquidationFees:
          type: string
        marginAccount:
          type: string
        notional:
          type: string
        realizedPnl:
          type: string
        riskDirection:
          type: string
        symbol:
          type: string
        totalFixedTokens:
          type: string
        totalFloatTokens:
          type: string
        totalFloatTradeValue:
          type: string
        totalPnl:
          type: string
        tradingFees:
          type: string
    dto.PositionMarginDetails:
      type: object
      properties:
        initialMarginRequirement:
          type: string
        leverage:
          type: string
        liquidationRate:
          type: string
        maintenanceMarginRequirement:
          type: string
        marginAccount:
          type: string
        pendingLongVolume:
          type: string
        pendingShortVolume:
          type: string
        symbol:
          type: string
    dto.UserTotalAccountSummary:
      type: object
      properties:
        accountValue:
          type: string
        baseCurrency:
          type: string
        freeBalance:
          type: string
        liquidationFees:
          type: string
        marginAccounts:
          type: array
          items:
            $ref: '#/components/schemas/dto.MarginAccountSummary'
        realizedPnl:
          type: string
        seqId:
          type: integer
        systemFees:
          type: string
        totalPnL:
          type: string
        tradingFees:
          type: string
        userId:
          type: string
    dto.UserOrders:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/dto.Order'
        seqId:
          type: string
          example: '0'
    dto.UserPositions:
      type: object
      properties:
        positions:
          type: array
          items:
            $ref: '#/components/schemas/dto.Position'
        positionsMarginDetails:
          type: array
          items:
            $ref: '#/components/schemas/dto.PositionMarginDetails'
        seqId:
          type: string
          example: '0'
    dto.UserAccountCandlesResponse:
      type: object
      properties:
        candles:
          type: array
          items:
            $ref: '#/components/schemas/dto.UserAccountCandle'
    dto.UserBalances:
      type: object
      properties:
        marginAccountsBalances:
          type: array
          items:
            $ref: '#/components/schemas/dto.CurrencyBalance'
        seqId:
          type: string
          example: '0'
        totalBalances:
          type: array
          items:
            $ref: '#/components/schemas/dto.CurrencyBalance'
    dto.RestWithdrawalRequest:
      type: object
      required:
      - amount
      - chainId
      - currencyId
      - ownerSignature
      properties:
        amount:
          type: string
          maxLength: 128
        chainId:
          type: string
        clientWithdrawalId:
          type: string
          maxLength: 36
        currencyId:
          type: string
          maxLength: 8
        deadline:
          type: string
          minimum: 0
          example: '0'
        marginAccount:
          type: string
        ownerSignature:
          description: 'TODO: in order to be able to validate this we need to use a string'
          type: string
        unwrapNativeToken:
          type: boolean
    dto.MarginAccountsResponse:
      type: object
      properties:
        userMarginAccounts:
          type: array
          items:
            $ref: '#/components/schemas/dto.MarginAccount'
    dto.UserTotalAccountResponse:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/dto.UserTotalAccountSummary'
    dto.UserWithdrawableBalances:
      type: object
      properties:
        nextWithdrawSequenceId:
          type: string
          example: '0'
        withdrawables:
          type: array
          items:
            $ref: '#/components/schemas/dto.WithdrawableBalance'
    dto.UserTransfersResponse:
      type: object
      properties:
        updates:
          type: array
          items:
            $ref: '#/components/schemas/dto.Transfer'
    dto.WithdrawableBalance:
      type: object
      properties:
        currency:
          type: string
        fee:
          type: number
        lockedBalance:
          type: number
        marginAccount:
          type: string
        maxNetWithdrawAmount:
          type: number
        withdrawableBalance:
          type: number
    dto.UserMarginAccountCandlesResponse:
      type: object
      properties:
        candles:
          type: array
          items:
            $ref: '#/components/schemas/dto.UserMarginAccountCandle'
    dto.UserTrade:
      type: object
      properties:
        cmdSeqId:
          type: string
          example: '0'
        floatIndex:
          type: string
        liquidationFees:
          type: string
        liquidityRole:
          type: string
          enum:
          - maker
          - taker
        marginAccount:
          type: string
        orderId:
          type: string
          example: '0'
        price:
          type: string
        side:
          type: string
          enum:
          - sell
          - buy
        symbol:
          type: string
        time:
          type: string
        tradeType:
          type: string
          enum:
          - regular
          - liquidation
          - self-trade
        tradingFees:
          type: string
        userId:
          type: string
        userTradeSeqId:
          type: string
          example: '0'
        volume:
          type: string
    dto.Order:
      type: object
      properties:
        avgExecutedPrice:
          type: string
        cancellationReason:
          type: string
          enum:
          - user-request
          - auto-risk-reducing
        clientOrderId:
          type: string
        createdAt:
          type: string
        executedQuantity:
          type: string
        initialQuantity:
          type: string
        lastExecutedPrice:
          type: string
        lastExecutedQuantity:
          type: string
        leavesQuantity:
          type: string
        marginAccount:
          type: string
        orderId:
          type: string
          example: '0'
        price:
          type: string
        seqId:
          type: string
          example: '0'
        side:
          type: string
          enum:
          - sell
          - buy
        status:
          type: string
          enum:
          - new
          - partially-filled
          - filled
          - rejected
          - cancelled
        symbol:
          type: string
        userId:
          type: string
    dto.UserAccountCandle:
      type: object
      properties:
        closeRealizedPnL:
          type: string
        closeTime:
          type: string
        closeTotalPnL:
          type: string
        closeTotalValue:
          type: string
        closeUnrealizedPnL:
          type: string
        highRealizedPnL:
          type: string
        highTotalPnL:
          type: string
        highTotalValue:
          type: string
        highUnrealizedPnL:
          type: string
        interval:
          type: string
        liquidationFeesAtClose:
          type: string
        liquidationFeesAtOpen:
          type: string
        lowRealizedPnL:
          type: string
        lowTotalPnL:
          type: string
        lowTotalValue:
          type: string
        lowUnrealizedPnL:
          type: string
        openRealizedPnL:
          type: string
        openTime:
          type: string
        openTotalPnL:
          type: string
        openTotalValue:
          type: string
        openUnrealizedPnL:
          type: string
        seqId:
          type: string
          example: '0'
        systemFeesAtClose:
          type: string
        systemFeesAtOpen:
          type: string
        tradingFeesAtClose:
          type: string
        tradingFeesAtOpen:
          type: string
        userId:
          type: string
    dto.ExternalError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        params:
          description: Params carries stable flat string metadata for selected V2 AppErrors only.
          type: object
          additionalProperties:
            type: string
        requestId:
          type: string
        seqId:
          type: string
          example: '0'
    dto.UserMarginAccountCandle:
      type: object
      properties:
        closeMargin:
          type: string
        closeRealizedPnL:
          type: string
        closeTime:
          type: string
        closeTotalPnL:
          type: string
        closeUnrealizedPnL:
          type: string
        highMargin:
          type: string
        highRealizedPnL:
          type: string
        highTotalPnL:
          type: string
        highUnrealizedPnL:
          type: string
        interval:
          type: string
        liquidationFeesAtClose:
          type: string
        liquidationFeesAtOpen:
          type: string
        lowMargin:
          type: string
        lowRealizedPnL:
          type: string
        lowTotalPnL:
          type: string
        lowUnrealizedPnL:
          type: string
        marginAccount:
          type: string
        openMargin:
          type: string
        openRealizedPnL:
          type: string
        openTime:
          type: string
        openTotalPnL:
          type: string
        openUnrealizedPnL:
          type: string
        seqId:
          type: string
          example: '0'
        tradingFeesAtClose:
          type: string
        tradingFeesAtOpen:
          type: string
        userId:
          type: string
    dto.UserTradesResponse:
      type: object
      properties:
        trades:
          type: array
          items:
            $ref: '#/components/schemas/dto.UserTrade'
    dto.MarginAccountSummary:
      type: object
      properties:
        currencyId:
          type: string
        id:
          type: string
        initialMarginRatio:
          type: string
        liquidationFees:
          type: string
        liquidationFeesInUsd:
          type: string
        maintenanceMarginRatio:
          type: string
        marginAccountValue:
          type: string
        marginAccountValueInUsd:
          type: string
        realizedPnl:
          type: string
        realizedPnlInUsd:
          type: string
        totalPnl:
          type: string
        totalPnlInUsd:
          type: string
        tradingFees:
          type: string
        tradingFeesInUsd:
          type: string
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header