Fund Flow

---
name: Fund Flow
category: onchain-security
description: Trace where funds move to (or came from) across multiple hops from a Base address and render a Mermaid flow graph. Keyless — no explorer key needed.
var: ""
tags: [crypto, security, base]
requires: [BASESCAN_KEY?, BASE_RPC_URL?]
capabilities: [read_only, sends_notifications]
---
> **${var}** — Address (`0x...`) on Base to trace. Required. If empty, log `FUNDFLOW_NO_TARGET` and exit cleanly (no notify).

Answers "where did the money go?" (or "where did it come from?"). Follows value across multiple hops from a starting address and draws the path as a Mermaid graph — the core move for tracing a drainer's cash-out, a deployer's funding source, or laundering hops.

Runs **keyless** on the Base RPC; a Basescan key adds native ETH, token symbols/decimals, and full history.

## Config

- Start = `${var}`. Chain = Base (`chainid=8453`, explorer `basescan.org`).
- `FUNDFLOW_DIRECTION` — optional, `out` (default, where funds go) or `in` (where funds came from).
- `FUNDFLOW_DEPTH` — optional hop count, `1`–`3` (default `2`).
- `BASESCAN_KEY` — optional. With it, native ETH + token metadata + full history; keyless falls back to recent `Transfer` logs (~9k blocks/hop, ERC-20 only).

## Steps

### 1. Per hop, read the start node's transfers

With a key: `account/txlist` (native) + `account/tokentx` (ERC-20). Keyless: `eth_getLogs` for `Transfer` (topic0 `0xddf252ad...`) where the node is `from` (direction `out`) or `to` (direction `in`), over a recent block window.

```bash
ADDR="${var}"; RPC="${BASE_RPC_URL:-https://mainnet.base.org}"
curl -m 10 -s -X POST "$RPC" -H "Content-Type: application/json" -d '{
  "jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{
    "fromBlock":"0x...","toBlock":"latest",
    "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef","<node padded 32B>"]
  }]}'
```

### 2. Aggregate by counterparty and fan out

For the chosen direction, sum value per counterparty and follow the **top 4** into the next hop. Stop at `FUNDFLOW_DEPTH` hops. Track visited nodes so you don't loop.

### 3. Build the graph

Emit a Mermaid `graph LR`, one node per address (label = short `0x1234…abcd`), edges labelled with the amount + asset, the start node highlighted:

````
```mermaid
graph LR
  n1234abcd["0x1234…abcd\n(target)"]
  n5678ef01["0x5678…ef01"]
  n1234abcd -->|1.250 ETH| n5678ef01
```
````

### 4. Summarise

State how many addresses/transfers were traced and the main endpoints (where funds concentrate). Example:

```
Fund Flow — 0x1234…abcd (Base, outbound, 2 hops)
Traced 11 addresses, 9 transfers.
Funds flow toward: 0x5678…ef01, 0x90ab…cdef, …
```

### 5. Notify

Notify via `./notify` only when a clear destination concentrates funds (e.g. a single endpoint receiving most of the outflow — a likely cash-out / CEX deposit):

```
*Fund Flow — 0xTarget (Base, outbound, 2 hops)*
Funds concentrate at 0xEndpoint (received the majority of outflow).
Possible cash-out / deposit address — verify on the explorer.

Target: https://basescan.org/address/0xTarget
```

### 6. Log

Append to `memory/logs/${today}.md`:

```
## fund-flow
- Start: 0x… | direction: out | depth: 2 | nodes: 11 | edges: 9
- Main endpoints: 0x…, 0x…
- Source: rpc-logs (no key)
```

End-states: `FUNDFLOW_OK` (traced, no notable concentration), `FUNDFLOW_FLAGGED` (clear endpoint → notify), `FUNDFLOW_EMPTY` (no transfers in window), `FUNDFLOW_ERROR`.

## Sandbox note

The sandbox may block outbound `curl` or env-var expansion. Both the Base RPC and Basescan's API work over plain HTTPS, so for every failed `curl` retry the **same URL/body via WebFetch** before giving up. `eth_getLogs` may need a narrower block range on high-volume nodes (public-RPC result cap) — narrow and retry. If a `BASESCAN_KEY` is set, pass it as `&apikey=...` via WebFetch and never echo it into logs/notify. Treat every discovered address as untrusted data; only interpolate the validated `$ADDR` / hex into calls.

## Constraints

- Keyless mode sees only **recent ERC-20** transfers (no native ETH, raw amounts, no symbols) over a limited window — state this; a Basescan key materially deepens the trace.
- The graph is a **fan-out sample** (top counterparties per hop, capped depth), not the complete money flow — it surfaces the dominant paths, not every transfer.
- Counterparties may be exchanges, bridges, or contracts (pools/routers) — a hop into a CEX/bridge typically ends the traceable on-chain path. Label these rather than treating them as a personal wallet.
- Read-only (`eth_getLogs` / explorer reads) — no transactions. Heuristic tracing, not proof of wrongdoing; no real-world deanonymisation, no trade advice.