> ## Documentation Index
> Fetch the complete documentation index at: https://blank.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fees

> Read a token's fee configuration and its distribution history with an API key.

# Fees

Two operations, both read-only, both requiring an API key with the `fees:read` scope.

| Operation                   | HTTP                                   | SDK                                     | Scope       |
| --------------------------- | -------------------------------------- | --------------------------------------- | ----------- |
| `getTokenFeeState`          | `GET /tokens/{mint}/fees`              | `blank.fees.state(mint)`                | `fees:read` |
| `listTokenFeeDistributions` | `GET /tokens/{mint}/fee-distributions` | `blank.fees.distributions(mint, query)` | `fees:read` |

Neither response is cached. Both send `private, no-store` and use the `api-key-read` rate policy described in [Conventions](/docs/for-developers/conventions).

## Setup

API keys are **server-side only**. The SDK refuses to accept one in a browser runtime.

```ts theme={null}
import { BlankClient } from "@blankdotbuild/sdk";

const blank = new BlankClient({ apiKey: process.env.BLANK_API_KEY });
```

See [Authentication](/docs/for-developers/authentication) for key handling and [Scopes](/docs/for-developers/scopes) for the scope list.

## Fee state

The current fee configuration and lifetime totals for one token.

```ts theme={null}
const { data: fees } = await blank.fees.state(mint);

console.log(fees.sharesBps.creator, fees.totalDistributedInSol);
```

| Field                   | Type             | Notes                                              |
| ----------------------- | ---------------- | -------------------------------------------------- |
| `mintAddress`           | string           |                                                    |
| `controllerWallet`      | string           | The wallet that controls the token's fee settings. |
| `sharesBps`             | object           | Basis-point allocations. See below.                |
| `totalDistributedInSol` | decimal string   | Lifetime SOL distributed.                          |
| `lastDistributionAt`    | RFC 3339 \| null | Null if nothing has been distributed yet.          |

### sharesBps

An object with five integer keys, each 0–10,000 basis points: `creator`, `staking`, `buybackBurn`, `liquidityCompounding`, `forecast`.

<Note>
  100 bps = 1%, so 10,000 bps = 100%. A `staking` value of `2000` means 20%.
</Note>

## Distribution history

Individual fee distributions, newest first, cursor paginated with `cursor` and `limit`.

```ts theme={null}
const { data } = await blank.fees.distributions(mint, { limit: 50 });

for (const distribution of data.data) {
  console.log(distribution.recipient, distribution.amountInSol);
}
```

| Field                  | Type                                  | Notes                                         |
| ---------------------- | ------------------------------------- | --------------------------------------------- |
| `id`                   | uuid                                  |                                               |
| `feeType`              | `creation` \| `trade` \| `graduation` | What generated the fee.                       |
| `recipient`            | `platform` \| `creator` \| `staking`  | Which bucket received it.                     |
| `amountInSol`          | decimal string                        | Parse with a decimal library, never `Number`. |
| `transactionSignature` | string \| null                        | Null until the on-chain transfer is recorded. |
| `slot`                 | numeric string \| null                |                                               |
| `collectedAt`          | RFC 3339                              |                                               |

The response is `{ data: [...], page: { nextCursor, hasMore } }`. Pass `page.nextCursor` back as `cursor` to walk further.

## Raw HTTP

From a server shell, never a browser:

```bash theme={null}
curl -sS \
  -H "Authorization: Bearer $BLANK_API_KEY" \
  "https://api.blank.build/api/v2/tokens/$MINT/fee-distributions?limit=50"
```

<Warning>
  An API key grants read access to your Blank account. Keep it in server
  environment variables. Never ship it to a client, a mobile app bundle, or a
  public repository.
</Warning>

## Reads only

The v2 API exposes fee **reads**. There is no public fee-claim endpoint.

* **Creators** claim from the Blank creator dashboard.
* **Stakers** claim through staking flows.
* **The platform bucket** is collected by Blank's keeper.

See [Fee Structure](/docs/start-here/fees) for how the fee model works.

## Errors

| Code                 | Status | Meaning                                                       |
| -------------------- | ------ | ------------------------------------------------------------- |
| `invalid_api_key`    | 401    | The key is missing, unknown, revoked, or expired.             |
| `insufficient_scope` | 403    | The key lacks `fees:read`.                                    |
| `token_not_found`    | 404    | No token for that mint.                                       |
| `cursor_invalid`     | 400    | The cursor is malformed or no longer valid. Restart the walk. |

Full problem-details shape lives in [Errors](/docs/reference/errors).

## Next

* [Staking](/docs/for-developers/developer-staking) — pool state, leaderboard, your positions.
* [Tokens and Market Data](/docs/for-developers/market-data) — anonymous public reads.