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

# Get Portfolio Coins

> Get detailed information about all coins in your portfolio with profit/loss data and performance metrics

export const title_0 = undefined

export const cards_0 = undefined

# Access Your Portfolio Coins

Get comprehensive information about all cryptocurrency holdings in your CoinStats portfolio, including current balances, profit/loss calculations, performance metrics, and risk assessment scores.

## Key Features

* **Complete Holdings Overview**: View all coins with current balances and USD values
* **Profit/Loss Tracking**: Detailed PnL data including realized, unrealized, and 24-hour changes
* **Performance Metrics**: Average buy/sell prices and profit percentages
* **Risk Assessment**: Optional risk scores including liquidity, volatility, and market cap metrics
* **Multi-Currency Values**: Get values in USD, BTC, and ETH

<Note>
  This endpoint is only available for users with a **Degen plan subscription**. You'll need a share token to access portfolio data. Learn more about [Share Token Authentication](/sharetoken).
</Note>

## Get Portfolio Coins

Retrieve detailed information about all coins in your portfolio:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-KEY: your-api-key" \
       -H "sharetoken: YOUR_SHARE_TOKEN" \
    "https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true', {
    headers: {
      'X-API-KEY': 'your-api-key',
      'sharetoken': 'YOUR_SHARE_TOKEN'
    }
  });
  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.coinstats.app/v1/portfolio/coins',
      params={
          'includeRiskScore': 'true'
      },
      headers={
          'X-API-KEY': 'your-api-key',
          'sharetoken': 'YOUR_SHARE_TOKEN'
      }
  )
  data = response.json()
  ```
</CodeGroup>

<Note>
  **8 credits** per request
</Note>

### Headers

| Header       | Required | Description                                               |
| ------------ | -------- | --------------------------------------------------------- |
| `X-API-KEY`  | Yes      | Your CoinStats API key                                    |
| `sharetoken` | Yes      | Your portfolio share token ([how to get it](/sharetoken)) |
| `passcode`   | No       | Passcode if your portfolio is protected                   |

### Query Parameters

| Parameter          | Type    | Required | Description                                            |
| ------------------ | ------- | -------- | ------------------------------------------------------ |
| `page`             | number  | No       | Page number for pagination (default: 1)                |
| `limit`            | number  | No       | Number of results per page                             |
| `includeRiskScore` | boolean | No       | Set to `true` to include risk metrics (default: false) |

### With Passcode

For passcode-protected portfolios, add the `passcode` header:

```bash theme={null}
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     -H "passcode: 123456" \
     "https://api.coinstats.app/v1/portfolio/coins?includeRiskScore=true"
```

### Example Response

```json theme={null}
{
  "result": [
    {
      "count": 44.4987,
      "coin": {
        "rank": 2,
        "identifier": "ethereum",
        "symbol": "ETH",
        "name": "Ethereum",
        "icon": "https://static.coinstats.app/coins/1650455629727.png",
        "isFake": false,
        "isFiat": false,
        "priceChange24h": -5.74,
        "priceChange1h": 0.1,
        "priceChange7d": 1.12,
        "priceChange1m": 8.42,
        "volume": 61315198931.43572
      },
      "price": {
        "USD": 4343.564311034,
        "BTC": 0.039479708,
        "ETH": 1
      },
      "profit": {
        "allTime": {
          "USD": 83720.75297372,
          "BTC": 0.054246576,
          "ETH": -0.0008427712028833412
        },
        "hour24": {
          "USD": -11770.04265107636,
          "BTC": -0.055726915608058335,
          "ETH": 0
        },
        "lastTrade": {
          "USD": -0.0011652685976688212,
          "BTC": -8.325768295004658e-9,
          "ETH": 8.470329472543003e-22
        },
        "unrealized": {
          "USD": 64875.375139922,
          "BTC": 0.516615331,
          "ETH": -0.000013421973257266018
        },
        "realized": {
          "USD": 18844.785945298,
          "BTC": -0.46237401135664413,
          "ETH": -0.0008426785167330308
        }
      },
      "averageBuy": {
        "USD": 2800.50,
        "BTC": 0.028,
        "ETH": 0.95
      },
      "averageSell": {
        "USD": 3200.00,
        "BTC": 0.032,
        "ETH": 1.05
      },
      "profitPercent": {
        "allTime": {
          "USD": 55.2,
          "BTC": 41.0,
          "ETH": -0.09
        },
        "unrealized": {
          "USD": 42.5,
          "BTC": 38.2,
          "ETH": -0.01
        },
        "realized": {
          "USD": 14.2,
          "BTC": -15.5,
          "ETH": -0.08
        }
      },
      "liquidityScore": 94.44676177373067,
      "volatilityScore": 6.823477152064536,
      "marketCapScore": 90.15554879029162,
      "riskScore": 7.407055529347417,
      "avgChange": 2.631321607022045
    }
  ]
}
```

## Response Fields

<AccordionGroup>
  <Accordion title="Coin Information">
    * `count`: Amount of the coin you hold
    * `coin.rank`: Market cap rank
    * `coin.identifier`: Unique coin identifier
    * `coin.symbol`: Coin ticker symbol
    * `coin.name`: Full coin name
    * `coin.icon`: Coin logo URL
    * `coin.priceChange24h`: 24-hour price change percentage
    * `coin.priceChange1h`: 1-hour price change percentage
    * `coin.priceChange7d`: 7-day price change percentage
    * `coin.priceChange1m`: 1-month price change percentage
    * `coin.volume`: 24-hour trading volume
  </Accordion>

  <Accordion title="Price Data">
    Current prices in multiple currencies:

    * `price.USD`: Price in US Dollars
    * `price.BTC`: Price in Bitcoin
    * `price.ETH`: Price in Ethereum
  </Accordion>

  <Accordion title="Profit/Loss Metrics">
    * `profit.allTime`: Total profit/loss since first purchase
    * `profit.hour24`: Profit/loss in the last 24 hours
    * `profit.lastTrade`: Profit/loss from the most recent trade
    * `profit.unrealized`: Profit/loss on holdings not yet sold
    * `profit.realized`: Profit/loss from completed sales
  </Accordion>

  <Accordion title="Average Prices">
    * `averageBuy`: Average price paid when buying
    * `averageSell`: Average price received when selling
  </Accordion>

  <Accordion title="Risk Scores (Optional)">
    Only included when `includeRiskScore=true`:

    * `liquidityScore`: Market liquidity metric (0-100)
    * `volatilityScore`: Price volatility metric (0-100)
    * `marketCapScore`: Market capitalization score (0-100)
    * `riskScore`: Overall risk assessment (0-100)
    * `avgChange`: Average price change percentage
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Portfolio Analysis" icon="chart-pie">
    Analyze your complete crypto holdings with detailed profit/loss data
  </Card>

  <Card title="Performance Tracking" icon="chart-line">
    Monitor individual coin performance and identify top performers
  </Card>

  <Card title="Risk Management" icon="shield-halved">
    Use risk scores to assess portfolio volatility and liquidity
  </Card>

  <Card title="Tax Reporting" icon="file-invoice">
    Export realized and unrealized gains for tax calculations
  </Card>
</CardGroup>

## Pagination

For portfolios with many coins, use pagination to manage results:

```bash theme={null}
# Get first 20 coins
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
  "https://api.coinstats.app/v1/portfolio/coins?page=1&limit=20"

# Get next 20 coins
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
  "https://api.coinstats.app/v1/portfolio/coins?page=2&limit=20"
```

## Error Handling

<AccordionGroup>
  <Accordion title="Missing Share Token (400)">
    ```json theme={null}
    {
      "error": "shareToken is required"
    }
    ```

    **Solution**: Include the share token in your request
  </Accordion>

  <Accordion title="Unauthorized (401)">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```

    **Solution**: Check that your API key is correct and active
  </Accordion>

  <Accordion title="Subscription Required (403)">
    ```json theme={null}
    {
      "error": "This endpoint requires a Degen plan subscription"
    }
    ```

    **Solution**: Upgrade to a Degen plan to access portfolio endpoints
  </Accordion>

  <Accordion title="Portfolio Not Found (404)">
    ```json theme={null}
    {
      "error": "Shared portfolio not found"
    }
    ```

    **Solution**: Verify your share token is correct
  </Accordion>

  <Accordion title="Passcode Required (409)">
    ```json theme={null}
    {
      "error": "Passcode required for this portfolio"
    }
    ```

    **Solution**: Include the correct passcode in your request
  </Accordion>
</AccordionGroup>

<Warning>
  Make sure you have a valid share token before making requests. See the [Share Token Authentication](/sharetoken) guide for detailed instructions on getting your token.
</Warning>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Portfolio Value" icon="wallet" href="/openapi/get-portfolio-value">
    Get total portfolio value and overall PnL metrics
  </Card>

  <Card title="Portfolio Chart" icon="chart-area" href="/portfolio/portfolio-chart">
    View historical portfolio performance data
  </Card>

  <Card title="Portfolio Transactions" icon="clock-rotate-left" href="/openapi/get-portfolio-transactions">
    Access complete transaction history
  </Card>

  <Card title="Portfolio DeFi" icon="layer-group" href="/openapi/get-portfolio-defi">
    View staking and DeFi positions
  </Card>
</CardGroup>

## {title_0 || "Support"}

{cards_0 ? (
<CardGroup cols={2}>
<Card title="Support Documentation" icon="question" href="https://help.coinstats.app/en/articles/12002063">
  Check our comprehensive help center
</Card>

<Card title="Telegram Support" icon="telegram" href="https://t.me/+JPUMD1QAMTNmNGQy">
  Join our API support channel for real-time help
</Card>

 <Card title="Email Support" icon="telegram" href="mailto:api.support@coinstats.app">
  You can reach us directly at api.support@coinstats.app
</Card>
</CardGroup>
) : (
  <ul>
      <li><strong>Documentation</strong>: This site contains comprehensive API documentation</li>
      <li><strong>Telegram Chat</strong>: For quick help and to connect with other developers, join our <a href="https://t.me/+JPUMD1QAMTNmNGQy">API Support Telegram group</a></li>
      <li><strong>Email Support</strong>: You can reach us directly at <a href="mailto:api.support@coinstats.app"><strong><u>api.support@coinstats.app</u></strong></a> for personalized assistance.</li>
  </ul>
)}