Dialect Positions API

openapi: 3.1.0
info:
  title: Dialect Alerts V2 Blink Positions API
  description: Dialect Alerts API supporting both subscriber and app authentication methods.
  version: 2.2.0-beta
servers:
- url: https://alerts-api.dial.to
  description: Dialect Production
- url: https://alerts.dialectapi.to
  description: Dialect Production
security: []
tags:
- name: Positions
paths:
  /v0/positions/owners:
    get:
      operationId: markets-positions.positionsV0Api.positionsByOwners
      summary: List all market positions by wallet address
      description: 'Supported providers & markets: Kamino Lending, Lulo.'
      tags:
      - Positions
      parameters:
      - name: walletAddresses
        in: query
        required: true
        schema:
          type: string
          description: Comma separated list of owner addresses. Currently only supports one address.
          default: 6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176
        allowEmptyValue: true
        allowReserved: true
      - name: bundleIds
        in: query
        required: false
        schema:
          type: string
          description: Comma separated list of bundle IDs. Currently only supports one bundle ID.
        allowEmptyValue: true
        allowReserved: true
      - name: type
        in: query
        required: false
        schema:
          type: string
          description: Comma separated list of position types (`lending`, `yield`, `loop`, `reward`, `prediction`). Currently only supports one position type. If no position type is specified, all position types are returned.
        allowEmptyValue: true
        allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  positions:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/LendingPositionWithMarket'
                      - $ref: '#/components/schemas/YieldPositionWithMarket'
                      - type: object
                        properties:
                          id:
                            type: string
                          type:
                            const: loop
                          marketId:
                            type: string
                          ownerAddress:
                            type: string
                          websiteUrl:
                            type: string
                            format: uri
                          bundleId:
                            type: string
                            description: Identifier for positions bundled into one logical structure, such as position or market
                          additionalData:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                          amount:
                            type: number
                            description: Current networth of the position in borrowed token value
                          amountUsd:
                            type: number
                            description: Current networth of the position in USD
                          amountTokenA:
                            type: number
                            description: Supplied token amount
                          amountTokenB:
                            type: number
                            description: Borrowed token amount
                          amountTokenAUsd:
                            type: number
                          amountTokenBUsd:
                            type: number
                          ltv:
                            type: number
                            minimum: 0
                            maximum: 1
                            description: Current Loan-to-Value before either full/partial liquidation commences (depending on the provider), expressed as a percentage ratio of deposited value
                          liquidationPrice:
                            type: number
                            description: Deposited token price expressed in borrowed token units at which the position becomes liquidatable, fully or partially.
                          leverage:
                            type: number
                            minimum: 0
                            description: Current leverage of the position, expressed as a multiplier
                          market:
                            $ref: '#/components/schemas/LoopMarket'
                        required:
                        - id
                        - type
                        - marketId
                        - ownerAddress
                        - amount
                        - amountTokenA
                        - amountTokenB
                        - market
                      - type: object
                        properties:
                          id:
                            type: string
                          type:
                            const: reward
                          ownerAddress:
                            type: string
                          bundleId:
                            type: string
                            description: Identifier for positions bundled into one logical structure, such as position or market
                          token:
                            type: object
                            properties:
                              address:
                                type: string
                              symbol:
                                type: string
                              decimals:
                                type: number
                              icon:
                                anyOf:
                                - type: string
                                - type: 'null'
                            required:
                            - address
                            - symbol
                            - decimals
                            - icon
                          marketId:
                            type: string
                          position:
                            type: object
                            properties:
                              id:
                                type: string
                              type:
                                enum:
                                - lending
                                - yield
                                - loop
                                - reward
                                - prediction
                                type: string
                              side:
                                enum:
                                - deposit
                                - borrow
                                type: string
                            required:
                            - type
                          additionalData:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                          amount:
                            type: number
                          amountUsd:
                            type: number
                          market:
                            anyOf:
                            - $ref: '#/components/schemas/LendingMarket'
                            - $ref: '#/components/schemas/YieldMarket'
                            - $ref: '#/components/schemas/LoopMarket'
                            - $ref: '#/components/schemas/PerpetualMarket'
                        required:
                        - id
                        - type
                        - ownerAddress
                        - token
                        - marketId
                        - amount
                      - type: object
                        properties:
                          id:
                            type: string
                          type:
                            const: prediction
                          ownerAddress:
                            type: string
                          bundleId:
                            type: string
                            description: Identifier for positions bundled into one logical structure, such as position or market
                          marketId:
                            type: string
                          token:
                            type: object
                            properties:
                              address:
                                type: string
                              symbol:
                                type: string
                              decimals:
                                type: number
                              icon:
                                anyOf:
                                - type: string
                                - type: 'null'
                              name:
                                anyOf:
                                - type: string
                                - type: 'null'
                            required:
                            - address
                            - symbol
                            - decimals
                            - icon
                            - name
                          side:
                            enum:
                            - 'yes'
                            - 'no'
                            type: string
                          additionalData:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                          amount:
                            type: number
                          amountUsd:
                            type: number
                          costBasisTotal:
                            type: number
                          costBasisAvg:
                            type: number
                          pnl:
                            type: object
                            properties:
                              total:
                                type: number
                              realized:
                                type: number
                              unrealized:
                                type: number
                              realizedLifetime:
                                type: number
                              totalLifetime:
                                type: number
                              unrealizedPct:
                                type: number
                              capital:
                                type: object
                                properties:
                                  invested:
                                    type: number
                                    description: Sum of all buy costs within the active position
                                  investedLifetime:
                                    type: number
                                    description: Sum of all buy costs across all re-entries for this market
                                  netFlow:
                                    type: number
                                    description: 'Net capital flow within the active position: sell proceeds minus buy costs. Negative means own capital is still locked in the position; positive means the initial investment has been fully recouped with additional realized returns'
                                  netFlowLifetime:
                                    type: number
                                    description: 'Net capital flow across all re-entries for this market: sell proceeds minus buy costs. Negative means own capital is still locked in the position; positive means the initial investment has been fully recouped with additional realized returns'
                                required:
                                - invested
                                - investedLifetime
                                - netFlow
                                - netFlowLifetime
                            required:
                            - total
                            - realized
                            - unrealized
                            - realizedLifetime
                            - totalLifetime
                            - unrealizedPct
                          market:
                            type: object
                            properties:
                              id:
                                type: string
                              type:
                                const: prediction
                              provider:
                                type: object
                                properties:
                                  id:
                                    enum:
                                    - kamino
                                    - lulo
                                    - marginfi
                                    - jupiter
                                    - defituna
                                    - carrot
                                    - dflow
                                  name:
                                    type: string
                                  icon:
                                    type: string
                                required:
                                - id
                                - name
                                - icon
                              websiteUrl:
                                type: string
                                format: uri
                              bundleId:
                                type: string
                                description: Identifier for positions bundled into one logical structure, such as position or market
                              title:
                                type: string
                              subtitle:
                                type: string
                              status:
                                enum:
                                - open
                                - closed
                                - settled
                                type: string
                              result:
                                type: string
                              volume:
                                type: number
                              openInterest:
                                type: number
                              yesBid:
                                type: number
                              noBid:
                                type: number
                              yesAsk:
                                type: number
                              noAsk:
                                type: number
                              openTime:
                                type: number
                              closeTime:
                                type: number
                              expirationTime:
                                type: number
                              yesToken:
                                type: object
                                properties:
                                  address:
                                    type: string
                                  symbol:
                                    type: string
                                  decimals:
                                    type: number
                                  icon:
                                    anyOf:
                                    - type: string
                                    - type: 'null'
                                  name:
                                    anyOf:
                                    - type: string
                                    - type: 'null'
                                required:
                                - address
                                - symbol
                                - decimals
                                - icon
                                - name
                              noToken:
                                type: object
                                properties:
                                  address:
                                    type: string
                                  symbol:
                                    type: string
                                  decimals:
                                    type: number
                                  icon:
                                    anyOf:
                                    - type: string
                                    - type: 'null'
                                  name:
                                    anyOf:
                                    - type: string
                                    - type: 'null'
                                required:
                                - address
                                - symbol
                                - decimals
                                - icon
                                - name
                              additionalData:
                                type: object
                                propertyNames:
                                  type: string
                                additionalProperties: {}
                            required:
                            - id
                            - type
                            - provider
                            - title
                            - status
                        required:
                        - id
                        - type
                        - ownerAddress
                        - marketId
                        - side
                        - amount
                        - market
                required:
                - positions
  /v0/positions/history:
    get:
      operationId: markets-positions.positionsV0Api.positionsHistory
      summary: Get historical position snapshots
      description: Fetch position snapshots within a time range for a wallet address. Optionally interpolate using Birdeye price data.
      tags:
      - Positions
      parameters:
      - name: walletAddress
        in: query
        required: true
        schema:
          type: string
          description: Wallet address to fetch position history for
          default: 6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176
        allowEmptyValue: true
        allowReserved: true
      - name: startTime
        in: query
        required: true
        schema:
          type: string
          format: date-time
          x-native-type: date
          description: Start time of the snapshot. Date or datetime in RFC 3339 format
          default: '2026-01-01T00:00:00Z'
        allowEmptyValue: true
        allowReserved: true
      - name: endTime
        in: query
        required: false
        schema:
          type: string
          format: date-time
          x-native-type: date
          description: End time of the snapshot. Date or datetime in RFC 3339 format. Defaults to current time if not provided
          default: '2026-01-31T23:59:59Z'
        allowEmptyValue: true
        allowReserved: true
      - name: positionIds
        in: query
        required: false
        schema:
          type: string
          description: Comma separated list of position IDs.
        allowEmptyValue: true
        allowReserved: true
      - name: resolution
        in: query
        required: false
        schema:
          enum:
          - 1m
          - 5m
          - 1h
          - 1d
          type: string
          description: Time resolution for aggregating snapshots
          default: 1h
        allowEmptyValue: true
        allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      positions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            providerId:
                              enum:
                              - kamino
                              - lulo
                              - marginfi
                              - jupiter
                              - defituna
                              - carrot
                              - dflow
                            type:
                              enum:
                              - lending
                              - yield
                              - loop
                              - reward
                              - prediction
                              type: string
                            marketId:
                              type: string
                            history:
                              type: array
                              items:
                                type: object
                                properties:
                                  timestamp:
                                    type: string
                                    format: date-time
                                    x-native-type: date
                                  amount:
                                    type: number
                                  amountUsd:
                                    anyOf:
                                    - type: number
                                    - type: 'null'
                                  amountTokenA:
                                    anyOf:
                                    - type: number
                                    - type: 'null'
                                  amountTokenAUsd:
                                    anyOf:
                                    - type: number
                                    - type: 'null'
                                  amountTokenB:
                                    anyOf:
                                    - type: number
                                    - type: 'null'
                                  amountTokenBUsd:
                                    anyOf:
                                    - type: number
                                    - type: 'null'
                                required:
                                - timestamp
                                - amount
                                - amountUsd
                          required:
                          - id
                          - providerId
                          - type
                          - marketId
                          - history
                    required:
                    - positions
                required:
                - data
  /v0/positions/pnl:
    get:
      operationId: markets-positions.positionsV0Api.positionsPnl
      summary: Get PnL data for wallet positions
      description: Computes realized and unrealized PnL for all pnl-able positions (currently DFlow prediction only), including closed positions.
      tags:
      - Positions
      parameters:
      - name: walletAddresses
        in: query
        required: true
        schema:
          type: string
          description: Comma separated list of owner addresses. Currently only supports one address.
          default: 6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176
        allowEmptyValue: true
        allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  currency:
                    const: USD
                    description: Currency of the PnL values
                  total:
                    type: number
                    description: Total PnL for all positions within the current session, unrealized + realized PnL
                  realized:
                    type: number
                    description: Realized PnL for all positions within the current session
                  unrealized:
                    type: number
                    description: Unrealized PnL for all positions. If position is closed, this field will be empty.
                  realizedLifetime:
                    type: number
                    description: Realized PnL for all positions across all sessions
                  totalLifetime:
                    type: number
                    description: Total PnL for all positions across all sessions, unrealized + realized lifetime PnL
                  positions:
                    type: array
                    items:
                      type: object
                      properties:
                        positionId:
                          type: string
                        marketId:
                          type: string
                        ownerAddress:
                          type: string
                        total:
                          type: number
                          description: Total PnL for the active position, unrealized + realized PnL
                        realized:
                          type: number
                          description: Realized PnL for the active position
                        unrealized:
                          type: number
                          description: Unrealized PnL for the active position. If position is closed, this field will be undefined.
                        realizedLifetime:
                          type: number
                          description: Realized PnL for positions across all re-entries for this market
                        totalLifetime:
                          type: number
                          description: Total PnL for positions across all re-entries for this market, unrealized + realized lifetime PnL
                        capital:
                          type: object
                          properties:
                            invested:
                              type: number
                              description: Sum of all buy costs within the active position
                            investedLifetime:
                              type: number
                              description: Sum of all buy costs across all re-entries for this market
                            netFlow:
                              type: number
                              description: 'Net capital flow within the active position: sell proceeds minus buy costs. Negative means own capital is still locked in the position; positive means the initial investment has been fully recouped with additional realized returns'
                            netFlowLifetime:
                              type: number
                              description: 'Net capital flow across all re-entries for this market: sell proceeds minus buy costs. Negative means own capital is still locked in the position; positive means the initial investment has been fully recouped with additional realized returns'
                          required:
                          - invested
                          - investedLifetime
                          - netFlow
                          - netFlowLifetime
                      required:
                      - positionId
                      - marketId
                      - ownerAddress
                      - total
                      - realized
                      - realizedLifetime
                      - totalLifetime
                    description: List of positions that contribute to PnL calculations. Each position is a separate entry.
                required:
                - currency
                - total
                - realized
                - unrealized
                - realizedLifetime
                - totalLifetime
                - positions
components:
  schemas:
    LendingMarket:
      type: object
      properties:
        id:
          type: string
        type:
          const: lending
        productName:
          type: string
        provider:
          type: object
          properties:
            id:
              enum:
              - kamino
              - lulo
              - marginfi
              - jupiter
              - defituna
              - carrot
              - dflow
            name:
              type: string
            icon:
              type: string
          required:
          - id
          - name
          - icon
        token:
          type: object
          properties:
            address:
              type: string
            symbol:
              type: string
            decimals:
              type: number
            icon:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - address
          - symbol
          - decimals
          - icon
        borrowToken:
          type: object
          properties:
            address:
              type: string
            symbol:
              type: string
            decimals:
              type: number
            icon:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - address
          - symbol
          - decimals
          - icon
        websiteUrl:
          type: string
          format: uri
        depositApy:
          type: number
          description: Total percentage ratio APY **including** rewards
        baseDepositApy:
          type: number
          description: APY percentage ratio excluding rewards
        baseDepositApy30d:
          type: number
          description: 30-day average APY percentage ratio excluding rewards
        baseDepositApy90d:
          type: number
          description: 90-day average APY percentage ratio excluding rewards
        baseDepositApy180d:
          type: number
          description: 180-day average APY percentage ratio excluding rewards
        borrowApy:
          type: number
          description: Total percentage ratio APY **including** rewards
        baseBorrowApy:
          type: number
          description: APY percentage ratio excluding rewards
        baseBorrowApy30d:
          type: number
          description: 30-day average APY percentage ratio excluding rewards
        baseBorrowApy90d:
          type: number
          description: 90-day average APY percentage ratio excluding rewards
        baseBorrowApy180d:
          type: number
          description: 180-day average APY percentage ratio excluding rewards
        totalDeposit:
          type: number
        totalDepositUsd:
          type: number
        totalBorrow:
          type: number
        totalBorrowUsd:
          type: number
        maxDeposit:
          type: number
        maxBorrow:
          type: number
        rewards:
          type: array
          items:
            anyOf:
            - type: object
              properties:
                type:
                  const: deposit
                apy:
                  type: number
                token:
                  type: object
                  properties:
                    address:
                      type: string
                    symbol:
                      type: string
                    decimals:
                      type: number
                    icon:
                      anyOf:
                      - type: string
                      - type: 'null'
                  required:
                  - address
                  - symbol
                  - decimals
                  - icon
                marketAction:
                  type: string
              required:
              - type
              - apy
              - token
              - marketAction
              title: Deposit Reward
              description: Reward for depositing
            - type: object
              properties:
                type:
                  const: borrow
             

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dialect/refs/heads/main/openapi/dialect-positions-api-openapi.yml