Supply API

The Supply API reports the total and circulating supply of Stable Mint 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.

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.

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:

{"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.

{
  "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

TIP

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

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 — 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):

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.

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

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

Staging Environment

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

Example Request

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