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

# Money flow

> The round trip: how money enters Payzor, how it moves when your agent buys and when your business sells, and where it physically sits at each step.

# Money flow

Payzor has **two sides**, and the same dollar can travel both. Your agent
**buys** — it pays APIs, services and other businesses. Your business **sells** —
it charges the agents that show up. In between, money is a row in a ledger; at
the edges, it is USDC on a chain.

This page is the round trip: where money comes in, what happens on each side,
and where it ends up.

## The round trip

```mermaid theme={null}
flowchart TB
    subgraph IN["1 · Money comes in"]
        W[Your external wallet<br/>MetaMask, Phantom, an exchange] -->|deposit USDC| CA[(Agent chain account<br/>custodied by Payzor)]
        CA -->|deposit watcher credits it| LED[(Agent balance<br/>Payzor ledger)]
    end

    subgraph BUY["2a · Buy side — your agent spends"]
        LED --> POL{Policy engine}
        POL -->|within the perimeter| OK[Charge paid]
        POL -->|over the threshold| HITL[Waits for your approval]
        HITL --> OK
    end

    subgraph SELL["2b · Sell side — your business collects"]
        OK -->|internal transfer<br/>nothing moves on-chain| MB[(Merchant balance)]
        X[Any agent<br/>no Payzor account] -->|signed x402 payment| FAC[Facilitator settles]
        FAC -->|USDC lands on-chain| TRE[(Payzor treasury)]
        FAC -->|credits the book| MB
    end

    subgraph OUT["3 · Money goes out"]
        MB -->|payout| DEST[An address you control]
        LED -->|agent withdrawal| DEST
        TRE -.->|payouts are funded from here| DEST
    end
```

<Note>
  Read the diagram as three phases, not five boxes: money **enters** as USDC,
  **circulates** as ledger entries, and **leaves** as USDC again. The only steps
  that touch a blockchain are the deposit, an x402 payment, and a withdrawal.
</Note>

## 1 · Money comes in

Every agent can hold a chain account, custodied by Payzor through Coinbase CDP.

```bash theme={null}
POST /agents/:id/chain      # create the account, get the deposit address
GET  /agents/:id/chain      # addresses per network
```

Send USDC to that address from any wallet or exchange. A watcher polls the
account and credits the agent's ledger balance when the deposit lands. For
testing, you can also credit the ledger directly:

```bash theme={null}
POST /agents/:id/topup
```

<Tip>
  The **ledger balance** is what the policy engine checks and what pays charges.
  The **chain balance** is the USDC sitting at the address. A deposit turns the
  second into the first.
</Tip>

## 2a · Buy side — your agent spends

Your agent pays from its ledger balance. Every payment goes through the
[policy engine](/concepts/policy-engine) first: per-transaction cap, daily cap,
allowed categories, and the human-approval threshold.

* **Within the perimeter** → the charge is paid immediately.
* **Over the approval threshold** → nothing is debited. The payment waits for
  you to approve it, and only then completes.
* **Outside a hard limit** → it is blocked, and the reason is recorded.

Paying a charge from a wallet is an **internal transfer**: the agent's balance
goes down, the merchant's balance goes up, and nothing moves on any chain. That
is what makes sub-cent payments viable — there is no gas to pay.

## 2b · Sell side — your business collects

Your business publishes something to be paid: a
[charge](/concepts/charges), a [payment link](/api-reference/checkout), a
catalog product, or a [PayLink](/concepts/paylinks) with a pre-authorized
budget. Then any agent can settle it, in one of two ways:

<CardGroup cols={2}>
  <Card title="From a Payzor wallet" icon="wallet">
    The agent carries a `pz_sk_` key. The charge is paid from its ledger balance,
    under its own policy. No chain movement.
  </Card>

  <Card title="On-chain with x402" icon="link">
    The agent has no Payzor account at all. It answers the `402` with a signed
    payment, the facilitator settles in USDC, and the sale closes in the same
    request.
  </Card>
</CardGroup>

Either way your **merchant balance** (`balance_minor`, always in USD cents) goes
up, the audit chain records it, and a `charge.succeeded` webhook fires.

## 3 · Money goes out

Both sides can take money out to an address they control.

**Business payouts** follow an explicit state machine — a withdrawal is never a
single fire-and-forget call:

```mermaid theme={null}
flowchart LR
    R[requested] --> A[approved] --> S[sending] --> D[sent]
    R -.-> C[cancelled]
    A -.-> C
```

```bash theme={null}
POST /merchant/payouts              # requested  (KYT-screened at this moment)
POST /merchant/payouts/:id/approve  # approved   (balance is debited here)
POST /merchant/payouts/:id/send     # sending → sent, on-chain
POST /merchant/payouts/:id/cancel   # cancelled, while still requested or approved
GET  /merchant/payouts
```

The destination address is screened for KYT **at withdrawal time**, not only
when you save it. Every request carries an idempotency key, so a retry can never
send the funds twice.

**Agent withdrawals** work the same way from the wallet side:

```bash theme={null}
POST /agents/:id/withdrawals
POST /agents/:id/withdrawals/:wid/send
GET  /agents/:id/withdrawals
```

<Warning>
  A withdrawal goes out on the **same network as the destination address**, and
  every chain has its own USDC contract. Sending to an address on the wrong
  chain loses the funds and cannot be undone — check the network before you
  approve. See [supported networks](/concepts/x402#supported-networks).
</Warning>

## Where the money physically is

The part that is easy to lose track of. An internal balance is a claim on
Payzor; the USDC itself sits somewhere specific.

| Stage                               | Balance you see       | Where the USDC actually is              |
| ----------------------------------- | --------------------- | --------------------------------------- |
| After a deposit                     | Agent ledger balance  | The agent's own chain account           |
| Agent pays a charge from its wallet | Agent ↓ · Merchant ↑  | It has not moved — this is a book entry |
| Agent pays with x402                | Merchant ↑            | The Payzor treasury, on-chain           |
| Payout requested                    | Merchant balance held | Still in the treasury                   |
| Payout sent                         | Merchant ↓            | The address you control                 |

<Note>
  Payouts are funded from the Payzor treasury, which is where on-chain
  settlements land. That is why a withdrawal is a real transaction with a hash
  you can look up, while paying a charge between two Payzor accounts is not.
</Note>

## Units, once and for all

* The **merchant API** speaks USD cents everywhere: `amountUsdCents`,
  `amountMinor`, `balance_minor`. `2500` is **\$25.00**.
* The **policy engine** speaks dollars. The payment machinery converts before
  evaluating, so a \$25.00 link is checked against the agent's policy as
  \$25.00 — never as 2500.

<Tip>
  When you reconcile, compare cents with cents. Mixing the two units by a factor
  of 100 is the single most common integration bug.
</Tip>