> ## Documentation Index > Fetch the complete documentation index at: https://coinstats.app/api-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 # 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] > > Your API key gives access to all of your own portfolios — no share token needed. Pass a `portfolioId` from [GET /portfolio/list](/api-docs/api-docs/openapi/get-portfolio-list) to target one portfolio, or omit it to get aggregated coins from all your portfolios. A [share token](/api-docs/api-docs/sharetoken) is only needed to read someone else's shared portfolio. ## Get Portfolio Coins Retrieve detailed information about all coins in your portfolio: ```bash cURL theme={null} curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/portfolio/coins?portfolioId=YOUR_PORTFOLIO_ID&includeRiskScore=true" ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.coinstats.app/v1/portfolio/coins?portfolioId=YOUR_PORTFOLIO_ID&includeRiskScore=true', { headers: { 'X-API-KEY': 'your-api-key' } }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.coinstats.app/v1/portfolio/coins', params={ 'portfolioId': 'YOUR_PORTFOLIO_ID', 'includeRiskScore': 'true' }, headers={ 'X-API-KEY': 'your-api-key' } ) data = response.json() ``` > [!NOTE] > > **8 credits** per request ### Headers | Header | Required | Description | | - | - | - | | `X-API-KEY` | Yes | Your CoinStats API key | | `sharetoken` | No | Share token of a shared portfolio ([learn more](/api-docs/api-docs/sharetoken)). Not needed for your own portfolios | | `passcode` | No | Passcode if the shared portfolio is protected | ### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `portfolioId` | string | No | One of your portfolios from [GET /portfolio/list](/api-docs/api-docs/openapi/get-portfolio-list). Omit to aggregate all your portfolios | | `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) | ### Shared Portfolio (Share Token) To read a portfolio someone shared with you, pass its share token instead of `portfolioId`. Add the `passcode` header if the shared portfolio is protected: ```bash theme={null} curl -H "X-API-KEY: your-api-key" \ -H "sharetoken: SHARED_PORTFOLIO_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 > **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 > **Price Data** > > Current prices in multiple currencies: > > * `price.USD`: Price in US Dollars > * `price.BTC`: Price in Bitcoin > * `price.ETH`: Price in Ethereum > **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 > **Average Prices** > > * `averageBuy`: Average price paid when buying > * `averageSell`: Average price received when selling > **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 ## Use Cases > **Portfolio Analysis** > > Analyze your complete crypto holdings with detailed profit/loss data > **Performance Tracking** > > Monitor individual coin performance and identify top performers > **Risk Management** > > Use risk scores to assess portfolio volatility and liquidity > **Tax Reporting** > > Export realized and unrealized gains for tax calculations ## 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" \ "https://api.coinstats.app/v1/portfolio/coins?portfolioId=YOUR_PORTFOLIO_ID&page=1&limit=20" # Get next 20 coins curl -H "X-API-KEY: your-api-key" \ "https://api.coinstats.app/v1/portfolio/coins?portfolioId=YOUR_PORTFOLIO_ID&page=2&limit=20" ``` ## Error Handling > **Unauthorized (401)** > > ```json theme={null} > { > "error": "Invalid API key" > } > ``` > > **Solution**: Check that your API key is correct and active > **Portfolio Not Found (404)** > > ```json theme={null} > { > "statusCode": 404, > "message": "Portfolio not found or not accessible" > } > ``` > > **Solution**: Use a `portfolioId` returned by [GET /portfolio/list](/api-docs/api-docs/openapi/get-portfolio-list). If you are reading a shared portfolio, verify the share token is correct > **Passcode Required (409)** > > ```json theme={null} > { > "error": "Passcode required for this portfolio" > } > ``` > > **Solution**: Include the correct passcode for the shared portfolio > [!WARNING] > > Share tokens are optional. Use them only to read a portfolio someone shared with you — see the [Share Token Authentication](/api-docs/api-docs/sharetoken) guide. ## Related Endpoints > **[Portfolio Value](/api-docs/api-docs/openapi/get-portfolio-value)** > > Get total portfolio value and overall PnL metrics > **[Portfolio Chart](/api-docs/api-docs/portfolio/portfolio-chart)** > > View historical portfolio performance data > **[Portfolio Transactions](/api-docs/api-docs/openapi/get-portfolio-transactions)** > > Access complete transaction history > **[Portfolio DeFi](/api-docs/api-docs/openapi/get-portfolio-defi)** > > View staking and DeFi positions ## Support This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.