> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/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

export const title_0 = "Need Help?"

export const cards_0 = "true"

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

<Note>
  Share tokens are only available for users with a **Degen plan subscription**. All portfolio endpoints require either a share token or proper API authentication.
</Note>

## Getting Your Share Token

<Steps>
  <Step title="Visit your CoinStats Portfolio">
    Go to [CoinStats Portfolio](https://coinstats.app/portfolio) and make sure you are signed in to your account.
  </Step>

  <Step title="Access the Share Button">
    In the top-right corner of the page, click on the **Share** button.

    <Frame>
      <img src="https://mintcdn.com/dev-c758229b/Yr049bZagR2waFYs/assets/share_button.png?fit=max&auto=format&n=Yr049bZagR2waFYs&q=85&s=1e1e5eadc2e91379889439b25d0e32b4" alt="Share Button Location" width="668" height="248" data-path="assets/share_button.png" />
    </Frame>
  </Step>

  <Step title="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.
    </Warning>
  </Step>

  <Step title="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
    ```

    <Frame>
      <img src="https://mintcdn.com/dev-c758229b/Yr049bZagR2waFYs/assets/share_token.png?fit=max&auto=format&n=Yr049bZagR2waFYs&q=85&s=c9d7775d68210d66918846941e53e331" alt="Share Button Location" width="874" height="260" data-path="assets/share_token.png" />
    </Frame>

    Copy only the token portion (without additional slashes or characters).
  </Step>
</Steps>

## 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"
```

<Info>
  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.
</Info>

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

## Endpoints That Use Share Tokens

All portfolio-related endpoints require share tokens:

<CardGroup cols={2}>
  <Card title="Portfolio Value" icon="chart-line" href="/openapi/get-portfolio-value">
    Get comprehensive portfolio profit/loss data and metrics
  </Card>

  <Card title="Portfolio Holdings" icon="coins" href="/openapi/get-portfolio-coins">
    View all coins in your portfolio with current holdings and PnL
  </Card>

  <Card title="Portfolio Chart" icon="chart-area" href="/openapi/get-portfolio-chart">
    Historical performance data for portfolio visualization
  </Card>

  <Card title="Transaction History" icon="clock-rotate-left" href="/openapi/get-portfolio-transactions">
    Complete transaction history with filtering options
  </Card>

  <Card title="Add Transaction" icon="plus" href="/openapi/add-portfolio-transaction">
    Add new transactions to manual portfolios
  </Card>

  <Card title="DeFi Positions" icon="layer-group" href="/openapi/get-portfolio-defi">
    Staking, liquidity pools, and yield farming data
  </Card>

  <Card title="Portfolio Snapshots" icon="camera" href="/openapi/get-portfolio-snapshot-items">
    Historical portfolio snapshot data over time
  </Card>
</CardGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Protect Your Share Tokens with Passcode">
    * Store share tokens passcode securely using environment variables
    * Never expose share tokens passcode in client-side code
  </Accordion>

  <Accordion title="Monitor Portfolio Access">
    * Keep track of where you've shared your portfolio links
    * Consider using passcode protection for sensitive portfolios
  </Accordion>
</AccordionGroup>

## Error Handling

Common errors when using share tokens:

<AccordionGroup>
  <Accordion title="Missing Share Token">
    ```json theme={null}
    {
      "error": "shareToken is required"
    }
    ```

    **Solution**: Ensure you're providing the share token either as a query parameter or header.
  </Accordion>

  <Accordion title="Invalid Share Token">
    ```json theme={null}
    {
      "error": "Shared portfolio not found"
    }
    ```

    **Solution**: Verify that your share token is correct and the portfolio still exists.
  </Accordion>

  <Accordion title="Passcode Required">
    ```json theme={null}
    {
      "error": "Passcode required for this portfolio"
    }
    ```

    **Solution**: Include the correct passcode in your request parameters.
  </Accordion>

  <Accordion title="Permission Denied">
    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## {title_0 || "Support"}

{cards_0 ? (
<CardGroup cols={2}>
<Card title="Support Documentation" icon="question" href="https://help.coinstats.app/en/articles/12002063">
  Check our comprehensive help center
</Card>

<Card title="Telegram Support" icon="telegram" href="https://t.me/+JPUMD1QAMTNmNGQy">
  Join our API support channel for real-time help
</Card>

 <Card title="Email Support" icon="telegram" href="mailto:api.support@coinstats.app">
  You can reach us directly at api.support@coinstats.app
</Card>
</CardGroup>
) : (
  <ul>
      <li><strong>Documentation</strong>: This site contains comprehensive API documentation</li>
      <li><strong>Telegram Chat</strong>: For quick help and to connect with other developers, join our <a href="https://t.me/+JPUMD1QAMTNmNGQy">API Support Telegram group</a></li>
      <li><strong>Email Support</strong>: You can reach us directly at <a href="mailto:api.support@coinstats.app"><strong><u>api.support@coinstats.app</u></strong></a> for personalized assistance.</li>
  </ul>
)}