> 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/sonic-token-api.md).

# SONIC Token API

Canonical public, read-only SONIC Token-2022 supply API separating initial maximum policy from verified observed total and circulating supply.

**Base path:** `/api/v1/token`\
**Authentication:** None\
**Mutation capability:** None

> **Contract vs deployment** — SONIC Tokenomics v1.0.0 defines policy constants. The API does not turn policy into observed chain state before the production mint is deployed and verified.

## Token-2022 policy context

```
standard                         Token-2022
initialMaximumSupply             18,446,000,000 SONIC
decimals                         9
atomicInitialMaximumSupply       18,446,000,000,000,000,000
launchTransferFeeBps             200
transferFeeRatePolicyCapBps      500
token2022MaximumFeeAtomic        TBA / null until deployment
productionMint                   TBA / null until deployment
```

The **2% Token-2022 transfer fee** is distinct from Marketplace, SONIC Swap, Solana network/priority and DEX/routing/provider fee domains. The **5% / 500 bps** policy cap is not the Token-2022 absolute `maximumFee` amount.

## Endpoint summary

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

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

Before production deployment:

```json
{
  "data": {
    "symbol": "SONIC",
    "initialMaximumSupply": "18446000000",
    "totalSupply": null,
    "decimals": 9,
    "unit": "SONIC",
    "status": "UNAVAILABLE",
    "deployment": "PRE_DEPLOYMENT"
  }
}
```

After deployment, `totalSupply` must be derived from the verified mint and must not exceed the initial maximum.

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

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

Every exclusion must be deterministic, documented and backed by an approved wallet/allocation registry. Until that methodology and deployment are verified, the endpoint returns `null`/`UNAVAILABLE` rather than a fabricated zero.

## Numeric precision

Use integer atomic units internally and decimal-safe strings in public JSON. With 9 decimals:

```
18,446,000,000 SONIC
= 18,446,000,000,000,000,000 atomic units
```

JavaScript floating-point values must not be the accounting authority.

## Production principle

> **The API publishes verified supply data; it does not define supply.**

Canonical policy, verified mint state, approved allocation classifications and on-chain balances remain authoritative.


---

# 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/sonic-token-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.