> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Get Total Supply \[token.getTotalSupply]

Gets the total supply of an ERC-20 token, returned in base units and human-readable form.

## Usage

This example gets the total supply of an ERC-20 token, returned in base units and human-readable form.

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const supply = await client.token.getTotalSupply({
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
// @log: { amount: 43428122000000000n, decimals: 6, formatted: '43428122000' }
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'
import { usdc } from 'viem/tokens'

export const client = Client.create({
  chain: mainnet,
  tokens: [usdc],
  transport: http(),
}).extend(publicActions())
```
:::

### Standalone Action

Call `Actions.token.getTotalSupply` directly by passing the Client as the first argument.

:::code-group
```ts twoslash [example.ts]
import { Actions } from 'viem'
import { client } from './viem.config'

const supply = await Actions.token.getTotalSupply(client, {
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
// @log: { amount: 43428122000000000n, decimals: 6, formatted: '43428122000' }
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { usdc } from 'viem/tokens'

export const client = Client.create({
  chain: mainnet,
  tokens: [usdc],
  transport: http(),
})
```
:::

## Recipes

### Format Historical Token Supply

Use `blockNumber` to read past supply state. Pass known decimals to format the amount without a separate `decimals` contract call.

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const supply = await client.token.getTotalSupply({
  blockNumber: 20_000_000n, // [!code focus]
  decimals: 6, // [!code focus]
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
}).extend(publicActions())
```
:::

## Return Value

`Amount`

The total supply as `{ amount, decimals, formatted }`, where `amount` is in base units and `formatted` is the human-readable decimal string.

## Parameters

### blockNumber

* **Type:** `bigint`

Reads the total supply at a given block number.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const supply = await Actions.token.getTotalSupply(client, {
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  blockNumber: 42069n, // [!code focus]
})
```

### blockOverrides

* **Type:** `BlockOverrides`

Overrides block fields for the contract read without changing chain state.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const supply = await Actions.token.getTotalSupply(client, {
  blockOverrides: { number: 42069n }, // [!code focus]
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
```

### blockTag

* **Type:** `'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`
* **Default:** `'latest'`

Reads the total supply at a given block tag.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const supply = await Actions.token.getTotalSupply(client, {
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  blockTag: 'safe', // [!code focus]
})
```

### decimals

* **Type:** `number`

Token decimals used to derive `formatted`. When omitted, decimals are taken from a declared token, or fetched from the contract.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const supply = await Actions.token.getTotalSupply(client, {
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  decimals: 6, // [!code focus]
})
```

### stateOverride

* **Type:** `StateOverrides`

Overrides account state for the contract read without changing chain state.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const supply = await Actions.token.getTotalSupply(client, {
  stateOverride: { // [!code focus]
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': { balance: 1n }, // [!code focus]
  }, // [!code focus]
  token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
```

### token

* **Type:** `Address | string`

The token to read: a contract `address`, or a symbol declared on the client's [`tokens`](/docs/clients/create) array.

```ts twoslash
// @noErrors
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'
import { usdc } from 'viem/tokens'

const client = Client.create({
  chain: mainnet,
  tokens: [usdc],
  transport: http(),
}).extend(publicActions())
// ---cut---
const supply = await client.token.getTotalSupply({
  token: 'usdc', // [!code focus]
})
```

## Errors

| Error | Description |
| --- | --- |
| `ContractError.ContractFunctionExecutionError` | The `totalSupply` call could not be executed. |