> ## 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.

# Scopes

> Every Blank API v2 scope, the operations it unlocks, and how scope enforcement works.

# Scopes

Every protected operation in API v2 declares the scopes it requires. A request is authorized only when the calling key carries **every** declared scope. Missing any one of them returns `403 insufficient_scope`.

Scopes are selected when the key is created and **cannot be widened afterwards**. Grant the narrowest set that works, and create a separate key when a new service needs more.

## Scopes in use

These scopes gate operations in the current contract.

| Scope                  | Unlocks                                                              | Operations                                                                                                                |
| ---------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `fees:read`            | Fee state and distribution history                                   | `getTokenFeeState`, `listTokenFeeDistributions`                                                                           |
| `staking:read`         | Your own staking positions                                           | `listOwnedStakingPositions`                                                                                               |
| `presales:read`        | Your own presale participation                                       | `getPresaleParticipation`                                                                                                 |
| `predictions:read`     | Prediction eligibility and your own predictions                      | `getPredictionEligibility`, `getOwnedPrediction`                                                                          |
| `predictions:write`    | Submitting a price prediction                                        | `createPrediction`                                                                                                        |
| `predictions:delegate` | Preparing and submitting wallet-authorized predictions for end users | `createDelegatedPredictionIntent`, `createDelegatedPrediction`                                                            |
| `operations:read`      | Async operation and transaction-intent status                        | `getOperation`, `getTransactionIntent`                                                                                    |
| `transactions:write`   | Submitting a signed transaction intent                               | `submitTransactionIntent`                                                                                                 |
| `webhooks:read`        | Reading endpoints and delivery history                               | `listWebhookEndpoints`, `getWebhookEndpoint`, `listWebhookDeliveries`                                                     |
| `webhooks:write`       | Managing endpoints, secrets, and replays                             | `createWebhookEndpoint`, `updateWebhookEndpoint`, `deleteWebhookEndpoint`, `rotateWebhookSecret`, `replayWebhookDelivery` |

## Scopes with no current operations

The contract also defines these scope values, and the Blank dashboard lets you select them, but **no operation in the current API v2 contract requires them**. Granting one today adds no capability.

`tokens:read`, `market-data:read`, `launches:read`, `launches:write`, `trading:write`, `staking:write`, `fees:write`, `presales:write`, `token-management:write`, `audience:read`

<Note>
  Token and market-data reads are anonymous, so `tokens:read` and
  `market-data:read` are not needed to call them. Leave these scopes unselected
  unless a future operation documents a requirement for one.
</Note>

## Operations that need no scope

* **Anonymous operations** need no key at all: token list and detail, market snapshot, candles, trades, holder stats, staking pool and leaderboard, presale list and detail, prediction rounds, round entries, standings, and the Solana manifest.
* **`getApiIdentity` (`GET /me`)** requires a valid key but no scope. It returns only the calling key's own identity.

## Recommended scope sets

| Integration                           | Scopes                                                                     |
| ------------------------------------- | -------------------------------------------------------------------------- |
| Public dashboard or price display     | none — use anonymous reads                                                 |
| Fee and revenue reporting             | `fees:read`                                                                |
| Portfolio tracker for your own wallet | `staking:read`, `presales:read`, `fees:read`                               |
| Prediction bot                        | `predictions:read`, `predictions:write`                                    |
| Prediction bot with event delivery    | `predictions:read`, `predictions:write`, `webhooks:read`, `webhooks:write` |
| End-user prediction integration       | `predictions:delegate`                                                     |
| Wallet-signed automation              | `operations:read`, `transactions:write`                                    |

## Checking your scopes at runtime

```ts theme={null}
const identity = await blank.identity.me();

const required = ["predictions:read", "predictions:write"];
const missing = required.filter(
  (scope) => !identity.data.scopes.includes(scope)
);

if (missing.length > 0) {
  throw new Error(`Blank API key is missing scopes: ${missing.join(", ")}`);
}
```

Failing on boot is better than discovering a missing scope on your first write.

## Scope failures

```json theme={null}
{
  "type": "https://blank.build/docs/reference/errors#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "The API key does not grant every scope required by this operation.",
  "instance": "/api/v2/predictions",
  "code": "insufficient_scope",
  "requestId": "req_0123456789abcdef0123456789abcdef"
}
```

`insufficient_scope` is not retryable. Create a new key with the required scopes — an existing key cannot be upgraded. See [Authentication](/docs/for-developers/authentication) and [Errors](/docs/reference/errors).