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

# Payment Card Balances

> End-of-day balances held in crypto card accounts, in USD, with holder counts and the average and median balance per holder. Each series is one card program token balance, keyed by protocol, chain, card program, token and where the balance sits (card account, lending, locked or linked account). Flow fields are null until the source carries flows by token.

One row per payment card balance, keyed by protocol, chain, card program, token and balance subtype: the parent protocol and product, chain, token and the mapped protocol, project and network records. The id is the series key of the payment-card-balances timeseries model.

| | |
| - | - |
| Access | Lending-protocols-dataset |
| Tabular model | `payment-card-balances`: primary key `id` |
| Timeseries model | `payment-card-balances`: intervals `1d`, series key `id` (Payment Card Balance ID), series must be named (up to 10 per call) |

## Endpoints

> [card] [List Payment Card Balances](https://docs.blockworks.com/api-reference/data-api/payment-cards/tabular-payment-card-balances.md)
>
> One page of rows with per-column filters, sorting and pagination.

> [card] [Batch Get Payment Card Balance timeseries](https://docs.blockworks.com/api-reference/data-api/payment-cards/timeseries-payment-card-balances.md)
>
> Up to 10 series in one request, named by Payment Card Balance ID in `series`.

> [card] [Get Payment Card Balance timeseries](https://docs.blockworks.com/api-reference/data-api/payment-cards/timeseries-payment-card-balances-by-id.md)
>
> One series over a time window, keyed by its Payment Card Balance ID.

## Metrics

7 metrics. Use the `Field` value in `selections`; every point starts with the timestamp and continues in this order.

| Field | Name | Type | Unit | Description |
| - | - | - | - | - |
| `balanceUSD` | Balance (USD) | float64 | | Balance in USD. |
| `grossInflowUSD` | Gross Inflow (USD) | float64 | | Gross inflow in USD (NULL until bwr carries flows by token). |
| `grossOutflowUSD` | Gross Outflow (USD) | float64 | | Gross outflow in USD (NULL until bwr carries flows by token). |
| `netFlowUSD` | Net Flow (USD) | float64 | | Net flow in USD (NULL until bwr carries flows by token). |
| `holders` | Holders | float64 | | Accounts holding \$1 or more. |
| `avgBalanceUSD` | Average Balance (USD) | float64 | | Average balance per holder in USD. |
| `medianBalanceUSD` | Median Balance (USD) | float64 | | Median balance per holder in USD. |

## Columns

Use the `Field` value in `selections`, `sortBy`, and as the base of a filter parameter (`Field` plus one of its `Filters` suffixes).

| Field | Type | Filters | Sort | Description |
| - | - | - | - | - |
| `id` | string | `Eq`, `IsOneOf` | | The series key of the payment-card-balances timeseries model, the parent slug, chain, program id, token address and balance subtype, joined with underscores. (primary key) |
| `name` | string | `Eq`, `IsOneOf`, `Contains` | default | The display name of the balance, the card program name, token symbol and balance subtype. |
| `slug` | string | `Eq`, `IsOneOf` | yes | The parent protocol's project slug, the slug used for the same protocol across the API. |
| `parentSlug` | string | `Eq`, `IsOneOf` | yes | The parent protocol's short name. |
| `productSlug` | string | `Eq`, `IsOneOf` | | The product or version within the parent protocol. |
| `chain` | string | `Eq`, `IsOneOf` | | The short name of the chain (ethereum, base, solana). |
| `programID` | string | `Eq`, `IsOneOf` | | The card program's identifier. |
| `tokenAddress` | string | `Eq`, `IsOneOf` | | The token contract address (the mint address on Solana); null when unlabeled. |
| `balanceSubtype` | string | `Eq`, `IsOneOf` | | Where the balance sits (card\_account, lending, locked or linked\_account). |
| `programName` | string | `Eq`, `IsOneOf`, `Contains` | | The card program's display name (for example ether.fi Cash). |
| `tokenSymbol` | string | `Eq`, `IsOneOf`, `Contains` | yes | The token's ticker symbol. |
| `protocolSlug` | string | `Eq`, `IsOneOf` | | The slug of the protocol record mapped to the product; null when unmapped. |
| `protocolName` | string | `Eq`, `IsOneOf` | | The name of the protocol record mapped to the product; null when unmapped. |
| `projectID` | string | `Eq`, `IsOneOf` | | The identifier of the parent protocol's project record; null when unmapped. |
| `networkID` | string | `Eq`, `IsOneOf` | | The chain's networkID in the blockchains model; null when unmapped. |

## Example

```bash curl theme={null}
curl "https://api.blockworks.com/query/timeseries/payment-card-balances/1d/<id>?timeframe=7d&selections=balanceUSD,grossInflowUSD" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"
```

See [Get Payment Card Balance timeseries](https://docs.blockworks.com/api-reference/data-api/payment-cards/timeseries-payment-card-balances-by-id.md) for the response and the errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.