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

# Credits

> Purchased credit balance, top-up URL, and cursor-paginated ledger activity.

Credit routes tell an agent **how much balance remains** and **what moved
that balance**. They do not unlock articles and there is no top-up API —
send users to `topUpUrl`.

Requires `Authorization: Bearer pk_drip_…` or an MCP OAuth access token with
`mcp:unlock`. Session JWTs are rejected (`401`).

MCP: `get_credits_balance`, `list_credit_activity`.

Create a key and add balance from the
[API Keys](https://dripstack.com/dashboard/api-keys) and
[Credits](https://dripstack.com/dashboard/credits?section=topup) dashboards.

## Balance

```bash theme={null}
curl -H "Authorization: Bearer pk_drip_…" "https://dripstack.com/api/v1/me/credits"
```

```json theme={null}
{
  "purchasedBalanceUsd": 4.25,
  "lifetimePurchasedUsd": 20,
  "lifetimeSpentUsd": 15.75,
  "topUpUrl": "https://dripstack.com/pricing",
  "dashboardUrl": "https://dripstack.com/dashboard/credits"
}
```

`lifetimePurchasedUsd` is purchases and promos only — it excludes signup
grants. Call this before a paid unlock when the balance may be low. On
`403` insufficient credits, send the user to `topUpUrl` and stop.

## Ledger

```bash theme={null}
curl -H "Authorization: Bearer pk_drip_…" \
  "https://dripstack.com/api/v1/me/credits/activity?limit=20"
```

Cursor-paginated, newest first. Optional `limit` (1-50, default 20) and
`cursor` (pass the previous `nextCursor`). `nextCursor` is `null` when
exhausted. A bad `limit` returns `400` with field `issues`; an unknown
`cursor` returns `{ "error": "..." }`.

```json theme={null}
{
  "items": [
    {
      "id": "ctxn_01",
      "kind": "SPEND",
      "amountUsd": -0.5,
      "balanceAfterUsd": 4.25,
      "feature": "api-post-access",
      "description": null,
      "packageId": null,
      "promoCode": null,
      "createdAt": "2026-06-15T10:30:00.000Z"
    }
  ],
  "nextCursor": null
}
```

`kind` is one of `PURCHASE`, `SPEND`, `REFUND`, `ADJUSTMENT`, `PROMO`,
`REFERRAL`, `SIGNUP`. `amountUsd` is the signed delta. `feature` is set on
spend rows.

See [Account](/account) for who the credential is, and [Unlocks](/unlocks)
for posts this balance already paid for.