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

# Get Position Batch Lookup

> Returns positions for arbitrary wallet and token pairs in a single request. Submit `{ wallet, token }` objects; unmatched pairs come back in `notFound`. Max 200 pairs.

## SDK Example

<CodeGroup>
  ```typescript SDK
  import { Client } from '@solana-tracker/data-api';

  const client = new Client({ apiKey: 'YOUR_API_KEY' });

  const data = await client.batchPnlV2PositionPairs([{ wallet: 'FbMxP3GVq8TQ36nbYgx4NP9iygMpwAwFWJwW81ioCiSF', token: '6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN' }]);

  ```
</CodeGroup>


## OpenAPI

````yaml /data-api/pnl-v2/openapi.json post /v2/pnl/positions/batch
openapi: 3.1.0
info:
  title: SolanaTracker PnL V2 API
  description: >-
    Profit-and-loss tracking for Solana wallets. Provides wallet PnL summaries,
    token-level positions, leaderboards, KOL rankings, risk analysis, and
    historical performance data. All monetary values are in USD. All timestamps
    are Unix milliseconds unless noted otherwise.
  version: 2.0.0
servers:
  - url: https://data.solanatracker.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Leaderboard
    description: Top traders, whales, and KOL rankings
  - name: Token
    description: Per-token trader and holder data
  - name: Wallet
    description: Wallet-level PnL, positions, history, and analysis
  - name: Batch
    description: Bulk wallet summaries and position lookups
paths:
  /v2/pnl/positions/batch:
    post:
      tags:
        - Batch
      summary: Get Position Batch Lookup
      description: >-
        Returns positions for arbitrary wallet and token pairs in a single
        request. Submit `{ wallet, token }` objects; unmatched pairs come back
        in `notFound`. Max 200 pairs.
      operationId: batchPositionPairs
      parameters:
        - $ref: '#/components/parameters/pnlMode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pairs
              properties:
                pairs:
                  type: array
                  description: Array of {wallet, token} objects. Max 200.
                  maxItems: 200
                  items:
                    type: object
                    required:
                      - wallet
                      - token
                    properties:
                      wallet:
                        type: string
                        description: Base58 wallet address
                      token:
                        type: string
                        description: Base58 token mint address
                  example:
                    - wallet: CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o
                      token: 38PgzpJYu2HkiYvV8qePFakB8tuobPdGm2FFEn7Dpump
                    - wallet: CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o
                      token: 84cAEWqiDsV5xXh6CB69Hi3HcnumBbdjH4THfyorpump
      responses:
        '200':
          description: Positions found. Pairs with no matching record appear in `notFound`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pnlMode:
                    type: string
                    enum:
                      - strict
                      - adjusted
                      - raw
                  count:
                    type: integer
                    description: Number of positions returned
                  positions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PositionWithWallet'
                  notFound:
                    type: array
                    items:
                      type: object
                      properties:
                        wallet:
                          type: string
                        token:
                          type: string
                    description: Pairs with no matching position record
                  invalid:
                    type: array
                    items:
                      type: object
                    description: Pairs that failed Base58 validation. Omitted when empty.
              example:
                pnlMode: strict
                count: 3
                positions:
                  - wallet: CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o
                    identity:
                      name: Cented
                      twitter: '@Cented7'
                      avatar: >-
                        https://kol-avatar.solanatracker.io/CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o
                      platforms:
                        - axiom
                        - bloom
                      type: kol
                      tags:
                        - kol
                        - axiom
                        - bloom
                    token: 38PgzpJYu2HkiYvV8qePFakB8tuobPdGm2FFEn7Dpump
                    pnl:
                      realized: 88872.66
                      unrealized: 0
                      total: 88872.66
                    invested: 3071.27
                    proceeds: 91943.94
                    roi: 2893.67
                    current:
                      balance: 0
                      costBasis: 0
                      value: 0
                      price: 0.001572798005924808
                      avgCost: 0
                    volume:
                      tokensBought: 46026806.173715
                      tokensSold: 46026806.173715
                      buyUsd: 3071.27
                      sellUsd: 91943.94
                    averages:
                      buy: 341.25
                      sell: 1242.49
                    counts:
                      buys: 9
                      sells: 74
                      total: 83
                    timing:
                      firstBuy: 1746044721229
                      lastBuy: 1772031549416
                      firstSell: 1746044751527
                      lastSell: 1772032040873
                      firstTrade: 1746044721229
                      lastTrade: 1772032040873
                      holdTimeSecs: 25987320
                    meta:
                      symbol: gork
                      name: New XAI gork
                      image: >-
                        https://image.solanatracker.io/proxy?url=https%3A%2F%2Fipfs-forward.solanatracker.io%2Fipfs%2FQmXkHvTBRFMyY5ozYHXcF7JHqqLBTorca3dXAdF3ooD5e3
                      decimals: 6
                      price: 0.001572798005924808
                      snapshotPrice: 0.001666646257827002
                      marketCap: 1572419.01
                      liquidity: 381495.96
                      primaryMarket: pumpfun-amm
                  - wallet: CyaE1VxvBrahnPWkqm5VsdCvyS2QmNht2UFrKJHga54o
                    token: 84cAEWqiDsV5xXh6CB69Hi3HcnumBbdjH4THfyorpump
                    pnl:
                      realized: 50791.19
                      unrealized: 0
                      total: 50791.19
                    invested: 2621.72
                    proceeds: 53412.92
                    roi: 1937.32
                    current:
                      balance: 0
                      costBasis: 0
                      value: 0
                      price: 0.000015786816405367
                      avgCost: 0
                    volume:
                      tokensBought: 96296057.47450998
                      tokensSold: 96296057.47451006
                      buyUsd: 2621.72
                      sellUsd: 53412.92
                    averages:
                      buy: 70.86
                      sell: 346.84
                    counts:
                      buys: 37
                      sells: 154
                      total: 191
                    timing:
                      firstBuy: 1774277622281
                      lastBuy: 1774294723039
                      firstSell: 1774277870173
                      lastSell: 1774296331666
                      firstTrade: 1774277622281
                      lastTrade: 1774296331666
                      holdTimeSecs: 18709
                    meta:
                      symbol: '7'
                      name: The 7 Wanderers
                      image: >-
                        https://image.solanatracker.io/proxy?url=https%3A%2F%2Fedge.uxento.io%2Fimage%2FBxu1Dr8rLNBDyEutHRapKLdquDLeZkn8zkiUn9Avpump
                      decimals: 6
                      price: 0.000015786816405367
                      snapshotPrice: 0.000022584238960459607
                      marketCap: 15781.28
                      liquidity: 13952.21
                      primaryMarket: pumpfun-amm
                notFound: []
        '400':
          description: Missing or entirely invalid pairs array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: >
            import { Client } from '@solana-tracker/data-api';


            const client = new Client({ apiKey: 'YOUR_API_KEY' });


            const data = await client.batchPnlV2PositionPairs([{ wallet:
            'FbMxP3GVq8TQ36nbYgx4NP9iygMpwAwFWJwW81ioCiSF', token:
            '6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN' }]);
      x-code-samples:
        - lang: typescript
          label: SDK
          source: >
            import { Client } from '@solana-tracker/data-api';


            const client = new Client({ apiKey: 'YOUR_API_KEY' });


            const data = await client.batchPnlV2PositionPairs([{ wallet:
            'FbMxP3GVq8TQ36nbYgx4NP9iygMpwAwFWJwW81ioCiSF', token:
            '6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN' }]);
components:
  parameters:
    pnlMode:
      name: pnlMode
      in: query
      description: >-
        How to treat positions flagged by the invalid PnL heuristic. `strict`
        zeros them out, `adjusted` caps them to a cost-basis-aware value, and
        `raw` leaves realized PnL untouched. Aliases `pnl_mode` and `mode` are
        also accepted by the API.
      schema:
        type: string
        enum:
          - strict
          - adjusted
          - raw
        default: strict
  schemas:
    PositionWithWallet:
      description: >-
        Position with an additional `wallet` field identifying which wallet the
        position belongs to.
      allOf:
        - type: object
          properties:
            wallet:
              type: string
              description: Wallet address
            identity:
              $ref: '#/components/schemas/Identity'
        - $ref: '#/components/schemas/Position'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
      required:
        - error
    Identity:
      type: object
      description: >-
        Unified wallet identity. Only fields with known values are returned; a
        wallet can carry multiple tags at once.
      properties:
        name:
          type:
            - string
            - 'null'
          description: Display name, if known.
        twitter:
          type:
            - string
            - 'null'
          description: Twitter/X handle, if known.
        avatar:
          type:
            - string
            - 'null'
          format: uri
          description: Avatar image URL.
        type:
          type:
            - string
            - 'null'
          description: >-
            Primary label for single-badge UIs, such as `kol`, `developer`,
            `pool`, `bot`, `hacker`, `spam_dusting`, `exchange`, or a platform
            tag.
        tags:
          type: array
          items:
            type: string
          description: >-
            All resolved labels for the wallet, including KOL, platform, pool,
            developer, bot, arbitrage, hacker, spam-dusting, or exchange tags.
        platforms:
          type: array
          items:
            type: string
          description: >-
            Normalized trading frontend tags such as `axiom`, `bloom`, or
            `photon`. Query filters also accept `axiom-flash`, which is
            normalized to `axiom` in identity responses.
        bot:
          type: object
          properties:
            name:
              type:
                - string
                - 'null'
            avatar:
              type:
                - string
                - 'null'
              format: uri
        pool:
          type: object
          properties:
            program:
              type:
                - string
                - 'null'
            poolAddress:
              type:
                - string
                - 'null'
        developer:
          type: object
          properties:
            token:
              type:
                - string
                - 'null'
            via:
              type: array
              items:
                type: string
            pools:
              type: array
              items:
                type: string
            creationTx:
              type:
                - string
                - 'null'
            createdAt:
              type:
                - integer
                - 'null'
              description: Unix timestamp in seconds.
        hacker:
          type: object
          description: Curated exploit/scam wallet label, when known.
          properties:
            label:
              type:
                - string
                - 'null'
        spamDusting:
          type: object
          description: Curated spam-dusting wallet label, when known.
          properties:
            label:
              type:
                - string
                - 'null'
        exchange:
          type: object
          description: Known centralized exchange hot wallet label, when known.
          properties:
            name:
              type:
                - string
                - 'null'
    Position:
      type: object
      description: A single token position for a wallet.
      properties:
        token:
          type: string
          description: Token mint address (base58).
        pnl:
          $ref: '#/components/schemas/PnlBlock'
        invested:
          type:
            - number
            - 'null'
          description: Total cost basis (USD spent buying this token).
        proceeds:
          type:
            - number
            - 'null'
          description: Total USD received from sales of this token.
        roi:
          type:
            - number
            - 'null'
          description: Return on investment percentage.
        current:
          type: object
          properties:
            balance:
              type:
                - number
                - 'null'
              description: Current token balance (native units).
            costBasis:
              type:
                - number
                - 'null'
              description: Cost basis of remaining held tokens.
            value:
              type:
                - number
                - 'null'
              description: Current USD value of held tokens.
            price:
              type:
                - number
                - 'null'
              description: Current token price in USD.
            avgCost:
              type:
                - number
                - 'null'
              description: Average cost per token in USD.
        volume:
          type: object
          properties:
            tokensBought:
              type:
                - number
                - 'null'
              description: Total tokens purchased (native units).
            tokensSold:
              type:
                - number
                - 'null'
              description: Total tokens sold (native units).
            buyUsd:
              type:
                - number
                - 'null'
              description: Total USD spent on buys.
            sellUsd:
              type:
                - number
                - 'null'
              description: Total USD received from sells.
        averages:
          type: object
          properties:
            buy:
              type:
                - number
                - 'null'
              description: Average buy size in USD.
            sell:
              type:
                - number
                - 'null'
              description: Average sell size in USD.
        counts:
          type: object
          properties:
            buys:
              type: integer
            sells:
              type: integer
            total:
              type: integer
              description: Total transactions (buys + sells).
        timing:
          type: object
          properties:
            firstBuy:
              type:
                - integer
                - 'null'
              description: Unix ms.
            lastBuy:
              type:
                - integer
                - 'null'
              description: Unix ms.
            firstSell:
              type:
                - integer
                - 'null'
              description: Unix ms.
            lastSell:
              type:
                - integer
                - 'null'
              description: Unix ms.
            firstTrade:
              type:
                - integer
                - 'null'
              description: Unix ms.
            lastTrade:
              type:
                - integer
                - 'null'
              description: Unix ms.
            holdTimeSecs:
              type:
                - integer
                - 'null'
              description: How long the position has been (or was) held, in seconds.
        meta:
          $ref: '#/components/schemas/TokenMeta'
        portfolioPercent:
          type:
            - number
            - 'null'
          description: >-
            This position's value as a percentage of the wallet's total holdings
            value. Only present on the positions endpoint.
    PnlBlock:
      type: object
      description: Realized, unrealized, and total profit/loss in USD.
      properties:
        realized:
          type:
            - number
            - 'null'
          description: Profit/loss from closed trades (tokens fully or partially sold).
        realizedRaw:
          type:
            - number
            - 'null'
          description: >-
            Unfiltered realized PnL before `pnlMode` adjustments. Present on
            position rows and leaderboard period stats when available.
        unrealized:
          type:
            - number
            - 'null'
          description: >-
            Paper profit/loss on tokens still held, based on current market
            price.
        total:
          type:
            - number
            - 'null'
          description: Sum of realized + unrealized PnL.
    TokenMeta:
      type: object
      description: Basic token metadata and current market data.
      properties:
        symbol:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        decimals:
          type:
            - integer
            - 'null'
        price:
          type:
            - number
            - 'null'
          description: Current price in USD.
        liquidity:
          type:
            - number
            - 'null'
          description: Current liquidity in USD.
        marketCap:
          type:
            - number
            - 'null'
          description: Current market cap in USD.
        primaryMarket:
          type:
            - string
            - 'null'
          description: Primary DEX where this token trades (e.g. Raydium, Orca).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key for authentication

````