Ondo Finance Positions API

openapi: 3.0.4
info:
  title: GM Backend Account Positions API
  description: An API spec for the Ondo GM Backend API.
  version: 1.0.0
servers:
- url: https://api.gm.ondo.finance
  description: GM Backend API
tags:
- name: Positions
paths:
  /v1/perps/positions:
    get:
      summary: Get Positions
      description: Returns all open positions for the authenticated account.
      operationId: getPerpsPositions
      tags:
      - Positions
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      responses:
        '200':
          description: List of positions
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GenericResponse'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        $ref: '#/components/schemas/ApiPosition'
              example:
                success: true
                result:
                - market: AAPL-USD.P
                  direction: long
                  netQuantity: '10.00'
                  averageEntryPrice: '225.00'
                  usedMargin: '1125.00'
                  unrealizedPnl: '25.00'
                  markPrice: '227.50'
                  liquidationPrice: '180.00'
                  bankruptcyPrice: '170.00'
                  maintenanceMargin: '112.50'
                  notionalValue: '2275.00'
                  leverage: '2.0'
                  netFundingSinceNeutral: '-1.23'
                  returnOnEquity: '0.022'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/perps/leverage:
    get:
      summary: Get Leverage
      description: Returns the current leverage setting(s) for the authenticated account. If `market` is provided, returns leverage for that market only; otherwise returns leverage for all markets.
      operationId: getPerpsLeverage
      tags:
      - Positions
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - name: market
        in: query
        description: Filter by market. If omitted, returns leverage for all markets.
        required: false
        schema:
          type: string
          example: AAPL-USD.P
      responses:
        '200':
          description: Array of leverage settings
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GenericResponse'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        $ref: '#/components/schemas/ApiLeverage'
              example:
                success: true
                result:
                - market: AAPL-USD.P
                  leverage: '10'
                - market: TSLA-USD.P
                  leverage: '5'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Set Leverage
      description: Sets the leverage for a market. Leverage must be a positive integer and cannot exceed the market's maximum leverage. Reducing leverage while insufficient margin is available will return 400 with `error_code=insufficient_margin`.
      operationId: setPerpsLeverage
      tags:
      - Positions
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLeverageReq'
      responses:
        '200':
          description: Leverage updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
              example:
                success: true
        '400':
          description: Bad request. The request was malformed or failed validation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    description: Human-readable error message
                  error_code:
                    type: string
                    enum:
                    - invalid_leverage
                    - invalid_market
              example:
                success: false
                error: Description of the error
                error_code: invalid_leverage
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Forbidden:
      description: Access denied. The authenticated account does not have permission.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                description: Human-readable error message
              error_code:
                type: string
                enum:
                - account_closed
                - account_not_allowed
                - forbidden
                - ip_not_permitted
                - key_doesnt_have_scope
          example:
            success: false
            error: Description of the error
            error_code: account_not_allowed
    TooManyRequests:
      description: Rate limit exceeded. Slow down request frequency.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                description: Human-readable error message
              error_code:
                type: string
                enum:
                - too_many_requests
          example:
            success: false
            error: Description of the error
            error_code: too_many_requests
    Unauthorized:
      description: Authentication required. Provide a valid JWT or API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                description: Human-readable error message
              error_code:
                type: string
                enum:
                - api_key_not_found
                - auth_expired
                - auth_invalid
                - auth_missing
                - failed_to_decode_hex_signature
                - failed_to_parse_timestamp
                - signature_mismatch
                - timestamp_too_far
          example:
            success: false
            error: Description of the error
            error_code: auth_missing
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                description: Human-readable error message
              error_code:
                type: string
                enum:
                - server_is_busy
                - service_unavailable
                - unknown
          example:
            success: false
            error: Description of the error
            error_code: unknown
  schemas:
    ApiLeverage:
      type: object
      required:
      - market
      - leverage
      properties:
        market:
          type: string
          description: Perps market
          example: AAPL-USD.P
        leverage:
          type: string
          description: Current leverage setting for this market
          example: '10'
    ApiPosition:
      type: object
      required:
      - market
      - direction
      - netQuantity
      - averageEntryPrice
      - usedMargin
      - unrealizedPnl
      - markPrice
      - liquidationPrice
      - bankruptcyPrice
      - maintenanceMargin
      - notionalValue
      - leverage
      - netFundingSinceNeutral
      - returnOnEquity
      properties:
        market:
          type: string
          description: Perps market
          example: AAPL-USD.P
        direction:
          type: string
          description: Position direction
          enum:
          - long
          - short
          - neutral
          example: short
        netQuantity:
          type: string
          description: Size of the position in base currency
          example: '1.5489'
        averageEntryPrice:
          type: string
          description: Average entry price
          example: '20566.84'
        usedMargin:
          type: string
          description: Margin used for the position
          example: '2566.84'
        unrealizedPnl:
          type: string
          description: Unrealized PNL relative to the mark price. Positive is profit, negative is loss.
          example: '-900.54'
        markPrice:
          type: string
          description: Current mark price
          example: '20000.54'
        liquidationPrice:
          type: string
          description: Price at which the position will be liquidated
          example: '9000.87'
        bankruptcyPrice:
          type: string
          description: Price at which bankruptcy occurs during liquidation
          example: '6000.11'
        maintenanceMargin:
          type: string
          description: Maintenance margin required for this position
          example: '1500.22'
        notionalValue:
          type: string
          description: Notional value of the position
          example: '30000.00'
        leverage:
          type: string
          description: Current effective leverage for this position
          example: '10.0'
        netFundingSinceNeutral:
          type: string
          description: Net funding payments since the position was opened
          example: '-12.34'
        returnOnEquity:
          type: string
          description: Return on equity for this position
          example: '-0.35'
        stopLossTriggerPrice:
          type: string
          description: Triggering price for stop loss order (optional)
          example: '18000.00'
        takeProfitTriggerPrice:
          type: string
          description: Triggering price for take profit order (optional)
          example: '25000.00'
    SetLeverageReq:
      type: object
      required:
      - market
      - leverage
      properties:
        market:
          type: string
          description: Perps market to set leverage for
          example: AAPL-USD.P
        leverage:
          type: string
          description: New leverage value. Must be a positive integer not exceeding the market maximum.
          example: '10'
    GenericResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: true
        error:
          type: string
          description: Error message, present only on failure
          example: ''
        error_code:
          type: string
          description: Semantic error code. See each endpoint's error responses for the specific codes it can return.
        deprecated:
          type: string
          description: Deprecation notice, if applicable
          example: ''
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header