> ## 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.

# Permissions

> tally.permissions — list active grants with caps and remaining daily allowance.

The `tally.permissions` resource exposes the active (agent, wallet, policy) grants in your account — what each agent is permitted to spend, on which wallet, with what caps, and how much daily allowance remains right now. See [Permissions (concept)](/permissions) for the model.

## Types

### `Permission`

```ts theme={null}
type Permission = {
  /** Stable cuid for this grant. */
  id: string;
  /** Agent's externalId. */
  agent_id: string;
  wallet_address: string;
  wallet_display_name: string;
  /** "active" once the wallet owner has authorized the signer on-chain;
   *  "pending" before that. */
  status: "active" | "pending";
  max_per_tx_usdc: string;
  daily_cap_usdc: string | null;
  /** USDC moved by this grant today (UTC). */
  used_today_usdc: string;
  /** daily_cap_usdc minus used_today_usdc, or null if uncapped. */
  remaining_today_usdc: string | null;
  recipient_allowlist: string[];
  contract_allowlist: string[];
  expires_at: string | null;
  created_at: string;
  activated_at: string | null;
};
```

### `PermissionListFilters`

```ts theme={null}
type PermissionListFilters = {
  /** Filter by agent externalId. */
  agent_id?: string;
  /** Max items per page. Default 50, max 100. */
  limit?: number;
};
```

## Methods

### `permissions.list(filters?)`

Returns an auto-paginating list of active grants. The result is an `AsyncResourcePage<Permission>` — iterate it with `for await`, or call `.toArray(n)` for a bounded read.

```ts theme={null}
// Iterate every grant in the account
for await (const p of tally.permissions.list()) {
  console.log(`${p.agent_id} → ${p.wallet_display_name}: $${p.remaining_today_usdc} left`);
}

// Filter by agent + cap the read
const grants = await tally.permissions.list({
  agent_id: "research-bot",
}).toArray(20);
```

**Returns:** `AsyncResourcePage<Permission>`. Each row includes today's usage so agent code can preflight a payment without re-fetching the policy bounds.

### Use cases

* **Preflight a payment** before submitting: check `remaining_today_usdc` to decide whether to attempt or skip.
* **Inventory** which agents have spending power on which wallets, e.g. for a setup script.
* **Compliance / audit**: surface all active grants in the account in one place.

## Limitations

* **Revoked grants are excluded.** Permission history is in the dashboard's per-agent audit log (or via webhooks: subscribe to `permission.revoked`).
* **Revoke and update via SDK are on the roadmap.** Both require a wallet-owner passkey signature, so the eventual SDK shape will be "server prepares → dashboard finishes," not a fully programmatic flow.

## See also

* [Permissions concept](/permissions)
* [SDK agents](/sdk/agents) — `agent.wallets[]` gives a per-agent view of granted wallets inline on the agent response.
* [SDK payments](/sdk/payments) — submit a payment that respects these grants.