---
title: "Get net balance, promotional grants, and approved credit"
method: GET
path: "/api/v1/chat/credit"
tags: ["Account"]
---

# Get net balance, promotional grants, and approved credit

`GET /api/v1/chat/credit`

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/api/v1/chat/credit`
- Auth: HTTP bearer

## Response `200`

Net available, held, and total balances plus funding sources in USD decimal strings. Unused credit is separate from wallet funds; model-scoped grants may not pay for every request.

- BalanceEnvelope
  - `code` 200, required
  - `msg` 'success', required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` Balance, required
    - `funding` FundingOverview
      - `balanceUsd` string, required: Net wallet available balance; may be negative for approved credit consumption or external payment recovery.
      - `heldUsd` string, required
      - `prepaidAvailableUsd` string, required: Unrestricted prepaid or legacy available funds.
      - `grantAvailableUsd` string, required: Active available grants; model applicability is checked at task admission.
      - `cashShortfallUsd` string, required: External payment recovery shortfall that cannot be covered by grants or credit.
      - `credit` CreditFacilityItem, required
        - `enabled` boolean, required
        - `limitUsd` string, required: Approved ceiling, not wallet funds.
        - `availableUsd` string, required
        - `usedUsd` string, required: Outstanding settled principal.
        - `heldUsd` string, required: Credit reserved for accepted tasks.
        - `expiresAt` string, date-time, nullable
        - `status` string, required
        - `version` integer, required
      - `grants` FundingGrantItem[], required
        - `id` string, required
        - `name` string, required
        - `amountUsd` string, required
        - `availableUsd` string, required
        - `heldUsd` string, required
        - `spentUsd` string, required
        - `status` string, required
        - `startsAt` string, date-time, required
        - `expiresAt` string, date-time, nullable
        - `modelSlugs` string[], required: Empty means all models.
        - `customerMemo` string, required
        - `createdAt` string, date-time, required
      - `grantsHasMore` boolean, required
    - `available` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
    - `held` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
    - `total` string, required: Decimal USD amount encoded as a string to avoid binary floating-point loss.
    - `availableCredits` integer, required: Credits you can spend now (the same amount as `available`, rounded down to a whole credit).
    - `heldCredits` integer, required: Credits held by accepted tasks that have not settled yet.
    - `totalCredits` integer, required: `availableCredits` + `heldCredits`.

## Other responses

- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `403`: Account, model, API-key, IP, or region authorization failed.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.

## Changes

- **2026-10-20** `fede911a6e9b`: 48 warning
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `401`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `403`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `429`
  - added the new `agent_project_budget` enum value to the `allOf[subschema #2]/data/reason` response property for the response status `500`
  - …44 more

[Operation history](https://skmtc.dev/popnow/apis/popnow-api/changes/api/v1/chat/credit/get.md)

---

[API](https://skmtc.dev/popnow/apis/popnow-api.md) · [All operations](https://skmtc.dev/popnow/apis/popnow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/popnow/apis/popnow-api/revisions/fede911a6e9b?raw)