Rho Protocol User Data API

swagger: '2.0'
info:
  description: ''
  title: Rho Exchange Market Data User Data API
  contact: {}
  version: development
host: ''
basePath: /api/v1
schemes: []
tags:
- name: User Data
paths:
  /margin-accounts:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns all margin accounts, positions, orders, etc. Rate limit weight: 2'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve all margin accounts for a user
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.MarginAccountsResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /margin-accounts/{marginAccount}:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns margin account, positions, orders, etc. Rate limit weight: 1'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve a single margin account
      parameters:
      - type: string
        description: Margin Account ID
        name: marginAccount
        in: path
        required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.MarginAccount'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /margin-accounts/{marginAccount}/candles:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns historical margin snapshots. Rate limit weight: 2'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user margin account candles
      parameters:
      - type: string
        description: Margin Account ID
        name: marginAccount
        in: path
        required: true
      - enum:
        - 1h
        - 1d
        type: string
        description: Candle interval
        name: interval
        in: query
        required: true
      - type: string
        description: Start time (ISO8601 / RFC3339)
        name: startTime
        in: query
      - type: string
        description: End time (ISO8601 / RFC3339)
        name: endTime
        in: query
      - type: integer
        description: Number of candles (default=1000)
        name: limit
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserMarginAccountCandlesResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /users/account:
    get:
      security:
      - Bearer: []
      description: 'Returns total account value, total P&L, etc. Rate limit weight: 1'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve total user account info
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserTotalAccountResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /users/account/candles:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns historical values snapshots. Rate limit weight: 2'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user total account candles
      parameters:
      - enum:
        - 1h
        - 1d
        type: string
        description: Candle interval
        name: interval
        in: query
        required: true
      - type: string
        description: Start time (ISO8601 / RFC3339)
        name: startTime
        in: query
      - type: string
        description: End time (ISO8601 / RFC3339)
        name: endTime
        in: query
      - type: integer
        description: Number of candles (default=1000)
        name: limit
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserAccountCandlesResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/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'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user balances
      parameters:
      - type: string
        description: Margin Account ID (optional)
        name: marginAccount
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserBalances'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/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'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user withdrawable balances
      parameters:
      - type: string
        description: Margin Account ID
        name: marginAccount
        in: query
        required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserWithdrawableBalances'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/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'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user's orders.
      parameters:
      - type: string
        description: Margin Account ID (optional)
        name: marginAccount
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserOrders'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/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'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve user's open positions.
      parameters:
      - type: string
        description: Margin Account ID (optional)
        name: marginAccount
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserPositions'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /users/trades:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns last N trades that belong to that user. Rate limit weight: 2'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve recent trades for a user
      parameters:
      - type: integer
        description: Number of trades (default=100, max=1000)
        name: limit
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserTradesResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
  /users/transfers:
    get:
      security:
      - Bearer: []
      - ApiKey: []
      description: 'Returns last N transfers for the user. Rate limit weight: 2'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Retrieve recent transfers for a user
      parameters:
      - type: integer
        description: Number of updates (default=100, max=1000)
        name: limit
        in: query
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/dto.UserTransfersResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/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'
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - User Data
      summary: Request withdrawal
      parameters:
      - description: Withdrawal request payload
        name: withdrawalRequest
        in: body
        required: true
        schema:
          $ref: '#/definitions/dto.RestWithdrawalRequest'
      responses:
        '202':
          description: Withdrawal request accepted for processing
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/dto.ExternalError'
        '500':
          description: Internal Error
          schema:
            $ref: '#/definitions/dto.ExternalError'
definitions:
  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
  dto.UserTotalAccountSummary:
    type: object
    properties:
      accountValue:
        type: string
      baseCurrency:
        type: string
      freeBalance:
        type: string
      liquidationFees:
        type: string
      marginAccounts:
        type: array
        items:
          $ref: '#/definitions/dto.MarginAccountSummary'
      realizedPnl:
        type: string
      seqId:
        type: integer
      systemFees:
        type: string
      totalPnL:
        type: string
      tradingFees:
        type: string
      userId:
        type: string
  dto.UserTotalAccountResponse:
    type: object
    properties:
      account:
        $ref: '#/definitions/dto.UserTotalAccountSummary'
  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.UserAccountCandlesResponse:
    type: object
    properties:
      candles:
        type: array
        items:
          $ref: '#/definitions/dto.UserAccountCandle'
  dto.UserBalances:
    type: object
    properties:
      marginAccountsBalances:
        type: array
        items:
          $ref: '#/definitions/dto.CurrencyBalance'
      seqId:
        type: string
        example: '0'
      totalBalances:
        type: array
        items:
          $ref: '#/definitions/dto.CurrencyBalance'
  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.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.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.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.UserTradesResponse:
    type: object
    properties:
      trades:
        type: array
        items:
          $ref: '#/definitions/dto.UserTrade'
  dto.UserPositions:
    type: object
    properties:
      positions:
        type: array
        items:
          $ref: '#/definitions/dto.Position'
      positionsMarginDetails:
        type: array
        items:
          $ref: '#/definitions/dto.PositionMarginDetails'
      seqId:
        type: string
        example: '0'
  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.UserOrders:
    type: object
    properties:
      orders:
        type: array
        items:
          $ref: '#/definitions/dto.Order'
      seqId:
        type: string
        example: '0'
  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: '#/definitions/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.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.CurrencyBalance:
    type: object
    properties:
      currency:
        type: string
      marginAccount:
        type: string
      netBalance:
        type: number
      realizedPnl:
        type: number
  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.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.UserWithdrawableBalances:
    type: object
    properties:
      nextWithdrawSequenceId:
        type: string
        example: '0'
      withdrawables:
        type: array
        items:
          $ref: '#/definitions/dto.WithdrawableBalance'
  dto.UserTransfersResponse:
    type: object
    properties:
      updates:
        type: array
        items:
          $ref: '#/definitions/dto.Transfer'
  dto.MarginAccountsResponse:
    type: object
    properties:
      userMarginAccounts:
        type: array
        items:
          $ref: '#/definitions/dto.MarginAccount'
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header