> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bendbasis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Positions

> List positions in a portfolio

```bash theme={null}
curl "https://api.bendbasis.com/v1/portfolios/PORTFOLIO_ID/positions?statuses=open&include=performance" \
  -H "Authorization: Bearer $BENDBASIS_API_KEY"
```


## OpenAPI

````yaml GET /v1/portfolios/{portfolio_id}/positions
openapi: 3.1.0
info:
  title: bendbasis API
  description: Funding market and arbitrage data from bendbasis.
  version: 1.0.0-preview
servers:
  - url: https://api.bendbasis.com
security: []
tags:
  - name: Portfolio
    description: Read-only access to your portfolios and positions.
paths:
  /v1/portfolios/{portfolio_id}/positions:
    get:
      tags:
        - Portfolio
      summary: List positions
      operationId: listPortfolioPositions
      parameters:
        - name: portfolio_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: statuses
          in: query
          required: false
          description: Filter by status. Omit to return open and closed positions.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - open
                - closed
            uniqueItems: true
        - name: include
          in: query
          required: false
          description: 'Include lifetime performance. Maximum page size: 100.'
          schema:
            type: string
            enum:
              - performance
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          required: false
          description: Value returned in next_cursor.
          schema:
            type: string
      responses:
        '200':
          description: Position collection
          headers:
            X-API-Version:
              schema:
                type: string
              example: v1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionCollection'
              example:
                data:
                  - position_id: de3e7930-4762-4b6d-80f0-13aa8a66ecfa
                    asset: BTC
                    status: open
                    opened_at: '2026-09-01T08:00:00.000Z'
                    closed_at: null
                    legs:
                      - side: long
                        market_id: 15036
                        exchange: binance
                        symbol: BTCUSDT
                        leverage: 2
                        quantity: 0.1
                        open_price: 108000
                        mark_price: 108240.5
                        mark_price_updated_at: '2026-09-13T11:59:57.000Z'
                      - side: short
                        market_id: 125
                        exchange: bybit
                        symbol: BTCUSDT
                        leverage: 2
                        quantity: 0.1
                        open_price: 108015
                        mark_price: 108255.2
                        mark_price_updated_at: '2026-09-13T11:59:54.000Z'
                    performance:
                      funding_pnl: 42.5
                      fees:
                        paid: 8.4
                        estimated_exit: 8.4
                      spread_pnl:
                        realized: 0
                        unrealized: 12.1
                      net_pnl: 37.8
                      duration_days: 12
                      apr: 21.29
                      calculated_at: '2026-09-13T12:00:00.000Z'
                next_cursor: null
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - BearerAuth: []
components:
  schemas:
    PositionCollection:
      type: object
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PositionSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: Cursor for the next page.
    PositionSummary:
      type: object
      additionalProperties: false
      required:
        - position_id
        - asset
        - status
        - opened_at
        - closed_at
        - legs
      properties:
        position_id:
          type: string
          format: uuid
        asset:
          type: string
        status:
          $ref: '#/components/schemas/PositionStatus'
        opened_at:
          type: string
          format: date-time
        closed_at:
          type:
            - string
            - 'null'
          format: date-time
        legs:
          type: array
          items:
            $ref: '#/components/schemas/PositionLegSummary'
        performance:
          $ref: '#/components/schemas/EmbeddedPositionPerformance'
    ValidationError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - VALIDATION_ERROR
        message:
          type: string
      example:
        code: VALIDATION_ERROR
        message: Invalid parameter
    UnauthorizedError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - UNAUTHORIZED
        message:
          type: string
      example:
        code: UNAUTHORIZED
        message: Valid API key required
    ForbiddenError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - FORBIDDEN
        message:
          type: string
      example:
        code: FORBIDDEN
        message: API key does not grant the required scope
    NotFoundError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - NOT_FOUND
        message:
          type: string
      example:
        code: NOT_FOUND
        message: Funding market not found
    PositionStatus:
      type: string
      enum:
        - open
        - closed
    PositionLegSummary:
      type: object
      additionalProperties: false
      required:
        - side
        - market_id
        - exchange
        - symbol
        - leverage
        - quantity
        - open_price
        - mark_price
        - mark_price_updated_at
      properties:
        side:
          type: string
          enum:
            - long
            - short
        market_id:
          type:
            - integer
            - 'null'
        exchange:
          type: string
        symbol:
          type: string
        leverage:
          type:
            - number
            - 'null'
        quantity:
          type: number
          description: Current quantity after size adjustments.
        open_price:
          type:
            - number
            - 'null'
        mark_price:
          type:
            - number
            - 'null'
          description: Latest available mark price for an open position.
        mark_price_updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Time the mark price was last updated.
    EmbeddedPositionPerformance:
      type: object
      additionalProperties: false
      required:
        - funding_pnl
        - fees
        - spread_pnl
        - net_pnl
        - duration_days
        - apr
        - calculated_at
      properties:
        funding_pnl:
          type: number
          description: Funding PnL in USD.
        fees:
          type: object
          additionalProperties: false
          required:
            - paid
            - estimated_exit
          properties:
            paid:
              type: number
              description: Fees already paid in USD.
            estimated_exit:
              type: number
              description: Estimated fee in USD for exiting the active quantity.
        spread_pnl:
          type: object
          additionalProperties: false
          required:
            - realized
            - unrealized
          properties:
            realized:
              type: number
              description: Realized spread PnL in USD.
            unrealized:
              type: number
              description: Estimated spread PnL in USD for the active quantity.
        net_pnl:
          type:
            - number
            - 'null'
          description: >-
            Funding plus realized and estimated spread PnL, minus paid and
            estimated exit fees, in USD. Null when required inputs are
            unavailable.
        duration_days:
          type: number
          description: Position duration in days.
        apr:
          type:
            - number
            - 'null'
          description: Annualized return in percent.
        calculated_at:
          type: string
          format: date-time
          description: Time the values were calculated.
  responses:
    ValidationFailed:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    Unauthorized:
      description: Missing or invalid API key.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          example: Bearer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    Forbidden:
      description: The API key does not grant the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
    ResourceNotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    RateLimited:
      description: Rate limit exceeded.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Personal API key created at bendbasis.com/account/api-keys.

````