Wallets

Agent wallets are programmable accounts that hold USD stablecoins with policy-controlled spending.

Overview

Every AI agent in Wallgent gets a wallet -- a programmable account that holds USD-denominated funds. Under the hood, each wallet maps one-to-one with a LIABILITY account in the double-entry ledger.

Data Model

Field	Type	Description
`id`	`text`	Unique identifier (`wal_<ulid>`)
`organizationId`	`text`	Owning organization
`accountId`	`text`	Linked ledger account (1:1)
`environment`	`enum`	`SANDBOX` or `PRODUCTION`
`name`	`varchar(256)`	Human-readable name
`agentName`	`varchar(256)`	Agent identifier
`metadata`	`jsonb`	Arbitrary key-value data

Creating Wallets

import { Wallgent } from '@wallgent/sdk';

const wg = new Wallgent('wg_test_abc123');

const wallet = await wg.wallets.create({
  name: 'Shopping Agent',
  agentName: 'shopper-v2',
  metadata: { team: 'commerce' },
});

When you create a wallet, the API:

Creates a new LIABILITY account in the ledger
Links the wallet record to that account
Applies the environment from your API key (sandbox keys create sandbox wallets)

Funding

Wallets are funded by transferring from the system Treasury account:

await wg.wallets.fund(wallet.id, {
  amount: '500.00',
});

This creates a ledger transaction: debit Treasury (ASSET), credit the wallet's account (LIABILITY).

Balance Queries

const balance = await wg.wallets.getBalance(wallet.id);
// { available: "500.00", currency: "USD" }

The balance is cached on the account record and updated atomically with every entry. A reconciliation script can verify cached balances against the sum of entries.

Environment Isolation

Wallets are scoped to environments. A SANDBOX API key can only access SANDBOX wallets. A PRODUCTION key can only access PRODUCTION wallets. The API middleware enforces this -- a mismatch returns HTTP 403.

Listing and Filtering

const wallets = await wg.wallets.list();
// Returns paginated results with cursor-based pagination
// { data: Wallet[], cursor?: string, hasMore: boolean }