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

# Supply

> Total and circulating supply, aggregated across every chain.

The Supply API reports the **total** and **circulating** supply of StableMint tokens, aggregated across every chain the token is deployed on. Values are returned as `{"result":"<value>"}`, the format that listing services such as CoinGecko and CoinMarketCap expect, and every response is signed (RSA-SHA256) so consumers can verify authenticity — see [Signature Validation](#signature-validation).

## API Format

### Total supply

```
GET /v1/supply/{token}/total-supply
```

### Circulating supply

```
GET /v1/supply/{token}/circulating-supply
```

### Per-chain breakdown

```
GET /v1/supply/{token}
```

### Path Parameters

| Parameter | Type   | Description  | Values  |
| --------- | ------ | ------------ | ------- |
| `token`   | string | Token symbol | `usdsm` |

<Tip>
  A token is served only while it is configured for the running environment. `eursm` is reserved but not yet deployed, so requesting it returns `400 Bad Request` until it is configured.
</Tip>

## Response Format

### Total / circulating supply

Both endpoints return a JSON object with the supply as a string under `result`, matching CoinGecko's documented supply API example (`https://api.coingecko.com/api/v3/supply/eth`), with `Content-Type: application/json`:

```json theme={null}
{"result":"28168334.1"}
```

Circulating supply is always equal to total supply: every minted token is in circulation. There is no locked, vested, or treasury-held supply.

So the body stays the minimal `{"result":"..."}` shape that listing services can parse, the signature is returned out-of-band in response headers:

| Header                  | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `X-Signature`           | Base64-encoded RSA-SHA256 signature                                      |
| `X-Signature-Timestamp` | UTC timestamp the figures were read on-chain (`yyyy-MM-ddTHH:mm:ss.fff`) |
| `X-Signature-Version`   | Signature payload version (e.g. `1.0`)                                   |

### Per-chain breakdown

The breakdown endpoint returns the aggregate plus the supply on each chain, with the signature inline. Use it for transparency dashboards or reconciliation.

```json theme={null}
{
  "token": "USDSM",
  "totalSupply": 28168334.1,
  "circulatingSupply": 28168334.1,
  "chains": [
    { "chain": "Etherlink", "address": "0x6bDE51212203aE5d592Cc5180DA2ABBd41c922dE", "supply": 21955893.95 },
    { "chain": "Ethereum",  "address": "0x399B29975CBE313C56269cD5097F5AE097Fa2741", "supply": 5456187.38 },
    { "chain": "Base",      "address": "0x26C358F7c5fEdB20a6ddEf108cD91Efb6B8Da0Cb", "supply": 386158.64 },
    { "chain": "Arbitrum",  "address": "0x26C358F7c5fEdB20a6ddEf108cD91Efb6B8Da0Cb", "supply": 370094.14 }
  ],
  "timestamp": "2026-06-03T15:13:39.123",
  "version": "1.0",
  "signature": "WyAEj75t6D3i5lolnxsvcjF3oIZD0ElB0YbtCnsevvVpz4pofFTx1U0ZNBcZXUx7..."
}
```

| Field               | Description                                                                             |
| ------------------- | --------------------------------------------------------------------------------------- |
| `token`             | Token symbol                                                                            |
| `totalSupply`       | Total supply across all chains, in whole tokens                                         |
| `circulatingSupply` | Equal to `totalSupply`                                                                  |
| `chains[]`          | Per-chain detail: chain name, contract `address`, and that chain's `supply`             |
| `timestamp`         | UTC timestamp the supply figures were read (`yyyy-MM-ddTHH:mm:ss.fff`)                  |
| `version`           | Signature payload version                                                               |
| `signature`         | Base64-encoded RSA-SHA256 signature — see [Signature Validation](#signature-validation) |

<Tip>
  Supply figures are live on-chain values and change over time. The numbers above are illustrative.
</Tip>

## Signature Validation

Every response is signed with RSA-SHA256 over the following payload, concatenated with pipe (`|`) separators:

```
symbol|totalSupply|circulatingSupply|timestamp|version
```

`circulatingSupply` always equals `totalSupply`; for the scalar `/total-supply` and `/circulating-supply` endpoints the returned number is used for both figures. Example signed string:

```
USDSM|28168334.1|28168334.1|2026-06-03T15:13:39.123|1.0
```

Supply responses are signed with the **same RSA key as the [Price Feed API](/feed/price)** — use the public key published there for your environment (production or staging).

### JavaScript Validation Example

The scalar endpoints are the most reliable to validate, because the body is the exact signed value as text (no floating-point rounding):

```javascript theme={null}
const crypto = require('crypto');

async function validateSupply(url, token, publicKey) {
  const res = await fetch(url);

  // The body is the exact numeric string that was signed — read it as text.
  const value = (await res.text()).trim();
  const timestamp = res.headers.get('X-Signature-Timestamp');
  const version = res.headers.get('X-Signature-Version');
  const signature = res.headers.get('X-Signature');

  // circulatingSupply === totalSupply === value
  const payload = `${token.toUpperCase()}|${value}|${value}|${timestamp}|${version}`;

  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(payload);
  return verifier.verify(publicKey, signature, 'base64');
}

// Example usage (publicKey: see the Price Feed API page for your environment)
(async () => {
  const isValid = await validateSupply(
    'https://feed.stablemint.io/v1/supply/usdsm/total-supply',
    'usdsm',
    publicKey
  );
  console.log('Signature valid:', isValid);
})();
```

The breakdown endpoint returns the same signature inline (`signature` field); reconstruct the payload from its `token`, `totalSupply`, `circulatingSupply`, `timestamp`, and `version` fields.

<Warning>
  Supply figures can carry up to 18 decimal places. JavaScript's `JSON.parse()` represents numbers as 64-bit floats and may silently lose precision on high-decimal values, which would break breakdown signature validation. For exact validation, prefer a scalar endpoint (its body is the precise string) or parse the breakdown with a precision-preserving JSON / big-decimal library.
</Warning>

## Production Environment

Base URL: `https://feed.stablemint.io`

### Available Endpoints

**USDSM total supply**

```
GET https://feed.stablemint.io/v1/supply/usdsm/total-supply
```

**USDSM circulating supply**

```
GET https://feed.stablemint.io/v1/supply/usdsm/circulating-supply
```

**USDSM per-chain breakdown**

```
GET https://feed.stablemint.io/v1/supply/usdsm
```

### Example Request

```bash theme={null}
curl https://feed.stablemint.io/v1/supply/usdsm/circulating-supply
```

## Staging Environment

Base URL: `https://feed.stablemint.net`

### Example Request

```bash theme={null}
curl https://feed.stablemint.net/v1/supply/usdsm/circulating-supply
```

## Errors

| Status                    | When                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400 Bad Request`         | Unsupported token — only configured tokens are served (currently `usdsm`; `eursm` is not yet deployed) |
| `503 Service Unavailable` | Supply for the requested token is temporarily unavailable                                              |