Overview
Closed-loop, dollar-denominated wallets for AbsoluteJS applications. Balances are integer cents, every movement is a balanced journal transaction, retries are idempotent, and bids/auctions reserve funds before settlement.
Wallet
@absolutejs/walletv0.9.3betaCommerce & GrowthProvider-agnostic, double-entry dollar wallets with reservations, idempotent settlement, and closed-loop marketplace policy for AbsoluteJS apps.
#Installation
BASH
bun add @absolutejs/wallet#Capabilities
Overview
Closed-loop, dollar-denominated wallets for AbsoluteJS applications. Balances are integer cents, every movement is a balanced journal transaction, retries are idempotent, and bids/auctions reserve funds before settlement.
The bundled policy starts with the AbsoluteJS marketplace decisions: USD display, $5 minimum funding, $2,000 maximum balance, $1,800 maximum transaction, 10% seller-paid market fee, and a $0.25 fee per direct-trade participant.
The package does not process cards, custody crypto, or promise cash redemption. Payment adapters fund the clearing side of a journal entry after a verified webhook; applications provide a transactional persistent WalletStore for production. For Bun/PostgreSQL hosts, pass one createBunSqlWalletClient(sql) instance to both PostgreSQL stores. Its async transaction context makes nested core Wallet operations join the allowance transaction, including with a one-connection pool.
Agent allowances
createAgentWallet grants an agent narrowly bounded spend authority: per-item, daily, weekly, and lifetime caps; merchant/category/action allowlists; expiry; refundability; and a maximum number of open reservations. Requests reserve the exact amount and produce a signed mandate bound to the merchant, cart hash, currency, amount, agent, allowance, reservation, and expiration.
Amounts above autoApproveUpToCents become an @absolutejs/agency action. Capture cannot proceed until current policy accepts the approval, and it then executes through a single-use agency lease. The model never receives a raw balance mutation tool.
Agency is a required host peer (>=0.7.1 <0.8.0) and is externalized from the Wallet build. Allowances and every other agent surface therefore share the host's one approval ledger. This package tests against exactly 0.7.1; a new Agency minor requires an explicit compatibility release.
Show 3 more
External provider effects use captureExternalSpend() only after the provider has succeeded or conclusive reconciliation evidence proves it succeeded. The purchase atomically captures the exact reservation into a provider clearing account and binds retries to the provider and payment reference. A successfully compensated provider effect uses refundExternalSpend() to reverse that exact journal boundary; both operations are safe to retry after a host crash.
The package also exports structural AP2 intent/payment mandate adapters and a UCP extension payload. Those evolving protocols remain adapters; the wallet's allowance and accounting contracts do not depend on them.
walletPostgresSchemaSql() supplies a production PostgreSQL journal with a deferred database constraint that rejects unbalanced transactions at commit.
Outcomes
What you can build
Agent allowances
createAgentWallet grants an agent narrowly bounded spend authority: per-item, daily, weekly, and lifetime caps; merchant/category/action allowlists; expiry; refundability; and a maximum number of open reservations. Requests reserve the exact amount and produce a signed mandate bound to the merchant, cart hash, currency, amount, agent, allowance, reservation, and expiration.
Hardening checklist
Production guidance
Make every external boundary explicitPin the deployed @absolutejs/wallet version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.
Follow in order
Troubleshooting path
1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/wallet example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.
#@absolutejs/wallet quick start
Partial snippet# @absolutejs/wallet
TS
import { createMemoryWalletStore, createWallet } from "@absolutejs/wallet";
const wallet = createWallet(createMemoryWalletStore());
await wallet.createAccount("user_123");#Public entry points
Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.
Public package entry point declared in package.json.
@absolutejs/wallet@absolutejs/wallet/manifest@absolutejs/wallet/manifest.json
#Package commands
Scripts declared by this project’s package manifest.
bun run buildrm -rf dist && bun build src/index.ts src/manifest.ts --root ./src --outdir dist --sourcemap --target=bun --external @absolutejs/agency --external '@absolutejs/agency/*' --external drizzle-orm --external 'drizzle-orm/*' && tsc --project tsconfig.build.json && absolute-manifest emit
bun run check:packagebun run typecheck && bun run test && bun run build
bun run testbun test
bun run typechecktsc --noEmit
#API reference
Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.
50 symbols