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

# Positions

> Get DeFi positions for a Solana wallet

Retrieve all DeFi positions for a Solana wallet across supported protocols.

## Request

<ParamField query="wallet" type="string" required>
  Solana wallet address in base58 format (32-44 characters).
</ParamField>

<ParamField query="protocols" type="string">
  Comma-separated list of protocol IDs to filter results. If omitted, all protocols are queried.

  **Available protocols:**

  * Lending: `marginfi`, `kamino`, `solend`, `defituna`
  * DEX: `raydium`, `orca`, `meteora`, `hawkfi`, `jupiter`
  * Perpetuals: `drift`, `mango`
  * Liquid Staking: `jito`, `marinade`, `blazestake`, `sanctum`, `solayer`, `fragmetric`, `kyros`
  * Governance: `jupiter-governance`
  * Native: `solana-native-staking`
  * Holdings: `wallet`
</ParamField>

## Response

<ResponseField name="wallet" type="string">
  The queried wallet address.
</ResponseField>

<ResponseField name="fetchedAt" type="string">
  ISO 8601 timestamp of when the data was fetched.
</ResponseField>

<ResponseField name="totalValueUsd" type="number">
  Net portfolio value in USD (deposits - borrows + positions).
</ResponseField>

<ResponseField name="totalDepositedUsd" type="number">
  Total deposited assets in USD.
</ResponseField>

<ResponseField name="totalBorrowedUsd" type="number">
  Total borrowed assets in USD.
</ResponseField>

<ResponseField name="totalRewardsUsd" type="number">
  Total unclaimed rewards in USD.
</ResponseField>

<ResponseField name="protocols" type="array">
  Array of protocol position data.

  <Expandable title="Protocol Object">
    <ResponseField name="protocol.id" type="string">
      Protocol identifier (e.g., `marginfi`, `drift`).
    </ResponseField>

    <ResponseField name="protocol.name" type="string">
      Protocol display name.
    </ResponseField>

    <ResponseField name="protocol.url" type="string">
      Protocol website.
    </ResponseField>

    <ResponseField name="protocol.category" type="string">
      Category: `lending`, `dex`, `perps`, `lst`, `staking`, `native-staking`, or `holdings`.
    </ResponseField>

    <ResponseField name="totalValueUsd" type="number">
      Net value in this protocol.
    </ResponseField>

    <ResponseField name="totalDepositedUsd" type="number">
      Total deposited in this protocol.
    </ResponseField>

    <ResponseField name="totalBorrowedUsd" type="number">
      Total borrowed in this protocol.
    </ResponseField>

    <ResponseField name="totalRewardsUsd" type="number">
      Unclaimed rewards in this protocol.
    </ResponseField>

    <ResponseField name="positions" type="array">
      Array of positions (see Position Object below).
    </ResponseField>
  </Expandable>
</ResponseField>

### Position Object

<ResponseField name="id" type="string">
  Unique position identifier.
</ResponseField>

<ResponseField name="type" type="string">
  Position type: `deposit`, `borrow`, `liquidity`, `stake`, or `perp`.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable position name (e.g., `USDC Deposit`, `SOL/USDC LP`).
</ResponseField>

<ResponseField name="valueUsd" type="number">
  Position value in USD.
</ResponseField>

<ResponseField name="tokens" type="array">
  Tokens in the position.

  <Expandable title="Token Object">
    <ResponseField name="mint" type="string">Token mint address.</ResponseField>
    <ResponseField name="symbol" type="string">Token symbol.</ResponseField>
    <ResponseField name="name" type="string">Token name.</ResponseField>
    <ResponseField name="amount" type="string">Raw amount (string for precision).</ResponseField>
    <ResponseField name="amountUsd" type="number">Value in USD.</ResponseField>
    <ResponseField name="decimals" type="number">Token decimals.</ResponseField>
    <ResponseField name="logoUri" type="string">Token logo URL (optional).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional data depending on position type.

  <Expandable title="Metadata Fields">
    **Lending positions:**
    <ResponseField name="apy" type="number">Annual percentage yield.</ResponseField>
    <ResponseField name="healthFactor" type="number">Account health factor.</ResponseField>
    <ResponseField name="liquidationThreshold" type="number">Liquidation threshold.</ResponseField>

    **DEX positions:**
    <ResponseField name="poolAddress" type="string">Pool address.</ResponseField>
    <ResponseField name="feeTier" type="number">Fee tier percentage.</ResponseField>
    <ResponseField name="inRange" type="boolean">Whether position is in range.</ResponseField>
    <ResponseField name="tickLower" type="number">Lower price bound.</ResponseField>
    <ResponseField name="tickUpper" type="number">Upper price bound.</ResponseField>
    <ResponseField name="unclaimedFees" type="array">Unclaimed trading fees.</ResponseField>

    **Perpetual positions:**
    <ResponseField name="side" type="string">`long` or `short`.</ResponseField>
    <ResponseField name="leverage" type="number">Position leverage.</ResponseField>
    <ResponseField name="entryPrice" type="number">Entry price.</ResponseField>
    <ResponseField name="markPrice" type="number">Current mark price.</ResponseField>
    <ResponseField name="unrealizedPnl" type="number">Unrealized PnL in USD.</ResponseField>
    <ResponseField name="liquidationPrice" type="number">Liquidation price.</ResponseField>

    **Staking positions:**
    <ResponseField name="exchangeRate" type="number">LST to SOL exchange rate.</ResponseField>
    <ResponseField name="pendingUnstake" type="number">Pending unstake amount (if applicable).</ResponseField>

    **Native staking positions:**
    <ResponseField name="stakeAccountAddress" type="string">Stake account address.</ResponseField>
    <ResponseField name="validatorVoteAccount" type="string">Validator vote account.</ResponseField>
    <ResponseField name="validatorCommission" type="number">Validator commission percentage.</ResponseField>
    <ResponseField name="activationState" type="string">`activating`, `active`, `deactivating`, or `inactive`.</ResponseField>
    <ResponseField name="activationEpoch" type="number">Epoch when the stake was activated.</ResponseField>
    <ResponseField name="deactivationEpoch" type="number">Epoch when the stake was deactivated.</ResponseField>
    <ResponseField name="currentEpoch" type="number">Current Solana epoch.</ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Code | Description                   |
| ---- | ----------------------------- |
| 400  | Invalid wallet address format |

```json theme={null}
{
  "error": "Invalid wallet address"
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.nefariouslabs.dev/api/positions?wallet=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  ```

  ```bash cURL (filtered) theme={null}
  curl "https://api.nefariouslabs.dev/api/positions?wallet=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU&protocols=marginfi,drift,jito"
  ```

  ```typescript TypeScript theme={null}
  const wallet = '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU';

  // Get all positions
  const response = await fetch(
    `https://api.nefariouslabs.dev/api/positions?wallet=${wallet}`
  );
  const data = await response.json();

  // Get specific protocols only
  const filtered = await fetch(
    `https://api.nefariouslabs.dev/api/positions?wallet=${wallet}&protocols=marginfi,drift`
  );
  ```

  ```python Python theme={null}
  import requests

  wallet = "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

  # Get all positions
  response = requests.get(
      f"https://api.nefariouslabs.dev/api/positions?wallet={wallet}"
  )
  data = response.json()

  # Get specific protocols only
  response = requests.get(
      f"https://api.nefariouslabs.dev/api/positions?wallet={wallet}&protocols=marginfi,orca"
  )
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "fetchedAt": "2024-01-15T10:30:00.000Z",
    "totalValueUsd": 15420.50,
    "totalDepositedUsd": 12500.00,
    "totalBorrowedUsd": 2100.00,
    "totalRewardsUsd": 45.30,
    "protocols": [
      {
        "protocol": {
          "id": "marginfi",
          "name": "MarginFi",
          "url": "https://app.marginfi.com",
          "category": "lending"
        },
        "totalValueUsd": 8400.00,
        "totalDepositedUsd": 10000.00,
        "totalBorrowedUsd": 1600.00,
        "totalRewardsUsd": 0,
        "positions": [
          {
            "id": "marginfi-deposit-abc123",
            "type": "deposit",
            "name": "USDC Deposit",
            "valueUsd": 5000.00,
            "tokens": [
              {
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "symbol": "USDC",
                "name": "USD Coin",
                "amount": "5000000000",
                "amountUsd": 5000.00,
                "decimals": 6
              }
            ],
            "metadata": {
              "apy": 0.085
            }
          },
          {
            "id": "marginfi-borrow-abc123",
            "type": "borrow",
            "name": "SOL Borrow",
            "valueUsd": 1600.00,
            "tokens": [
              {
                "mint": "So11111111111111111111111111111111111111112",
                "symbol": "SOL",
                "name": "Wrapped SOL",
                "amount": "8000000000",
                "amountUsd": 1600.00,
                "decimals": 9
              }
            ],
            "metadata": {
              "apy": 0.045
            }
          }
        ]
      },
      {
        "protocol": {
          "id": "orca",
          "name": "Orca",
          "url": "https://www.orca.so",
          "category": "dex"
        },
        "totalValueUsd": 3500.00,
        "totalDepositedUsd": 3500.00,
        "totalBorrowedUsd": 0,
        "totalRewardsUsd": 25.50,
        "positions": [
          {
            "id": "orca-whirlpool-def456",
            "type": "liquidity",
            "name": "SOL/USDC LP",
            "valueUsd": 3500.00,
            "tokens": [
              {
                "mint": "So11111111111111111111111111111111111111112",
                "symbol": "SOL",
                "name": "Wrapped SOL",
                "amount": "8750000000",
                "amountUsd": 1750.00,
                "decimals": 9
              },
              {
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "symbol": "USDC",
                "name": "USD Coin",
                "amount": "1750000000",
                "amountUsd": 1750.00,
                "decimals": 6
              }
            ],
            "metadata": {
              "poolAddress": "HJPjoWUrhoZzkNfRpHuieeFk9WcZWjwy6PBjZ81ngndJ",
              "tickLower": -10000,
              "tickUpper": 10000,
              "inRange": true,
              "unclaimedFees": [
                {
                  "mint": "So11111111111111111111111111111111111111112",
                  "symbol": "SOL",
                  "amount": "50000000",
                  "amountUsd": 10.00,
                  "decimals": 9
                },
                {
                  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                  "symbol": "USDC",
                  "amount": "15500000",
                  "amountUsd": 15.50,
                  "decimals": 6
                }
              ]
            }
          }
        ]
      },
      {
        "protocol": {
          "id": "drift",
          "name": "Drift",
          "url": "https://app.drift.trade",
          "category": "perps"
        },
        "totalValueUsd": 2500.00,
        "totalDepositedUsd": 2000.00,
        "totalBorrowedUsd": 0,
        "totalRewardsUsd": 0,
        "positions": [
          {
            "id": "drift-perp-btc",
            "type": "perp",
            "name": "BTC-PERP Long",
            "valueUsd": 500.00,
            "tokens": [
              {
                "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "symbol": "USDC",
                "name": "USD Coin",
                "amount": "500000000",
                "amountUsd": 500.00,
                "decimals": 6
              }
            ],
            "metadata": {
              "side": "long",
              "leverage": 5.0,
              "entryPrice": 42000.00,
              "markPrice": 43500.00,
              "unrealizedPnl": 500.00,
              "liquidationPrice": 35000.00
            }
          }
        ]
      },
      {
        "protocol": {
          "id": "jito",
          "name": "Jito",
          "url": "https://www.jito.network",
          "category": "lst"
        },
        "totalValueUsd": 1020.50,
        "totalDepositedUsd": 1000.00,
        "totalBorrowedUsd": 0,
        "totalRewardsUsd": 20.50,
        "positions": [
          {
            "id": "jito-stake",
            "type": "stake",
            "name": "Jito Staked SOL",
            "valueUsd": 1020.50,
            "tokens": [
              {
                "mint": "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn",
                "symbol": "JitoSOL",
                "name": "Jito Staked SOL",
                "amount": "5000000000",
                "amountUsd": 1020.50,
                "decimals": 9
              }
            ],
            "metadata": {
              "exchangeRate": 1.085
            }
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>