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

# Get Positions



## OpenAPI

````yaml GET /api/v2/portfolio/positions
openapi: 3.0.3
info:
  description: Multi-chain DEX trading API for developers
  license:
    name: ''
  title: Shuriken API v2
  version: 2.0.0
servers:
  - url: https://api.shuriken.trade
security: []
tags:
  - description: SplitNOW cross-chain split plan + execute
    name: V2 Splits
  - description: Wallet archive lifecycle (archive / unarchive / bulk-archive)
    name: Wallets
  - description: Token discovery, metadata, and pricing
    name: V2 Tokens
  - description: Quote and execute swaps
    name: V2 Swap
  - description: Limit orders and stop-loss
    name: V2 Trigger
  - description: Managed-agent invocation
    name: V2 Agents
  - description: Portfolio positions and PnL
    name: V2 Portfolio
  - description: User account management
    name: V2 Account
  - description: WebSocket stream discovery, session bootstrap, and channel authorization
    name: V2 WebSocket
  - description: Perpetual trading on Hyperliquid
    name: V2 Perps
  - description: Agent-proposed trade suggestions
    name: V2 Suggestions
paths:
  /api/v2/portfolio/positions:
    get:
      tags:
        - V2 Portfolio
      summary: GET /api/v2/portfolio/positions — Get user positions with PnL
      operationId: get_portfolio_positions
      parameters:
        - description: Filter by chain
          in: query
          name: chain
          required: false
          schema:
            type: string
        - description: Filter by position status
          in: query
          name: status
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_PositionsResponse'
          description: Portfolio positions
      security:
        - bearer_auth: []
components:
  schemas:
    ApiResponse_PositionsResponse:
      description: V2 success response envelope
      properties:
        data:
          description: Positions response with aggregated data
          example:
            positionCount: 1
            positions:
              - balanceUsd: 1000
                boughtUsd: 1500
                latestBalanceRaw: '1000000000'
                latestTokenUsdPrice: 1
                network: sol
                realisedPnlPct: -33.33
                soldUsd: 500
                tokenAddress: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
                tokenDecimal: 6
                totalPnlPct: 0
                walletAddress: CuieVDEDtLo7FypA9SbLM9saXFdb1dsshEkyErMqkRQq
            totalValueUsd: 1000
          properties:
            positionCount:
              description: Number of positions
              minimum: 0
              type: integer
            positions:
              description: List of token positions
              items:
                $ref: '#/components/schemas/PositionInfo'
              type: array
            totalValueUsd:
              description: Total portfolio value in USD
              format: double
              type: number
          required:
            - positions
            - totalValueUsd
            - positionCount
          type: object
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          nullable: true
        requestId:
          type: string
      required:
        - data
        - requestId
      type: object
    PositionInfo:
      description: Token position with PnL data
      example:
        balanceNative: 10
        balanceUsd: 1000
        boughtNative: 15
        boughtUsd: 1500
        buyCount: 3
        latestBalanceRaw: '1000000000'
        latestTokenUsdPrice: 1
        network: sol
        realisedPnlPct: -33.33
        sellCount: 1
        soldNative: 5
        soldUsd: 500
        tokenAddress: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
        tokenDecimal: 6
        totalPnlPct: 0
        walletAddress: CuieVDEDtLo7FypA9SbLM9saXFdb1dsshEkyErMqkRQq
      properties:
        balanceNative:
          description: Current position value in native currency
          format: double
          type: number
        balanceUsd:
          description: Current position value in USD
          format: double
          type: number
        boughtNative:
          description: Total native currency spent buying (e.g., SOL, BNB)
          format: double
          type: number
        boughtUsd:
          description: Total USD spent buying this token
          format: double
          type: number
        buyCount:
          description: Number of buy transactions
          format: int64
          minimum: 0
          type: integer
        latestBalanceRaw:
          description: Raw token balance (before decimal adjustment)
          type: string
        latestTokenUsdPrice:
          description: Current USD price of the token
          format: double
          type: number
        network:
          description: Network/chain identifier (e.g., "sol", "bsc", "monad")
          type: string
        realisedPnlPct:
          description: Realized PnL percentage (from closed positions)
          format: double
          type: number
        sellCount:
          description: Number of sell transactions
          format: int64
          minimum: 0
          type: integer
        soldNative:
          description: Total native currency received from selling
          format: double
          type: number
        soldUsd:
          description: Total USD received from selling this token
          format: double
          type: number
        tokenAddress:
          description: Token contract address
          type: string
        tokenDecimal:
          description: Token decimal places
          format: int32
          minimum: 0
          type: integer
        totalPnlPct:
          description: Total PnL percentage (realized + unrealized)
          format: double
          type: number
        walletAddress:
          description: Wallet address holding this position
          type: string
      required:
        - walletAddress
        - tokenAddress
        - latestBalanceRaw
        - latestTokenUsdPrice
        - tokenDecimal
        - boughtUsd
        - soldUsd
        - boughtNative
        - soldNative
        - buyCount
        - sellCount
        - balanceUsd
        - balanceNative
        - realisedPnlPct
        - totalPnlPct
        - network
      type: object
    PaginationInfo:
      description: Page-based pagination info (per RFC)
      properties:
        hasMore:
          type: boolean
        limit:
          format: int32
          minimum: 0
          type: integer
        page:
          format: int32
          minimum: 0
          type: integer
        total:
          format: int32
          minimum: 0
          nullable: true
          type: integer
      required:
        - page
        - limit
        - hasMore
      type: object
  securitySchemes:
    bearer_auth:
      bearerFormat: JWT or sk_{keyId}_{secret}
      description: >-
        Use `Authorization: Bearer <jwt>` for user auth or `Authorization:
        Bearer sk_{keyId}_{secret}` for API key auth.
      scheme: bearer
      type: http

````