Methodology

How usdc.cool tracks the USDC supply using only on-chain data

usdc.cool strives to provide the most accurate, comprehensive picture of the USDC supply across all chains and bridges ‐ while using only on-chain data.

By the end of this article, you should be able to answer some of the most common questions I get, such as:

• “How do you calculate the USDC supply?”
• “How do you calculate bridged USDC supply?”
• “Why is your total different from what Circle shows?”
• "Why should I trust you?"
• “Why does your total show $X million less than etherscan?”

Here’s how the data is calculated:

TL;DR

All of this data is verifiable on chain, and every relevant address is provided on the site. The simplified formulas for calculating supply look like this:

Total USDC overall:

This total intentionally does not include any bridge calculations, because all bridged USDC must be backed by native USDC.

Total USDC on a chain:

Total USDC on a chain, including bridges:

100% on-chain data

Before we begin, I should mention a guiding principle: As a rule, all data on usdc.cool comes directly from on-chain sources. This allows the calculations to be verifiable, reproducible and tamper-proof, while also providing technical redundancy.

In fact, the first version of usdc.cool didn’t have a backend, and it fetched directly from the blockchains from your browser when you loaded the page.

Calculating native USDC supply

First, let’s talk about how Circle issues USDC. In a simplified form: someone gives Circle $1, and Circle gives that person 1 USDC token. When the person wants to cash out, they can give Circle their 1 USDC token, and Circle will give them $1.

So, you could reasonably assume that the total amount of USDC issued is the same as the total number of "minted" tokens. Unfortunately, it’s more complex than that, but that’s where we’ll start.x

Token Supply

First, we look at how many USDC tokens have been minted on each chain. For ERC-20 tokens, this is the totalSupply() method of the token.

This is the value displayed on Block Explorers, like Etherscan and others. However, it is often NOT an accurate representation of the supply of USDC on that chain. As you’ll see in the following sections, this value is often much larger than the true amount of USDC on that chain.

For our equation, let’s call this value Token Supply.

Treasury (Pre-Mint) accounts

On several chains, USDC will be “pre-minted” on the blockchain before being officially issued. This pre-mint process serves the same purpose as minting/burning but can be more efficient for the issuer (Circle) in certain scenarios, such as managing gas fees or network congestion.

However, doing this means the Token Supply on a chain (and on block explorers) will be larger than the actual amount of issued USDC. As an example, there is over 18 Trillion USDC pre-minted on Algorand.

The pre-minting process is as follows:

• The issuer (Circle) will “mint” a large amount of the USDC token on a chain before any customer demand for the token.
• This balance will be held in a “treasury” account (a.k.a pre-mint account, minter account) awaiting customer demand.
• When a customer buys USDC from the issuer (Circle), instead of minting new tokens on chain, the issuer transfers from these reserves.
• The same is true in reverse. Instead of “burning” a token when it is redeemed, the issuer (Circle) will keep it in their treasury for future use.

Therefore, on chains like these, transfers from the treasury accounts are how the token is issued. If the treasury reserves get too low, the issuer (Circle) will pre-mint another chunk.

To calculate this balance, we sum the balances of all treasury (pre-mint) accounts on a given chain (there can be multiple per chain). For our calculation, we can call this the Treasury Balance.

This value is subtracted from the Token Supply value, so now our equation is:

Banned Addresses

Occasionally, whether via law enforcement requirement or other, certain addresses can be marked as “banned” by the issuer, preventing that address from sending or receiving USDC. This means any USDC held in that address is effectively removed from the circulating supply: it can not be transferred anymore.

Calculating the total amount of “banned” USDC poses a bit of a challenge, because the USDC itself is not banned — instead, the Address is banned.

Banning an address is a separate process that is not associated with a mint or transfer. This means we have to listen to all on-chain events emitted from the USDC contract, listening for a Blacklisted event, and calculating their USDC balance at the time of that event.

Because this “Banned USDC” is removed from circulating supply (it can no longer be transferred), we should also subtract this value from the total supply. To do this, we must sum the USDC balance of all banned addresses and subtract it from our balance.

Our formula is now:

Native issuance

At this point we now have an accurate picture of the officially issued USDC on a chain.

As you may have noticed, we have not yet considered “Bridged” USDC as part of this calculation. Bridged USDC does not contribute to the Total USDC calculation because all bridged USDC must be backed by natively-issued USDC.

Instead, Bridged USDC subtracts from one chain while adding an equal value on a separate chain.

Bridges

The full picture of USDC can’t be painted with native USDC alone. A significant amount of USDC activity occurs via Bridged USDC.

It is worth emphasizing: bridged USDC calculations have no bearing on the overall USDC supply. All bridged USDC should be backed by a native USDC, which is used to calculate the total.

How does Bridged USDC work?

When users want USDC on a chain that the issuer (Circle) has not yet officially supported, developers will “bridge” USDC to that chain.

The process of bridging can be complex, but a simplified version of the flow can look like this:

A user wants to bridge 1 USDC from Ethereum to a new chain, Chain X.

1. The user sends 1 native USDC to a Bridge contract on Ethereum.
2. The Bridge contract holds that native USDC on Ethereum (essentially a “treasury” balance for the bridge, as described in the “pre-mint” section above).
3. An off-chain process is watching for this, and triggers a mint on Chain X
4. On Chain X, the bridge contract “mints” a new token (often called USDC.e to represent that it came from Ethereum) to the user’s address on Chain X.

At this point there is 1 native USDC sitting in the Bridge contract on Ethereum, and 1 USDC.e on Chain X.

Calculating bridge supply

Calculating the bridged supply of USDC is a multi-step process involving source and destination chains.

Source (“originating”) chain

To begin, we need to find the amount of USDC bridged “out” using a given bridge contract. Because tokens never leave the chain they were minted on, the token will sit in a bridge’s “treasury” account.

We can find that balance for each bridge on a chain (the “bridged out” balance) and subtract it from the chain’s current USDC supply.

Destination chain

On the destination chain, we start with the total minted supply for the bridge token (the amount “bridged in”). However, USDC bridged in to this chain can also be bridged out to a 3rd chain, and beyond. For example, native USDC issued on Ethereum can be bridged to Arbitrum, and bridged from Arbitrum to Lyra or Aptos.

To calculate the accurate total for this bridge, we need to recursively check how much of this new token was minted, and how much of the minted token was bridged out to another chain. This is similar to the native USDC calculation, but in this case the “issuer” would be the bridging service.

With this, our formula now becomes:

Once we calculate this for each bridge on each chain, including cases where a token is bridged to more than one chain, we have a complete picture of the USDC supply across bridges.

Multi-chain bridges

Some bridging services allow bridging to and from several chains. Wormhole is a good example of this. These cases can be slightly more complex, but once we calculate both sides (in and out) of these bridges on all chains, the values will offset where necessary and the data falls into place.

Bridge discrepancies

Because our formula tracks the bridged-in and bridged-out balances for each bridging service, we can use it to verify that each bridge is acting properly. For example, it will be clear if the bridge minted more than it should. In this case, the bridge will be flagged on usdc.cool.

CCTP

Because trusting Bridges can be risky, Circle offers the Cross Chain Transfer Protocol (CCTP) on several chains. While similar to a bridge, CCTP is actually native minting and burning the official USDC on supported chains.

It operates the same as native issuance and redemption, and is therefore automatically captured in our supply calculations and does not need any special treatment.

Errors

While usdc.cool strives for perfection, there is a chance the data is not perfect. Here are some example error scenarios:

• Occasionally chains go down, or requests to RPC providers can fail.
  • In case of RPC failure, we can failover to fallback RPCs.
  • If the requests continue to fail (e.g. chain-level error), we can use the previous successful balance check for that chain. In this case, the data appears slightly outdated, but not incorrect.
• New chains: When Circle launches native USDC on a new chain, it may take several hours before it is supported on usdc.cool.
• New pre-mint addresses: When Circle adds a new pre-mint address for a chain, there may be a time delay before it is supported on usdc.cool. During this time, the chain’s balance may appear elevated. This is rare, however, as Circle usually publishes their pre-mint addresses long before using them.

Built by a fan

And remember, usdc.cool is a labor of love by @mattyven. If you find the service useful, please let me know!

Or if you find any errors on the site, please report them to @usdc_cool or @mattyven on X, or email at hello@usdc.cool.