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

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.

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

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

{
  "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 and Errors.

Start Here

Features

For Developers

Reference

API Reference

Endpoints

Scopes

Scopes

Scopes in use

Scopes with no current operations

Operations that need no scope

Recommended scope sets

Checking your scopes at runtime

Scope failures

​Scopes

​Scopes in use

​Scopes with no current operations

​Operations that need no scope

​Recommended scope sets

​Checking your scopes at runtime

​Scope failures

Scopes

Scopes in use

Scopes with no current operations

Operations that need no scope

Recommended scope sets

Checking your scopes at runtime

Scope failures