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

# Share Token Authentication

> Learn how to use share tokens to access portfolio data through the CoinStats API

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.

> [!TIP]
>
> To work with your own portfolios, skip share tokens entirely. Call [GET /portfolio/list](/api-docs/api-docs/openapi/get-portfolio-list) to get your `portfolioId`s, then pass `portfolioId` to any portfolio endpoint — or omit it to get aggregated data for all your portfolios.

## What is a Share Token?

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

> [!NOTE]
>
> 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](/api-docs/api-docs/openapi/get-portfolio-list).

## Getting Your Share Token

**1. Visit your CoinStats Portfolio**

Go to [CoinStats Portfolio](https://coinstats.app/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](https://mintcdn.com/dev-c758229b/t8KX4os34x2U4jMV/api-docs/assets/share_button.png?fit=max\&auto=format\&n=t8KX4os34x2U4jMV\&q=85\&s=ad906ba6ca4845a55bf3730601ee7600)

**3. Generate a Share Link**

This will bring up sharing preferences for your portfolio. Fill Title and Description and Click **Generate Link**.

> [!WARNING]
>
> 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](https://mintcdn.com/dev-c758229b/t8KX4os34x2U4jMV/api-docs/assets/share_token.png?fit=max\&auto=format\&n=t8KX4os34x2U4jMV\&q=85\&s=8b5e708a84e8457e7279799f3b1b47e0)

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)

```bash theme={null}
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

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

> [!NOTE]
>
> 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 via the `sharetoken` request header (recommended) or as a query parameter.

### Method 1: Request Header (Recommended)

Include the share token in the `sharetoken` header:

```bash theme={null}
curl -H "X-API-KEY: your-api-key" \
     -H "sharetoken: YOUR_SHARE_TOKEN" \
     "https://api.coinstats.app/v1/portfolio/value"
```

With passcode:

```bash theme={null}
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:

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

With passcode:

```bash theme={null}
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:

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

> [!NOTE]
>
> Headers take precedence over query parameters when both are provided for the same value.

## Endpoints That Accept Share Tokens

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](/api-docs/api-docs/openapi/get-portfolio-value)**
>
> Get comprehensive portfolio profit/loss data and metrics

> **[Portfolio Holdings](/api-docs/api-docs/openapi/get-portfolio-coins)**
>
> View all coins in your portfolio with current holdings and PnL

> **[Portfolio Chart](/api-docs/api-docs/openapi/get-portfolio-chart)**
>
> Historical performance data for portfolio visualization

> **[Transaction History](/api-docs/api-docs/openapi/get-portfolio-transactions)**
>
> Complete transaction history with filtering options

> **[DeFi Positions](/api-docs/api-docs/openapi/get-portfolio-defi)**
>
> Staking, liquidity pools, and yield farming data

> **[Portfolio Snapshots](/api-docs/api-docs/openapi/get-portfolio-snapshot-items)**
>
> Historical portfolio snapshot data over time

> **[Add Transaction (legacy)](/api-docs/api-docs/openapi/add-portfolio-transaction)**
>
> Add a transaction to a manual portfolio. Own share links only; prefer `portfolioId` with your API key

## Security Best Practices

> **Protect Your Share Tokens with Passcode**
>
> * Store share tokens passcode securely using environment variables
> * Never expose share tokens passcode in client-side code

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

> **Invalid Share Token**
>
> ```json theme={null}
> {
>   "statusCode": 404,
>   "message": "Shared portfolio not found"
> }
> ```
>
> **Solution**: Verify that your share token is correct and the portfolio still exists.

> **Passcode Required**
>
> ```json theme={null}
> {
>   "error": "Passcode required for this portfolio"
> }
> ```
>
> **Solution**: Include the correct passcode in your request parameters.

> **Permission Denied**
>
> ```json theme={null}
> {
>   "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](/api-docs/api-docs/openapi/get-portfolio-list) (recommended).

## Need Help?

> **[Support Documentation](https://help.coinstats.app/en/articles/12002063)**
>
> Check our comprehensive help center

> **[Telegram Support](https://t.me/+JPUMD1QAMTNmNGQy)**
>
> Join our API support channel for real-time help

> **[Email Support](mailto:api.support@coinstats.app)**
>
> You can reach us directly at [api.support@coinstats.app](mailto:api.support@coinstats.app)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.