4.14 Wallet Flow Classifier

1. Bot Identity

2. Purpose

Score on-chain wallets on historical edge over a long window — emitted as a feature, never as a copy-trade signal.

3. Why This Bot Matters

• Wallet behaviour treated as a copy-trade signal

  Naively echoing 'smart money' wallets is the textbook way to lose money — the apparent edge is survivor bias, the real wallets front-run, and the implementation amounts to copy-trading. Emitting a feature with explicit non-trigger guidance prevents that misuse.

• Strategies build their own wallet scorers, inconsistently

  Without a shared classifier, every strategy author writes a slightly different version. The library ends up with three inconsistent scores, none of them auditable.

• No long-window context for short-term flows

  A wallet's 24-hour activity is meaningless without its multi-month history. Centralising the long-window score gives all consumers the same baseline and prevents recency-driven misclassifications.

• Compliance unable to flag suspicious counterparties

  Sanctions and abuse reviews need a structured score per wallet. The classifier provides one consistent input that ComplianceGate and Governance can both read.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "institutional_threshold_pusd": 10000 }

if (total_pusd >= p.institutional_threshold_pusd.default) label = 'institutional';

{ "poll_interval_s": 12 }

if (p.poll_interval_s > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

8. Default Configuration

{
  "bot_id": "intel.wallet-flow-classifier",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "institutional_threshold_pusd": 10000,
    "poll_interval_s": 12
  },
  "locked": {
    "institutional_threshold_pusd": {
      "min": 1000
    },
    "poll_interval_s": {
      "max": 60
    }
  }
}

9. Implementation Flow

— not yet authored —

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION classifyWalletFlow(block_number):
  // 0. KillSwitch check
  IF FETCH internal.killswitch.status == ACTIVE:
    RETURN

  // 1. Fetch fills for block range
  fills = onchain.getLogs(CTFExchangeV2, 'OrderFilled', block_number)
  IF len(fills) == 0:
    RETURN

  // 2. Group fills by wallet address
  wallet_fills = groupBy(fills, 'makerAddress')

  // 3. Classify each wallet
  FOR wallet, wfills IN wallet_fills:
    total_pusd = sum(toPusdUnits(f.fillAmount) for f in wfills)
    IF total_pusd < retail_threshold:
      label = 'retail'
    ELIF total_pusd > institutional_threshold:
      label = 'institutional'
    ELIF isArbitragePattern(wfills):
      label = 'arbitrage'
    ELSE:
      label = 'unknown'

    // 4. Emit ObservationReport
    EMIT ObservationReport {
      report_id: gen_id(),
      kind: 'ObservationReport',
      wallet_address: wallet,
      flow_label: label,
      total_pusd: total_pusd,
      block_number: block_number,
      emitted_at_ms: now_ms()
    }

SDK calls used

• onchain.getLogs(CTFExchangeV2, 'OrderFilled', block_number)
• data.GET('/wallets/<address>/history')
• toPusdUnits(fillAmount)

Complexity: O(F) per block where F = fills in block for tracked wallets

11. Wire Examples

Input — what arrives on the wire

{
  "label": "CTFExchangeV2 OrderFilled log for wallet flow classification",
  "source": "onchain",
  "payload": {
    "makerAddress": "0xA1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0",
    "fillAmount": "50000000000",
    "tokenId": "99887766",
    "block_number": 72346100,
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — wallet classified as institutional",
  "payload": {
    "report_id": "rep_wfc_0xa1b2_1746703000000",
    "trace_id": "trc_0xbeef0102030405060715",
    "bot_id": "intel.wallet-flow-classifier",
    "kind": "ObservationReport",
    "wallet_address": "0xA1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0",
    "flow_label": "institutional",
    "total_pusd": 50000,
    "block_number": 72346100,
    "emitted_at_ms": 1746703010000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_wfc_0xa1b2_1746703000000",
  "trace_id": "trc_0xbeef0102030405060715",
  "bot_id": "intel.wallet-flow-classifier",
  "kind": "ObservationReport",
  "wallet_address": "0xA1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8A9B0",
  "flow_label": "institutional",
  "total_pusd": 50000,
  "block_number": 72346100,
  "warnings": [],
  "emitted_at_ms": 1746703010000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / WalletFlowClassifier volume by flow label

16. Developer Reporting

{
  "bot_id": "intel.wallet-flow-classifier",
  "block_number": 72346100,
  "fills_processed": 12,
  "wallets_classified": 5,
  "institutional_count": 1,
  "arbitrage_count": 0,
  "retail_count": 4,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, re-classify from next block; historical backfill not required.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Adversary uses multiple wallets to fragment institutional flow and evade institutional classification
• Wash-trades between related wallets to generate artificial arbitrage pattern signals

Mitigations

• Classification is probabilistic and informational only; strategies apply independent signal weighting
• Arbitrage detection requires multi-market simultaneous fills to reduce single-market spoofing

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

WalletFlowClassifier incidents are most commonly RPC outages. High arbitrage rate alerts indicate unusual market conditions worth investigating but do not block trading.

On-call actions

Manual overrides

• reset_wallet_state — DEL redis key wallet:<address> to reset classification state for a specific wallet — After known wallet rotation or operator-confirmed wallet re-use

Healthcheck

Endpoint: /internal/health/wallet-flow-classifier | Green: rpc_block_lag_s < 24 AND Redis reachable AND last classification < 30 s ago | Red: rpc_block_lag_s > 60 OR Redis unreachable

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%