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

# Agents & Wallets

> Every agent in Payzor has an identity, a balance, and an audit trail. This is what makes machine money accountable.

# Agents & Wallets

An **agent** is any autonomous program that spends or receives money: a coding assistant buying compute, a research agent hiring a legal agent, a shopping bot paying your store.

When you register an agent, Payzor creates three things atomically:

1. **Identity**: a stable `agentId` (`agent_...`) plus a human-readable name.
2. **Wallet**: a ledger balance (USDC-denominated) the agent can spend.
3. **Audit trail**: an append-only log of everything it ever did, with sequence numbers and chained hashes.

```json theme={null}
{
  "agentId": "agent_6b75c0e895ba9c3d",
  "name": "E2E Spender",
  "wallet": { "balance": 99856, "currency": "USDC" },
  "status": "active"
}
```

## How agents get funded

| Method              | What happens                                                                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Console top-up      | Owner credits the ledger directly (dev/test and internal flows).                                                                                                               |
| On-chain deposit    | The agent owns deposit addresses on Base, Arbitrum, Polygon, and Ethereum. A watcher detects incoming USDC and credits the ledger automatically, emitting `deposit.confirmed`. |
| Receiving transfers | Another agent sends money A2A with escrow.                                                                                                                                     |
| Collections         | Humans pay a Wompi checkout link generated by the agent.                                                                                                                       |

## The golden rule

<Warning>
  An agent can only move its own money, and only through its own key. There are no endpoints that accept an `agentId` for spending; if there were, a leaked key would be a master key. The credential *is* the boundary.
</Warning>

## Lifecycle

* `active`: normal operation.
* `paused`: policy checks reject new spending; balances untouched.
* `frozen`: same as paused, but signals an incident; useful when you suspect a compromised key.

Change status with `POST /agents/:id/status`. Pausing takes effect on the next policy evaluation; in-flight approved payments complete.

## Why wallets matter for businesses

When you receive money from an agent, you know:

* which `agentId` paid,
* that its owner's policy allowed the payment (or a human explicitly approved it),
* and every fact is exportable for accounting via the audit chain.

That is something a card payment from a browser session can never tell you.