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

Your API key gives access to all of your own portfolios — no share token needed. Pass a portfolioId from GET /portfolio/list to target one portfolio, or omit it to get aggregated coins from all your portfolios. A share token is only needed to read someone else’s shared portfolio.

Get Portfolio Coins

Retrieve detailed information about all coins in your portfolio:

curl -H "X-API-KEY: your-api-key" \
  "https://api.coinstats.app/v1/portfolio/coins?portfolioId=YOUR_PORTFOLIO_ID&includeRiskScore=true"

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();

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()

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). 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. 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)

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:

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

{
  "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:

# 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)

{
  "error": "Invalid API key"
}

Solution: Check that your API key is correct and active

Portfolio Not Found (404)

{
  "statusCode": 404,
  "message": "Portfolio not found or not accessible"
}

Solution: Use a portfolioId returned by GET /portfolio/list. If you are reading a shared portfolio, verify the share token is correct

Passcode Required (409)

{
  "error": "Passcode required for this portfolio"
}

Solution: Include the correct passcode for the shared portfolio

Share tokens are optional. Use them only to read a portfolio someone shared with you — see the Share Token Authentication guide.

Portfolio Value

Get total portfolio value and overall PnL metrics

Portfolio Chart

View historical portfolio performance data

Portfolio Transactions

Access complete transaction history

Portfolio DeFi

View staking and DeFi positions

Getting started

AI Agents Integration

Wallet Data

User Portfolio

Token Security

Prediction Markets

Get Portfolio Coins

Access Your Portfolio Coins

Key Features

Get Portfolio Coins

Headers

Query Parameters

Example Response

Response Fields

Use Cases

Portfolio Analysis

Performance Tracking

Risk Management

Tax Reporting

Error Handling

Portfolio Value

Portfolio Chart

Portfolio Transactions

Portfolio DeFi

​Access Your Portfolio Coins

​Key Features

​Get Portfolio Coins

​Headers

​Query Parameters

​Shared Portfolio (Share Token)

​Example Response

​Response Fields

​Use Cases

Portfolio Analysis

Performance Tracking

Risk Management

Tax Reporting

​Pagination

​Error Handling

​Related Endpoints

Portfolio Value

Portfolio Chart

Portfolio Transactions

Portfolio DeFi

Access Your Portfolio Coins

Key Features

Get Portfolio Coins

Headers

Query Parameters

Shared Portfolio (Share Token)

Example Response

Response Fields

Use Cases

Pagination

Error Handling

Related Endpoints