Share Token Authentication

Share tokens provide a way to read a portfolio that has been shared from the CoinStats app. They are optional: your API key already gives you access to all of your own portfolios, so you only need a share token to read a portfolio shared with you.

To work with your own portfolios, skip share tokens entirely. Call GET /portfolio/list to get your portfolioIds, then pass portfolioId to any portfolio endpoint — or omit it to get aggregated data for all your portfolios.

A share token is a unique identifier that grants read access to a specific shared portfolio. It’s generated from the Share button on a 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

Share tokens are a legacy, optional way to identify a portfolio. Portfolio endpoints work with just your API key. Reads: a share token lets you read a portfolio shared with you by another user. Writes: POST /portfolio/transaction still accepts a sharetoken header (legacy), but only for share links you own. The recommended way is your API key plus a portfolioId from GET /portfolio/list.

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.

These endpoints optionally accept a share token (instead of portfolioId). Reads work for a portfolio shared with you; the write endpoint (legacy) works only for your own share links:

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

DeFi Positions

Staking, liquidity pools, and yield farming data

Portfolio Snapshots

Historical portfolio snapshot data over time

Add Transaction (legacy)

Add a transaction to a manual portfolio. Own share links only; prefer portfolioId with your API key

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

{
  "statusCode": 403,
  "message": "You are not allowed to add transactions to this portfolio"
}

Solution: Adding transactions via a share token works only when the share link belongs to you. Instead, use your API key with a manual portfolioId from GET /portfolio/list (recommended).

Getting started

AI Agents Integration

Wallet Data

User Portfolio

Token Security

Prediction Markets

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

DeFi Positions

Portfolio Snapshots

Add Transaction (legacy)

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 Accept Share Tokens

Portfolio Value

Portfolio Holdings

Portfolio Chart

Transaction History

DeFi Positions

Portfolio Snapshots

Add Transaction (legacy)

​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 Accept Share Tokens

Security Best Practices

Error Handling