> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/solana-and-sonic-token/token-supply-api.md).

# Token Supply API

Public, read-only SONIC supply endpoints for websites, explorers, analytics providers, exchanges and token trackers.

> **Pre-deployment contract** — SONIC has an approved **initial maximum supply of 18,446,000,000 SONIC** and **9 decimals**, but no production mint is yet published. Observed total and circulating supply therefore remain unavailable until deployment verification.

## Endpoints

| Method | Endpoint                           | Auth | Purpose                                      |
| ------ | ---------------------------------- | ---- | -------------------------------------------- |
| `GET`  | `/api/v1/token/total-supply`       | None | Verified observed SONIC total supply         |
| `GET`  | `/api/v1/token/circulating-supply` | None | Verified calculated circulating SONIC supply |

## Initial maximum policy

```
initialMaximumSupply       18,446,000,000 SONIC
decimals                   9
atomicInitialMaximumSupply 18,446,000,000,000,000,000
```

The initial maximum is a policy ceiling. It is not a substitute for observed mint supply.

## GET `/api/v1/token/total-supply`

### Pre-deployment

```json
{
  "data": {
    "symbol": "SONIC",
    "initialMaximumSupply": "18446000000",
    "totalSupply": null,
    "decimals": 9,
    "unit": "SONIC",
    "status": "UNAVAILABLE",
    "deployment": "PRE_DEPLOYMENT"
  },
  "meta": {
    "network": "solana-mainnet-beta",
    "source": "canonical-token-policy"
  }
}
```

### Verified production

After the mint is verified, `totalSupply` is returned as a decimal-safe string derived from the production mint. It must satisfy:

```
0 ≤ observedTotalSupply ≤ 18,446,000,000 SONIC
```

Burns may reduce observed total supply. The API must not force observed total supply back to the initial maximum.

## GET `/api/v1/token/circulating-supply`

Circulating supply is derived from verified allocation and account state:

```
circulatingSupply =
  observedTotalSupply
  - lockedSupply
  - vestingExcludedSupply
  - treasuryExcludedSupply
  - reserveExcludedSupply
  - otherApprovedNonCirculatingSupply
```

Until the deployment and circulation methodology are verified:

```json
{
  "data": {
    "symbol": "SONIC",
    "circulatingSupply": null,
    "unit": "SONIC",
    "status": "UNAVAILABLE",
    "methodologyStatus": "DRAFT"
  }
}
```

## Token-2022 fee context

Supply endpoints do not calculate transaction fees, but token metadata/status should expose:

```
launchTransferFeeBps          200
transferFeeRatePolicyCapBps   500
token2022MaximumFeeAtomic     TBA / null until deployment
```

The Token-2022 transfer fee is separate from Marketplace, SONIC Swap, Solana network/priority and DEX/routing/provider fees.

## Implementation contract

* use integer atomic units internally;
* use `bigint`, `Decimal`, or equivalent arbitrary-precision arithmetic;
* never use JavaScript floating-point arithmetic for token accounting;
* keep Solana RPC keys and provider credentials server-side;
* reconcile observed total supply against the verified mint;
* enforce the initial maximum as a policy ceiling, not as a fabricated live supply number;
* calculate circulating supply from the approved exclusion registry;
* return decimal-safe strings for available token quantities;
* expose unavailable/null states when required evidence is missing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/solana-and-sonic-token/token-supply-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.