Skip to main content
Share tokens provide a secure way to access portfolio data from the CoinStats app through the API. This authentication method allows you to share specific portfolio information without exposing your main API credentials.

​
What is a Share Token?

A share token is a unique identifier that grants API access to a specific portfolio. It’s generated directly from your CoinStats portfolio and can be used to:
  • View portfolio holdings and balances
  • Access transaction history
  • Retrieve DeFi positions and staking data
  • Get portfolio performance metrics and charts
  • Add transactions to manual portfolios
Share tokens are only available for users with a Degen plan subscription. All portfolio endpoints require either a share token or proper API authentication.

​
Getting Your Share Token

1

Visit your CoinStats Portfolio

Go to CoinStats Portfolio and make sure you are signed in to your account.
2

Access the Share Button

In the top-right corner of the page, click on the Share button.
Share Button Location
3

Generate a Share Link

This will bring up sharing preferences for your portfolio. Fill Title and Description and Click Generate Link.
Make sure you understand the privacy implications of sharing your portfolio data before generating a link.
4

Extract the Share Token

In the generated URL, the segment following /p/ is your share token.
https://coinstats.app/p/YOUR_SHARE_TOKEN_HERE
                        ^^^^^^^^^^^^^^^^^^^^
                      This is your share token
Share Button Location
Copy only the token portion (without additional slashes or characters).

​
Passcode Protection

Some portfolios may be protected with an additional passcode for extra security. If a portfolio requires a passcode, you can include it in your requests using either query parameters or headers (recommended): 
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     -H "passcode: 123456" \
     "https://openapiv1.coinstats.app/portfolio/value"

​
Method 2: Query Parameter

curl -H "X-API-KEY: your-api-key" \
     "https://openapiv1.coinstats.app/portfolio/value?shareToken=YOUR_SHARE_TOKEN&passcode=123456"
The passcode is an optional 6-digit code that can be set when sharing a portfolio for additional privacy protection. Headers are recommended for better security as they keep sensitive information out of URL logs.

​
Using Share Tokens in API Requests

Share tokens can be provided in two ways, and passcode can be included using either method:

​
Method 1: Query Parameter

Include the shareToken parameter in your query string: 
curl -H "X-API-KEY: your-api-key" \
     "https://openapiv1.coinstats.app/portfolio/value?shareToken=YOUR_SHARE_TOKEN"
With passcode: 
curl -H "X-API-KEY: your-api-key" \
     "https://openapiv1.coinstats.app/portfolio/value?shareToken=YOUR_SHARE_TOKEN&passcode=123456"
Include the share token in the sharetoken header: 
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     "https://openapiv1.coinstats.app/portfolio/value"
With passcode: 
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     -H "passcode: 123456" \
     "https://openapiv1.coinstats.app/portfolio/value"

​
Hybrid Approach

You can also mix query parameters and headers: 
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     "https://openapiv1.coinstats.app/portfolio/value?passcode=123456"
Headers take precedence over query parameters when both are provided for the same value.

​
Endpoints That Use Share Tokens

All portfolio-related endpoints require share tokens:

Portfolio Value

Get comprehensive portfolio profit/loss data and metrics

Portfolio Holdings

View all coins in your portfolio with current holdings and PnL

Portfolio Chart

Historical performance data for portfolio visualization

Transaction History

Complete transaction history with filtering options

Add Transaction

Add new transactions to manual portfolios

DeFi Positions

Staking, liquidity pools, and yield farming data

Portfolio Snapshots

Historical portfolio snapshot data over time

​
Security Best Practices

  • Store share tokens passcode securely using environment variables
  • Never expose share tokens passcode in client-side code
  • Keep track of where you’ve shared your portfolio links
  • Consider using passcode protection for sensitive portfolios

​
Error Handling

Common errors when using share tokens: 
{
  "error": "shareToken is required"
}
Solution: Ensure you’re providing the share token either as a query parameter or header.
{
  "error": "Shared portfolio not found"
}
Solution: Verify that your share token is correct and the portfolio still exists.
{
  "error": "Passcode required for this portfolio"
}
Solution: Include the correct passcode in your request parameters.
{
  "error": "You are not allowed to add transactions to this portfolio"
}
Solution: This error occurs when trying to add transactions to a portfolio you don’t own or to non-manual portfolios.
⌘I