> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.metadao.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/supply

> Retrieve complete token supply breakdown with allocation details

## Overview

The supply endpoints provide complete supply breakdown for launchpad tokens, including detailed allocation information for circulating supply, team performance packages, and liquidity positions.

<Info>
  For launchpad tokens, circulating supply **excludes** the team performance package but **includes** all liquidity (both FutarchyAMM and Meteora DAMM).
</Info>

## Supply Breakdown

For launchpad tokens, supply is broken down into the following categories:

| Category                     | Description                                              | Circulating? |
| ---------------------------- | -------------------------------------------------------- | ------------ |
| **Circulating Supply**       | Total supply minus team performance package              | ✅ Yes        |
| **Team Performance Package** | Locked tokens allocated to the team (price-based unlock) | ❌ No         |
| **FutarchyAMM Liquidity**    | Tokens in the internal FutarchyAMM for spot trading      | ✅ Yes        |
| **Meteora LP Liquidity**     | Tokens in the external Meteora DAMM pool (POL)           | ✅ Yes        |

<Warning>
  Liquidity tokens (both FutarchyAMM and Meteora) **are** counted as circulating supply since they can be traded.
</Warning>

## Endpoints

| Endpoint                                   | Description                                                    |
| ------------------------------------------ | -------------------------------------------------------------- |
| `GET /api/supply/:mintAddress`             | Returns complete supply breakdown with allocation details      |
| `GET /api/supply/:mintAddress/total`       | Returns total supply only                                      |
| `GET /api/supply/:mintAddress/circulating` | Returns circulating supply (excludes team performance package) |

## Full Supply Information

**Endpoint:** `GET /api/supply/:mintAddress`

Returns complete supply information for a token.

### Path Parameters

<ParamField path="mintAddress" type="string" required>
  The SPL token mint address (Solana PublicKey)

  Example: `METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta`
</ParamField>

### Response

<ResponseField name="result" type="string" required>
  The formatted total supply as a string
</ResponseField>

<ResponseField name="data" type="object" required>
  Complete supply data object with allocation breakdown

  <Expandable title="data properties">
    <ResponseField name="mint" type="string">
      The token mint address
    </ResponseField>

    <ResponseField name="totalSupply" type="string">
      Total token supply (formatted with decimals)
    </ResponseField>

    <ResponseField name="circulatingSupply" type="string">
      Circulating token supply - excludes team performance package (formatted with decimals)
    </ResponseField>

    <ResponseField name="teamPerformancePackage" type="string">
      Locked tokens allocated to the team with price-based unlock - NOT circulating
    </ResponseField>

    <ResponseField name="futarchyAmmLiquidity" type="string">
      Tokens in the internal FutarchyAMM for spot trading - IS circulating
    </ResponseField>

    <ResponseField name="meteoraLpLiquidity" type="string">
      Tokens in the external Meteora DAMM pool (POL) - IS circulating
    </ResponseField>

    <ResponseField name="decimals" type="number">
      Token decimal places
    </ResponseField>

    <ResponseField name="rawTotalSupply" type="string">
      Raw total supply without decimal formatting
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://market-api.metadao.fi/api/supply/METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta
  ```

  ```javascript JavaScript theme={null}
  const mintAddress = 'METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta';
  const response = await fetch(`https://market-api.metadao.fi/api/supply/${mintAddress}`);
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  mint_address = 'METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta'
  response = requests.get(f'https://market-api.metadao.fi/api/supply/{mint_address}')
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "result": "1000000.0",
  "data": {
    "mint": "METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta",
    "totalSupply": "1000000.0",
    "circulatingSupply": "850000.0",
    "teamPerformancePackage": "150000.0",
    "futarchyAmmLiquidity": "200000.0",
    "meteoraLpLiquidity": "100000.0",
    "decimals": 9,
    "rawTotalSupply": "1000000000000000"
  }
}
```

***

## Total Supply Only

**Endpoint:** `GET /api/supply/:mintAddress/total`

Returns just the total supply value as a plain string. Useful for integrations that only need the total supply number.

### Example Request

```bash theme={null}
curl https://market-api.metadao.fi/api/supply/METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta/total
```

### Example Response

```
1000000.0
```

<Note>
  This endpoint returns a plain text response, not JSON, for easy integration with tools expecting a simple number.
</Note>

***

## Circulating Supply Only

**Endpoint:** `GET /api/supply/:mintAddress/circulating`

Returns just the circulating supply value as a plain string. This value **excludes** the team performance package but **includes** all liquidity positions.

<Info>
  **Circulating = Total Supply - Team Performance Package**

  Both FutarchyAMM liquidity and Meteora LP liquidity are included in circulating supply since these tokens are actively tradeable.
</Info>

### Example Request

```bash theme={null}
curl https://market-api.metadao.fi/api/supply/METAwkXcqyXKy1AtsSgJ8JiUHwGCafnZL38n3vYmeta/circulating
```

### Example Response

```
850000.0
```

<Note>
  This endpoint returns a plain text response, not JSON, for easy integration with price aggregators like CoinGecko and CoinMarketCap.
</Note>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Price Aggregators" icon="chart-mixed">
    CoinGecko and CoinMarketCap require supply endpoints for market cap calculations
  </Card>

  <Card title="Token Dashboards" icon="gauge">
    Display real-time supply metrics on token information pages
  </Card>

  <Card title="Analytics" icon="magnifying-glass-chart">
    Track supply changes over time for tokenomics analysis
  </Card>

  <Card title="DeFi Integrations" icon="coins">
    Calculate fully diluted valuations and token metrics
  </Card>
</CardGroup>

## Error Handling

### Invalid Mint Address

```json theme={null}
{
  "error": "Invalid mint address"
}
```

### Mint Not Found

```json theme={null}
{
  "error": "Token mint not found"
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Tickers API" icon="chart-line" href="/api-reference/tickers">
    Get pricing and volume data for all DAOs
  </Card>

  <Card title="Volume Aggregate" icon="chart-bar" href="/api-reference/volume-aggregate">
    Get aggregate volume with daily breakdown
  </Card>

  <Card title="API Overview" icon="book" href="/api-reference/overview">
    Learn about the API architecture
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle" href="/advanced/error-handling">
    Handle API errors properly
  </Card>
</CardGroup>