> ## Documentation Index > Fetch the complete documentation index at: https://nevermined.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If you are an agent buying services: start with these steps. Every page has a .md version. > 1. Install the Catalog MCP (live server https://mcp.live.nevermined.app/mcp, sandbox server https://mcp.sandbox.nevermined.app/mcp; rehearse on sandbox with a sandbox API key before live, as keys work only in their own environment; Claude Code and Cursor commands, Codex config.toml entry): https://nevermined.ai/docs/products/catalog/mcp.md > 2. Get an API key: https://nevermined.ai/docs/agents-guide/get-api-key.md > 3. Enroll a card and create a delegation (a payment method plus a spend mandate: an amount, an expiry and a number of purchases): https://nevermined.ai/docs/agents-guide/enroll-card.md > 4. Buy and call a paid agent over x402: https://nevermined.ai/docs/getting-started/ai-agent-purchase.md > SDK quickstart: https://nevermined.ai/docs/integrate/quickstart/typescript.md. Pricing: https://nevermined.ai/pricing/ # Read Your Credits > Your Nevermined credits: every credit your personal account holds — free welcome credits, a Nevermined Subscription's monthly allowance and top-up credits — as one balance, subscribed or not. They are spent earliest expiry first. Charges nothing; a caller with no credits gets `total: "0"` and an empty `parts`. Always personal: an organization tag on the key and an `X-Current-Org-Id` header are ignored — but a call made in an organization never spends these credits (`BCK.SUBSCRIPTION_ROUTER.0002`), so `spendable` is what a personal key can pay with. API keys only: an OAuth-minted credential is refused (`BCK.OAUTH.0030`), even a commerce connection allowed to spend your credits. Frozen credits count in `total` but not in `spendable`. ## OpenAPI ````yaml GET /credits/balance openapi: 3.1.0 info: title: Nevermined API description: >- API for managing AI agents, payment plans, and x402 payments in the Nevermined ecosystem. ## Prerequisites You need a Nevermined API Key to authenticate. Get one at [nevermined.app](https://nevermined.app) under **Settings > API Keys**. See the [5-Minute Setup Guide](/docs/integrate/quickstart/5-minute-setup) for detailed instructions. license: name: MIT version: 1.0.0 servers: - url: https://api.sandbox.nevermined.app/api/v1 description: Sandbox (Testing) - Base Sepolia - url: https://api.live.nevermined.app/api/v1 description: Live (Production) - Base Mainnet security: - bearerAuth: [] tags: - name: Protocol - Agents description: Endpoints for registering and managing AI agents - name: Protocol - Plans description: Endpoints for creating and managing payment plans - name: Protocol - Credits description: Endpoints for minting and redeeming credits - name: Protocol - Access description: Endpoints for access tokens and request validation - name: X402 - Permissions description: Endpoints for x402 delegated permissions paths: /credits/balance: get: tags: - Router summary: Read your credits description: >- Your Nevermined credits: every credit your personal account holds — free welcome credits, a Nevermined Subscription's monthly allowance and top-up credits — as one balance, subscribed or not. They are spent earliest expiry first. Charges nothing; a caller with no credits gets `total: "0"` and an empty `parts`. Always personal: an organization tag on the key and an `X-Current-Org-Id` header are ignored — but a call made in an organization never spends these credits (`BCK.SUBSCRIPTION_ROUTER.0002`), so `spendable` is what a personal key can pay with. API keys only: an OAuth-minted credential is refused (`BCK.OAUTH.0030`), even a commerce connection allowed to spend your credits. Frozen credits count in `total` but not in `spendable`. operationId: getCreditsBalance parameters: [] responses: '200': description: The caller's credits, as a total and by kind and expiry. content: application/json: schema: $ref: '#/components/schemas/CreditsBalanceDto' '401': description: Missing/invalid Nevermined API key. content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '403': description: An OAuth-minted credential (BCK.OAUTH.0030). content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '503': description: >- The balance could not be read (BCK.CREDITS.0014) — never answered as zero. Retry. content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' components: schemas: CreditsBalanceDto: type: object properties: total: type: string description: >- Every unexpired credit, frozen ones included, as a whole-number digit string. `"0"` when there is none. example: '2000' spendable: type: string description: >- The credits that can pay a call right now: the sum of the parts that are not frozen, as a whole-number digit string. What the Router spends — read it rather than adding up your calls. example: '2000' parts: type: array description: >- The credits left, by kind, expiry and freeze, in the order they are spent: earliest expiry first, never-expiring last. Empty when there is none. items: $ref: '#/components/schemas/CreditsBalancePartDto' nextExpiry: description: >- The next credits to expire, or `null` when none of the credits left ever expires. oneOf: - $ref: '#/components/schemas/CreditsNextExpiryDto' - type: 'null' topups: description: >- Your credit top-up settings. Present when credit top-ups are available to you; absent when they are not, or when the settings could not be read this time. Top-ups are turned on and managed in the Nevermined App, not over the API. allOf: - $ref: '#/components/schemas/CreditTopupsSettingsDto' required: - total - spendable - parts - nextExpiry RouterErrorResponseDto: type: object properties: code: type: string description: >- Router error code. `BCK.ROUTER.0001` invalid request / no fundable option / bad 402 (400); `BCK.ROUTER.0002` requestId already used — idempotency conflict (409); `BCK.ROUTER.0003` delegation budget exceeded, expired, or inactive (402); `BCK.ROUTER.0004` payment record not found (404); `BCK.ROUTER.0005` payment not in a settleable state (409). Framework-level `BCK.HTTP.*` codes (e.g. `BCK.HTTP.400` request validation, `BCK.HTTP.429` throttling) may also appear — see the base `code` field. example: BCK.ROUTER.0003 httpStatus: type: number description: HTTP status code example: 500 message: type: string description: Error message for Router operations. example: delegation budget exceeded, expired, or inactive examples: - >- delegationId is required — create one via POST /api/v1/delegation/create - 'no fundable option; offered: [...]' - >- upstream pay-to address is not in this delegation's allowed recipients - delegation budget exceeded, expired, or inactive - payment already settled with a different txHash details: type: string description: >- Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise. example: Hash JWT is not signed by the node account error: type: string description: >- RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error. example: authorization_pending hint: type: string description: >- Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look. example: >- Verify the wallet has sufficient balance and that the plan is active. docsUrl: type: string description: Permalink to the docs page describing this error code. example: >- https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008 category: type: string description: >- Coarse classification of the failure, useful for client-side branching without parsing the message. enum: - validation - auth - business - integration - internal example: integration retryable: type: boolean description: >- Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way. example: true correlationId: type: string description: >- Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues. example: a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9 uuid: type: string description: >- Per-error UUID generated at construction. Useful for log correlation. example: e-550e8400-e29b-41d4-a716-446655440000 date: type: string description: ISO timestamp at which the error was constructed. example: '2026-05-09T12:34:56.789Z' format: date-time params: type: string description: >- JSON-stringified contextual parameters supplied at the throw site (e.g. IDs, state). Always a string in the wire format — parse with JSON.parse if needed. example: '{"planId":"43298432984329","reason":"Invalid configuration"}' required: - code - httpStatus - message CreditsBalancePartDto: type: object properties: kind: type: string enum: - allowance - welcome - topup - sla description: >- What the credits are: `allowance` (a Nevermined Subscription invoice; expires at the period end), `welcome` (the free sign-up grant; expires on its date), `topup` (a credit pack; never expires) or `sla` (credits Nevermined added for a defective result; expire at the period end). example: welcome credits: type: string description: >- Credits of this kind and expiry left, as a whole-number digit string. example: '2000' expiresAt: type: - string - 'null' description: When these credits expire (ISO 8601), or `null` when they never do. example: '2026-11-26T09:12:44.000Z' frozen: type: - string - 'null' enum: - renewal_overdue - dispute - null description: >- `null` when these credits can be spent. `renewal_overdue`: allowance credits, frozen until the overdue renewal payment goes through; your other credits stay spendable. `dispute`: every credit is frozen while a card dispute on a payment to Nevermined is open, or after one was decided in the cardholder's favour. required: - kind - credits - expiresAt - frozen CreditsNextExpiryDto: type: object properties: credits: type: string description: Credits that expire at `at`, as a whole-number digit string. example: '2000' at: type: string description: The earliest expiry among the credits left (ISO 8601). example: '2026-11-26T09:12:44.000Z' required: - credits - at CreditTopupsSettingsDto: type: object description: >- A personal account's credit top-up settings: a pack of never-expiring credits charged automatically when the credits run out, up to a monthly limit. Amounts are US dollars. properties: enabled: type: boolean description: >- Whether a pack is charged automatically when credits run out. Off by default; switched on by buying the first pack in the Nevermined App. example: true monthlyLimitUsd: type: - integer - 'null' description: >- The monthly limit the account set, in whole US dollars before tax, or `null` when it never set one. Kept when top-ups are switched off. example: 30 maxMonthlyLimitUsd: type: integer description: The highest monthly limit Nevermined allows, in whole US dollars. example: 50 boughtThisMonthUsd: type: number description: >- Packs bought this UTC calendar month, in US dollars before tax — every pack charged or being charged, a refunded one included. What the monthly limit counts. example: 10 packPriceUsd: type: - number - 'null' description: >- The price of one pack, in US dollars before tax: what the next pack adds to `boughtThisMonthUsd`. The lowest monthly limit is this rounded up to a whole dollar. `null` when no pack is on sale in this deployment. example: 10 paused: description: '`null` unless packs are paused, and why.' oneOf: - $ref: '#/components/schemas/CreditTopupsPausedDto' - type: 'null' card: description: The saved card that pays packs, or `null` when none is saved. oneOf: - $ref: '#/components/schemas/CreditTopupsCardDto' - type: 'null' required: - enabled - monthlyLimitUsd - maxMonthlyLimitUsd - boughtThisMonthUsd - packPriceUsd - paused - card CreditTopupsPausedDto: type: object properties: reason: type: string enum: - payment_failed - action_required - card_unavailable - dispute description: >- `payment_failed`: the last automatic pack was declined. `action_required`: its card asked for authentication. `card_unavailable` (API version 1.84 or later; older versions read `payment_failed`): the card that pays packs can no longer pay (removed, or no longer usable); choosing another card lifts it. Buying a pack lifts any of these. `dispute`: a card dispute on a credit top-up pack is open, or was decided in the cardholder's favour — every credit is frozen and no pack is charged. A dispute on the subscription also freezes every credit (`frozen: dispute` on the parts) but leaves `paused` at `null`. example: payment_failed since: type: string description: Since when (ISO 8601). example: '2026-10-19T10:00:00.000Z' required: - reason - since CreditTopupsCardDto: type: object properties: brand: type: string description: The saved card's brand, as Stripe names it. example: visa last4: type: string description: The saved card's last four digits. example: '4242' required: - brand - last4 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Nevermined API Key (starts with 'nvm:'). Get one at [nevermined.app](https://nevermined.app) under **Settings > API Keys**. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.