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

# Wallets

> tally.wallets — list and provision wallets in your account.

The `tally.wallets` resource manages wallet provisioning + discovery. See [Wallets (concept)](/wallets) for the model.

## Types

### `Wallet`

```ts theme={null}
type Wallet = {
  /** Stable Tally cuid. Use as `wallet_id` to permission routes (grant,
   *  edit, revoke). */
  id: string;
  /** EVM address. Use as `wallet` in `tally.payments.create({ wallet })`. */
  address: string;
  /** Friendly name set when the wallet was created. */
  display_name: string;
  /** Optional role label (e.g., "treasury", "ops"); null if unset. */
  role_label: string | null;
  mode: "test" | "live";
  /** ISO 8601 timestamp. */
  created_at: string;
};
```

### `WalletCreateInput`

```ts theme={null}
type WalletCreateInput = {
  /** Human-friendly name. 1–60 chars after trimming. */
  display_name: string;
  /** Optional role label (1–40 chars after trimming). */
  role_label?: string;
};
```

## Methods

### `wallets.list()`

Returns every wallet in the API key's account + mode, oldest-first. The "Main Wallet" auto-provisioned at sign-in shows up first.

```ts theme={null}
const wallets = await tally.wallets.list();

for (const w of wallets) {
  console.log(`${w.display_name} (${w.role_label ?? "—"}): ${w.address}`);
}
```

**Returns:** `Promise<Wallet[]>`. Empty array if the account has no wallets in this mode (rare — sign-in always provisions a Main Wallet, but possible if all wallets were created in the *other* mode).

### `wallets.create(input)`

Provisions a new Privy server wallet in the API key's account + mode. Owned (in Privy) by the oldest `owner`-role member of the account, so any future signer changes go through the same passkey as dashboard-created wallets.

```ts theme={null}
const wallet = await tally.wallets.create({
  display_name: "Treasury",
  role_label: "ops",
});

console.log(`Created ${wallet.address}`);
```

**Parameters**

| Field                | Type                  | Description                                                   |
| -------------------- | --------------------- | ------------------------------------------------------------- |
| `input.display_name` | `string`              | Friendly name. 1–60 chars after trimming.                     |
| `input.role_label`   | `string \| undefined` | Optional label, e.g. `"treasury"`. 1–40 chars after trimming. |

**Returns:** `Promise<Wallet>`. The new wallet is empty — fund it via the dashboard's wallet detail page or by sending USDC directly to `wallet.address`.

## Errors

* `ValidationError (400)` — `display_name` is missing or out of range (1–60 chars after trim).
* `RateLimitError (429)` — hit the per-API-key rate limit (60/min default).
* `TallyError (500/502)` — Privy wallet provisioning failed. Retry idempotently after a backoff.

See [SDK errors](/sdk/errors) for the typed exception hierarchy.

## See also

* [Wallets concept](/wallets) — the model + why wallets are account-scoped, not agent-scoped.
* [`tally.payments.create()`](/sdk/payments) — send USDC from a wallet via an agent's granted permission.
* [Agent wallets](/sdk/agents) — `agent.wallets[]` gives you the spendable wallets per agent inline.