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

# Commerce Flows

> Classified stablecoin transfers for real commerce-related onchain activity — B2B, B2C, and C2B flows identified via protocol matches and behavioural heuristics across EVM chains, Tron, and Solana.

Not every stablecoin transfer is a payment. `payments.commerce_flows` is a transfer-level dataset that identifies the ones that are — every transfer that is a legitimate commerce transaction, tagged with its flow type (`party_pair`, `purpose`), a `confidence` level, and the `protocol` where one is known.

The table is intentionally conservative: transfers that don't match a rule are **excluded**, not bucketed as "unclear". It is not a universal stablecoin classifier and does not try to label everything.

Commerce Flows feeds back into the stablecoins dataset — payments are a sub-category of stablecoin activity. Matched transfers have their `category` updated from `unidentified` to `payment` in [`stablecoins_evm.activity_enriched`](/data-catalog/curated/stablecoins/activity-enriched/stablecoins-evm-activity-enriched).

## Why this dataset matters

Most stablecoin volume is not payments — it is trading, bridging, and treasury movement. Commerce Flows isolates the slice that is genuine commercial settlement, attaching an explicit rule and a confidence level to every row. It makes it possible to:

* Measure onchain commerce volume by flow type (B2B, C2B, B2C) and protocol.
* Separate protocol-verified settlement (Tier A) from behavioural inference (Tier B).
* Label stablecoin transfers as payment-related for downstream analytics.

## Coverage

**Chains:** EVM chains, Tron, and Solana. Solana coverage is label-based (Tier A) only.

**Tokens:** Stablecoins only — the dataset classifies transfers from the upstream stablecoin transfer tables. Unlike [`payments.card_transactions`](/data-catalog/curated/payments/card-transactions) and [`payments.agentic_payments`](/data-catalog/curated/payments/agentic-payments), which are not restricted to stablecoins, non-stablecoin settlement does not appear here.

**Protocol-verified sources (Tier A):**

* Crypto cards — sourced from [`payments.card_transactions`](/data-catalog/curated/payments/card-transactions).
* Agentic payments (x402 / MPP) — sourced from [`payments.agentic_payments`](/data-catalog/curated/payments/agentic-payments).
* Stripe, Shopify Commerce Payments Protocol, Coinbase Commerce, Request Network, and stablecoin payment processors (e.g. BVNK).

**Behavioural flows (Tier B):** B2C payroll-style distributions, C2B merchant aggregation, and recurring B2B commerce.

## Output taxonomy

| Party pair | Purpose | Meaning |
| - | - | - |
| B2B | Commerce | Business pays business for goods or services. |
| C2B | Commerce | Consumer pays a merchant or service (checkout, subscriptions where detectable). |
| B2C | Payroll | Recurring business-to-many-individuals payouts. |

Some reports group these flows by audience instead. The audiences overlap on the raw taxonomy — agentic settlement is itself a B2B row — so apply them in precedence order to keep each row in exactly one bucket: `agents` first (B2B rows with `heuristic_id = 'agentic_payments'`, in full protocol detail in [`payments.agentic_payments`](/data-catalog/curated/payments/agentic-payments)); then `businesses` for the remaining B2B; and `retail` for the consumer-facing pairs (C2B and B2C).

## Methodology

The pipeline runs in ordered stages: a **strict exclusion layer** removes non-commerce and non-final activity, then **Tier A** captures protocol-explicit matches (`confidence = high`), and finally **Tier B** applies a small set of high-signal behavioural heuristics to the residual (`confidence = medium`). Each transfer maps to **one** output row, and Tier A always takes precedence over Tier B.

### 1. Exclusion layer

Fires before any classification. A transfer matching any rule is dropped from the eligible universe.

* **Via upstream stablecoin labels:** issuer mechanics (mint / burn), bridge and wrap infrastructure, CEX legs, DEX / AMM / routing, and DeFi vaults / lending / yield.
* **Via behavioural shape:** same-entity / self-transfers, round-trip and reverse transfers (treasury reshuffling, wash patterns), A→B→C pass-through routing (avoids double-counting intermediary legs), high-frequency bot wallets, and large one-off treasury repositioning.

<Note>
  **Eligibility settles 24 hours after block time.** Round-trip and reverse-transfer detection looks 24 hours forward, so a transfer's eligibility is not final until 24 hours after its block time. Rows older than 24 hours are stable; only the most recent 24 hours can still change as later reverse legs land. This keeps both legs of a round trip out of the dataset, at the cost of a short settling window on the leading edge.
</Note>

### 2. Wallet classification

Each address is typed from its full transaction history, with a `wallet_balance_tier` derived from its rolling 30-day average USD balance.

| Wallet type | Balance tiers | Profile |
| - | - | - |
| Consumer | dust (under $100), micro ($100–$1K), small ($1K–\$10K) | Retail-sized transfers, low counterparty diversity |
| Business | medium ($10K–$100K) | Recurring inflows from many senders, or outflows to many receivers |
| Institutional | large ($100K–$1M), whale (over \$1M) | High-value counterparties, treasury / corporate flow shapes |
| Unclassified | any | Average balance under \$10 or sparse history — excluded from classified output |

### 3. B2B commerce

| Tier | Detector | What it captures |
| - | - | - |
| A (labels) | Agentic payments | Agent-to-agent settlement (x402 / MPP), from [`payments.agentic_payments`](/data-catalog/curated/payments/agentic-payments). |
| A (labels) | Processor deposits | Stablecoin payment-processor settlement legs (e.g. BVNK). |
| B (behavioural) | Recurring B2B | Business / institutional sender → receiver, ticket ≥ \$2K, directional, low recurrence. |

### 4. B2C payroll

| Tier | Detector | What it captures |
| - | - | - |
| A (labels) | Request Network | Protocol-mediated payouts through Request payment proxies. |
| B (behavioural) | Payroll batch | Business-tier sender distributing to ≥5 recipients on a regular cadence, mid-size tickets, no return flow. |

### 5. C2B commerce

| Tier | Detector | What it captures |
| - | - | - |
| A (labels) | Crypto cards | Card purchase settlements, from [`payments.card_transactions`](/data-catalog/curated/payments/card-transactions). |
| A (labels) | Stripe | Stablecoin checkout settlement into the Stripe MerchantFactory contract. |
| A (labels) | Shopify CPP | Final settlement legs of the Shopify Commerce Payments Protocol (captures / charges only). |
| A (labels) | Coinbase Commerce | Final settlement into the merchant / operator. |
| B (behavioural) | Merchant aggregation | Merchant-like receiver aggregating many payers, then settling out to 1–2 wallets. |

## Table schema

Each row is one classified stablecoin transfer. Non-applicable fields are `NULL`. Every row carries `tx_hash` + `transfer_evt_index` + `transfer_unique_key` to join back to the upstream stablecoin transfer.

| Column | Type | Description |
| - | - | - |
| `blockchain` | varchar | Chain name |
| `block_month` | date | Block month (partition key) |
| `block_date` | date | Block date |
| `block_time` | timestamp | Block timestamp |
| `tx_hash` | varbinary | Transaction hash of the classified transfer |
| `activity_evt_index` | bigint | Event index of the protocol anchor event for Tier A matches; `NULL` for Tier B |
| `transfer_evt_index` | bigint | Event index of the underlying token transfer |
| `transfer_unique_key` | varchar | Unique transfer identifier; merge key and join key back to upstream |
| `token_address` | varbinary | Token contract address |
| `token_symbol` | varchar | Token symbol, e.g. `USDC`, `USDT` |
| `amount_raw` | uint256 | Raw token amount |
| `amount` | double | Normalized token amount |
| `amount_usd` | double | USD value at block time |
| `sender` | varbinary | Raw transfer sender |
| `receiver` | varbinary | Raw transfer receiver |
| `payment_uuid` | varchar | Identifier grouping the legs of a single payment; populated only where a multi-leg payment can be reconstructed, `NULL` otherwise |
| `sender_wallet_type` | varchar | `consumer`, `business`, `institutional`, or `unclassified` |
| `sender_wallet_balance_tier` | varchar | `dust` (under $100), `micro` ($100–$1K), `small` ($1K–$10K), `medium` ($10K–$100K), `large` ($100K–$1M), `whale` (over $1M) |
| `receiver_wallet_type` | varchar | Same vocabulary as `sender_wallet_type` |
| `receiver_wallet_balance_tier` | varchar | Same vocabulary as `sender_wallet_balance_tier` |
| `party_pair` | varchar | `b2b`, `c2b`, or `b2c` |
| `purpose` | varchar | `commerce` or `payroll` |
| `heuristic_type` | varchar | `labels_based` (Tier A) or `activity_based` (Tier B) |
| `heuristic_id` | varchar | Specific rule that matched, e.g. `crypto_card`, `stripe`, `shopify_cpp`, `coinbase_commerce`, `request_network`, `agentic_payments`, `b2b_processor_deposits`, `c2b_commerce_h3_aggregation`, `b2c_payroll_h1_batch`, `b2b_commerce_h_recurring` |
| `confidence` | varchar | `high` (Tier A) or `medium` (Tier B) |
| `protocol` | varchar | Protocol or provider for Tier A matches (e.g. `x402`, `stripe`, `shopify_base_cpp`, `coinbase_commerce`, `request_network`, or the card brand for crypto cards); `NULL` for Tier B |
| `dataset_version` | varchar | Methodology version; bumped when classification logic changes |
| `_updated_at` | timestamp | Pipeline load time (when the row was last written) |

## Sample queries

### Commerce flow volume by party pair and purpose

```sql theme={null}
SELECT
    party_pair,
    purpose,
    heuristic_type,
    SUM(amount_usd)        AS volume_usd,
    COUNT(*)               AS tx_count,
    COUNT(DISTINCT sender) AS unique_senders
FROM payments.commerce_flows
WHERE block_date >= NOW() - INTERVAL '30' DAY
GROUP BY 1, 2, 3
ORDER BY 4 DESC
```

### Protocol-verified flows only

```sql theme={null}
SELECT
    protocol,
    blockchain,
    SUM(amount_usd) AS volume_usd,
    COUNT(*)        AS tx_count
FROM payments.commerce_flows
WHERE confidence = 'high'
  AND block_date >= NOW() - INTERVAL '30' DAY
GROUP BY 1, 2
ORDER BY 3 DESC
```

## Related tables

* [`payments.card_transactions`](/data-catalog/curated/payments/card-transactions) — Tier A source for crypto card matches.
* [`payments.agentic_payments`](/data-catalog/curated/payments/agentic-payments) — Tier A source for x402 and MPP matches.
* [`stablecoins_evm.activity_enriched`](/data-catalog/curated/stablecoins/activity-enriched/stablecoins-evm-activity-enriched) — downstream consumer; exposes `category = 'payment'` for matched transfers.


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