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

# Cash Flow

> Get how money moved through a wallet over the last 30, 90 and 365 days

## Overview

Returns flow statistics for the wallet over three trailing windows, summed across every chain it has used. It is the on-chain counterpart of a bank-statement cash-flow analysis: how much arrived and left, from how many counterparties, how regularly, and how fast the balance turns over. Pair it with [Balance History](https://docs.credprotocol.com/api-reference/report/balance-history.md), which gives the stock at four instants; this endpoint gives the movement between them.

**Cost:** 8 Cred Units per request.

## How transfers are counted

Every native, internal and ERC-20 transfer touching the wallet is valued in USD at that day's price and sorted into one of three kinds:

| Kind | What it is | Where it shows |
| - | - | - |
| External | Funds arriving from or leaving to anyone other than a lending protocol | `inflow_*`, `outflow_*`, `net_flow_usd`, counterparties, largest transfers |
| Lending | One-way transfers to or from a known Aave pool or Compound market: supplies and repayments out, borrows and withdrawals in | `lending_inflow_usd`, `lending_outflow_usd` |
| Conversion | A transaction that moved value both into and out of the wallet: swaps, wraps, LP entries. Money changed form; it did not arrive or leave | `conversion_usd`, `conversion_count` |

> [!NOTE]
>
> Lending receipt and debt tokens (aTokens, variable-debt tokens, Comet balances) are positions, not funds, and are ignored. Transfers of tokens without a market price are ignored and counted in `unpriced_transfers`. This is also what keeps airdrop spam out of the totals.

## Path Parameters

**address** `string` *required*

Ethereum address or ENS name (e.g., `vitalik.eth` or `0x742d35Cc6634C0532925a3b844Bc454e4438f44e`)

## Response

**address** `string`

The resolved Ethereum address (checksummed)

**timestamp** `string`

ISO 8601 timestamp when the statistics were computed; every window ends here

**coverage** `string`

`complete` when every chain's transfers were read, otherwise `partial`

**unavailable\_chains** `integer[]`

Present only when `coverage` is `partial`: chains whose transfers could not be read

**unpriced\_transfers** `integer`

Transfers ignored because their token has no market price

**chains** `object`

Per chain read: `transfers`, the number of transfer legs found in the longest window, and `complete`, false when the chain had more rows than one read returns and the window predates the oldest row

**windows** `array`

One object per window, 30, 90 and 365 days

**windows\[].days / from / to** `integer / string / string`

The window length and its date range

**windows\[].inflow\_usd / outflow\_usd / net\_flow\_usd** `number`

External funds in, out, and the difference

**windows\[].inflow\_count / outflow\_count** `integer`

External transfers in and out

**windows\[].lending\_inflow\_usd / lending\_outflow\_usd** `number`

Borrows and withdrawals received from lending protocols; supplies and repayments sent to them

**windows\[].conversion\_usd / conversion\_count** `number / integer`

Value sold in conversions (the outgoing side) and the number of converting transactions

**windows\[].active\_days** `integer`

Days with at least one priced transfer of any kind

**windows\[].stablecoin\_inflow\_usd** `number`

External inflow in stablecoins

**windows\[].stablecoin\_inflow\_periods / periods** `integer`

How many of the window's 30-day periods saw any stablecoin inflow, and how many periods the window has

**windows\[].stablecoin\_inflow\_cv** `number | null`

Coefficient of variation of stablecoin inflow across the periods. 0 is perfectly steady; above 1 is lumpy. `null` for the 30-day window or when there was none

**windows\[].counterparties\_in / counterparties\_out** `integer`

Distinct external senders and recipients

**windows\[].top\_counterparty\_inflow\_share** `number | null`

Share of external inflow from the single largest sender. `null` when there was no inflow

**windows\[].largest\_inflow\_usd / largest\_outflow\_usd** `number`

The largest single external transfer in each direction

**windows\[].days\_since\_last\_inflow** `integer | null`

Days since the most recent external inflow inside the window; `null` when there was none

**windows\[].average\_balance\_usd** `number | null`

Mean of the balance-history points (assets held plus lending deposits) that fall inside the window. The 365-day window uses the same points as the 90-day one

**windows\[].turnover\_ratio** `number | null`

`(inflow_usd + outflow_usd) / average_balance_usd`. Below 1 per quarter reads as a treasury; tens read as active trading

**windows\[].complete** `boolean`

`false` when some chain's history could not be read back far enough to cover this window

## Reading the numbers

* **Income regularity**: `stablecoin_inflow_periods` equal to `periods` with a low `stablecoin_inflow_cv` is salary-like; a single large period is a one-off.
* **Dependence**: `top_counterparty_inflow_share` near 1 with `counterparties_in` of 1 means one source funds the wallet.
* **Drain**: negative `net_flow_usd` with a large `largest_outflow_usd` relative to `average_balance_usd`, especially in the 30-day window against a positive 365-day one.
* **Debt service**: `lending_outflow_usd` against `inflow_usd` shows whether repayments are funded by income.

## Known limits

* Transfers between a user's own wallets read as external flows.
* Gas is not counted as an outflow.
* Celo transfers are read, but only its native coin and CoinGecko-listed tokens are priced. Robinhood Chain tokens other than ETH are unpriced.
* A chain with more than 10,000 rows of one kind in the window is read from the newest row backwards; windows the read did not reach are marked `complete: false`.

```bash cURL theme={null}
curl -X GET "https://api.credprotocol.com/api/v2/report/address/vitalik.eth/cash-flow" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.credprotocol.com/api/v2/report/address/vitalik.eth/cash-flow',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

for w in response.json()['windows']:
    print(f"{w['days']}d: in ${w['inflow_usd']:,.0f} out ${w['outflow_usd']:,.0f} "
          f"turnover {w['turnover_ratio']} top sender {w['top_counterparty_inflow_share']}")
```

```json 200 theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "timestamp": "2026-10-24T18:40:11+00:00",
  "coverage": "complete",
  "unpriced_transfers": 3,
  "chains": {"1": {"transfers": 212, "complete": true}, "8453": {"transfers": 48, "complete": true}},
  "windows": [
    {
      "days": 30, "from": "2026-09-24", "to": "2026-10-24",
      "inflow_usd": 12400.0, "outflow_usd": 9100.5, "net_flow_usd": 3299.5,
      "inflow_count": 6, "outflow_count": 11,
      "lending_inflow_usd": 0.0, "lending_outflow_usd": 2500.0,
      "conversion_usd": 4800.0, "conversion_count": 3,
      "active_days": 9,
      "stablecoin_inflow_usd": 12000.0, "stablecoin_inflow_periods": 1, "periods": 1, "stablecoin_inflow_cv": null,
      "counterparties_in": 2, "counterparties_out": 7, "top_counterparty_inflow_share": 0.968,
      "largest_inflow_usd": 6000.0, "largest_outflow_usd": 2500.0, "days_since_last_inflow": 4,
      "average_balance_usd": 18420.55, "turnover_ratio": 1.167,
      "complete": true
    },
    {"days": 90, "from": "2026-07-26", "to": "2026-10-24", "...": "same fields"},
    {"days": 365, "from": "2025-10-24", "to": "2026-10-24", "...": "same fields"}
  ]
}
```

```json 503 theme={null}
{
  "detail": "Transfer history is temporarily unavailable from upstream data providers; please retry shortly"
}
```

## Performance

* **Response Time**: 5–20 seconds on a cold wallet (three transfer feeds per active chain, plus one price series per token); well under a second afterwards
* **Caching**: transfers per chain for an hour, price series for a day, the response for 5 minutes
* **Not billed**: a `503` (no provider could answer) consumes no Cred Units


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.