---
name: bijection-wallet
description: "Evaluate and integrate the Wallet component with Bijection."
---

# Wallet

Consumable balances and economy ledger with atomic spend and lazy regen, as a Bijection component

- Package: @bijectionhq/wallet
- Category: Payments
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/wallet/tree/86623289d0d8346f17c35e43618569181392c135
- Upstream: https://github.com/vllnt/convex-wallet/tree/89dde0e3e0ee3a5b9f73f2dce19f790cd0741a62
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/wallet

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/wallet.git
cd wallet
git checkout 86623289d0d8346f17c35e43618569181392c135
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @vllnt/convex-wallet. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Wallet & Ledger. Follow the installation and configuration steps exactly.

# Wallet & Ledger

## Instructions

@vllnt/convex-wallet stores consumable balances and a ledger of value changes. Currency names and subject references come from your application, so a balance can represent credits, energy, points, or another unit.

Configure currencies and ceilings, then grant, earn, spend, or transfer amounts. Spending checks available balance atomically. Idempotency keys protect supported grant and spend paths, and history records deltas and reasons. Optional regeneration calculates replenishment from server time without a periodic refill job.

The host authenticates callers, verifies purchases, and controls every credit and debit. This is not a payment processor, bank account, or subscription system. UI, pricing, reward eligibility, and external payment reconciliation stay in your app.

Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).

### Installation

```bash
npm install @vllnt/convex-wallet
```

Current npm version: `@vllnt/convex-wallet@0.1.0`

## Use cases

- AI products: grant credits after a verified purchase and spend them on generation.
- Mobile games: maintain coins or energy, with optional time-based regeneration.
- Reward programs: credit participation points and debit them when the host approves a redemption.
- Team tools: manage workspace balances for exports or processing operations.

## How it works

Configure currencies and ceilings, then grant, earn, spend, or transfer amounts. Spending checks available balance atomically. Idempotency keys protect supported grant and spend paths, and history records deltas and reasons. Optional regeneration calculates replenishment from server time without a periodic refill job.

The host authenticates callers, verifies purchases, and controls every credit and debit. This is not a payment processor, bank account, or subscription system. UI, pricing, reward eligibility, and external payment reconciliation stay in your app.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Wallet & Ledger is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-wallet)
- [GitHub repository](https://github.com/vllnt/convex-wallet)
- [Live demo](https://vllnt.com/)
- [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-wallet)
- [Convex documentation](https://docs.convex.dev)