Share Token Authentication

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. 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 available to all CoinStats users — generate one from your portfolio using the Share button (see below). All portfolio endpoints require either a share token or proper API authentication.

Visit your CoinStats Portfolio

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

Access the Share Button

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

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.

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

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

Method 1: Header (Recommended)

curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     -H "passcode: 123456" \
     "https://api.coinstats.app/v1/portfolio/value"

Method 2: Query Parameter

curl -H "X-API-KEY: your-api-key" \
     "https://api.coinstats.app/v1/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.

Share tokens can be provided via the sharetoken request header (recommended) or as a query parameter.

Method 1: Request Header (Recommended)

Include the share token in the sharetoken header:

curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     "https://api.coinstats.app/v1/portfolio/value"

With passcode:

curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     -H "passcode: 123456" \
     "https://api.coinstats.app/v1/portfolio/value"

Method 2: Query Parameter

Pass shareToken as a query parameter:

curl -H "X-API-KEY: your-api-key" \
     "https://api.coinstats.app/v1/portfolio/value?shareToken=YOUR_SHARE_TOKEN"

With passcode:

curl -H "X-API-KEY: your-api-key" \
     "https://api.coinstats.app/v1/portfolio/value?shareToken=YOUR_SHARE_TOKEN&passcode=123456"

Hybrid Approach

You can also mix query parameters and headers:

curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     "https://api.coinstats.app/v1/portfolio/value?passcode=123456"

Headers take precedence over query parameters when both are provided for the same value.

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

Monitor Portfolio Access

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:

Passcode Required

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

Solution: Include the correct passcode in your request parameters.

Permission Denied

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

Getting started

AI Agents Integration

Wallet Data

User Portfolio

Token Security

Passcode Protection

Method 1: Header (Recommended)

Method 2: Query Parameter

Method 1: Request Header (Recommended)

Method 2: Query Parameter

Hybrid Approach

Portfolio Value

Portfolio Holdings

Portfolio Chart

Transaction History

Add Transaction

DeFi Positions

Portfolio Snapshots

Security Best Practices

Error Handling

​What is a Share Token?

​Getting Your Share Token

​Passcode Protection

​Method 1: Header (Recommended)

​Method 2: Query Parameter

​Using Share Tokens in API Requests

​Method 1: Request Header (Recommended)

​Method 2: Query Parameter

​Hybrid Approach

​Endpoints That Use Share Tokens

Portfolio Value

Portfolio Holdings

Portfolio Chart

Transaction History

Add Transaction

DeFi Positions

Portfolio Snapshots

​Security Best Practices

​Error Handling

What is a Share Token?

Getting Your Share Token

Passcode Protection

Method 1: Header (Recommended)

Method 2: Query Parameter

Using Share Tokens in API Requests

Method 1: Request Header (Recommended)

Method 2: Query Parameter

Hybrid Approach

Endpoints That Use Share Tokens

Security Best Practices

Error Handling