Skip to main content

Lumen Supply Metrics

This section explains how lumen supply metrics are calculated and made available via API. This information can be useful for products and services that track the distribution of XLM, including market cap aggregators and some exchanges, or to anyone who wants to investigate the distribution of XLM defined by the SDF mandate.

Unlike many other blockchains, the native network currency is not created through mining- all XLM that has ever existed and will ever exist was created when the Stellar network went live.

SDF’s Dashboard API endpoint will always have the live totals for the essential numbers around lumens. This guide explains important supply metrics like Original Supply, Total Supply, and Circulating Supply entailed in that data.

Dashboard API​

As of December 12, 2019, the Dashboard API shows:

{
  "updatedAt": "2019-12-12T21:07:23.480Z",
  "originalSupply": "100000000000",
  "inflationLumens": "5443902087.3472865",
  "burnedLumens": "55442098181.3755700",
  "totalSupply": "50001803905.9717165",
  "upgradeReserve": "414310437.8111675",
  "feePool": "1807341.5766261",
  "sdfMandate": "29635032570.5297368",
  "circulatingSupply": "19950653556.0541861",
  "_details": "https://www.stellar.org/developers/guides/lumen-supply-metrics.html"
}

Definitions​

originalSupply One hundred billion lumens were created when the Stellar network went live. That’s the Original Supply for the network.

inflationLumens For the first five or so years of Stellar’s existence, the supply of lumens increased by 1% annually. This “network inflation” was ended by validator vote on October 28, 2019. The total number of lumens generated by inflation was 5,443,902,087.3472865.

Adding this number to the Original Supply, you get the total lumens that have ever existed: 105,443,902,087.3472865. This number is visible on the List All Ledgers (https://horizon-mainnet-url/ledgers?order=desc) Horizon API endpoint as _embedded.records.total_coins.

burnedLumens These are all the lumens sent to accounts with no signers, meaning the funds are inaccessible and have been removed forever from Stellar’s lumen supply.

While any address with no signers is counted here, the vast majority of the lumens in this sum are in a single locked address. On November 4, 2019, SDF reduced its lumen holdings to better reflect its mission and the growth of the Stellar ecosystem. To do so, the Foundation sent 55,442,095,285.7418 lumens to GALA…LUTO.

totalSupply The Total Supply is the number of lumens now in existence: 50,001,803,905.97172. The Total Supply includes four major categories of lumens, which the API treats in detail.

upgradeReserve The Upgrade Reserve is a special address that’s neither circulating nor a part of SDF’s mandate. When Stellar changed its consensus algorithm in 2015 and relaunched the network these lumens were set aside, to be claimed, one-for-one, by holders of the old network tokens. The Upgrade Reserve account is essentially an escrow, and we don’t expect many claimants to come and pull those lumens into the circulating supply at this point.

feePool The Fee Pool is where network fees collect. The lumens do not belong to any particular account. No one has access to the fee pool, so these lumens are non-circulating. Network validators could theoretically vote for a protocol change that would affect the fee pool, so we include it n the total supply. Stellar’s transaction fees are extremely low so the fee pool grows very slowly. The Fee Pool is tracked by the protocol itself, and the current number is visible on the List All Ledgers (https://horizon-mainnet-url/ledgers?order=desc) Horizon API endpoint as _embedded.records.fee_pool. i sdfMandate The SDF Mandate is described in detail here. The Foundation was funded by lumens generated at Stellar’s inception; all of those lumens will eventually be spent or distributed to enhance and promote Stellar. Here is a complete list of the addresses currently associated with the SDF Mandate:

circulatingSupply The Circulating Supply is lumens in the hands of individuals and independent companies. These are lumens out in the world, used to pay network fees and fund Stellar accounts. They are also used as a general medium of exchange. We expect Stellar’s Circulating Supply to grow steadily as SDF spends and distributes lumens according to its mandate. Lumens in the Total Supply, but not in the SDF Mandate, Upgrade Reserve, or Fee Pool are assumed to be circulating.