# Banking Bodyguard
> Scored cbBTC whale signals on Base, delivered per-call via x402.
> For agents that act on large cbBTC flows: lending vaults, liquidity rebalancers, research bots.

Banking Bodyguard watches cbBTC transfers on Base, scores each one BEARISH / NEUTRAL / BULLISH against a labelled-address graph, and returns an action recommendation (HOLD / TIGHTEN_STOP / EXIT) with an impact measure. One HTTP call returns a complete decision-ready signal. No subscription, no API key, no account. Payment is 0.10 USDC per call via x402 v2.

## When to call this API

Call Banking Bodyguard at the moment your agent is about to make a cbBTC-sensitive decision:

- Before adjusting a cbBTC-collateralized lending position
- Before rebalancing a Base DEX pool with cbBTC exposure
- Before sizing or unwinding a leveraged cbBTC position
- On a fixed cadence (10–60s) inside a liquidation-protection bot

Do not call it as a general "is the market up or down" signal. It measures on-chain whale flow, not BTC spot price direction. Validated by backtest May 2026: BEARISH+HIGH+EXIT signals show no 1-hour BTC spot price edge. They do show a usable 60–120 second lead before Base lending oracles reprice cbBTC collateral — that is the actual product.

## Endpoint

```
GET https://bodyguard.finance/x402/signal/cbbtc/latest
```

Payment: 0.10 USDC per call via x402 v2 on Base Mainnet.
Pay-to: `0x8BcbB0C445686bd6F6F7FD73F0778658f4206AE5`.

The endpoint enforces x402 v2 only. v1 payloads return 402 with a v2 challenge. Use an x402 client at SDK v2.9 or later. The 402 response carries network, asset contract, and amount in a machine-readable challenge body — your client reads those at runtime rather than hardcoding them.

### Demo mode

```
GET https://bodyguard.finance/x402/signal/cbbtc/latest?demo=true
```

Returns a realistic sample payload, marked `"demo": true`, with no payment. Unlimited. Use this for integration plumbing — request shape, response parsing, header handling — before connecting a real wallet.

### Free tier

The first 20 real (non-demo) calls per client return signals without charging — no wallet required. The response includes `"free_tier_remaining": N` counting down from 19 on the first call. After call 20, the x402 payment flow kicks in and each call charges 0.10 USDC as normal. No registration, no account, no setup — just call the endpoint. Free tier is rate-limit-keyed by client identity; moving to paid is the moment your agent signs its first x402 payload.

## Response

```json
{
  "signal_id": "8626a32e-1d7a-4142-b1f0-c03a68582da7",
  "schema_version": "1.0",
  "timestamp_utc": "2026-05-11T09:14:22.031187+00:00",
  "block_number": 45612880,
  "tx_hash": "0x9b3f517ea2e97ba3022b62dd0d5455964bb806637b05666303d8a9a2c81c0755",
  "from_address": "0x40EbC1Ac8d4Fedd2E144b75fe9C0420BE82750c6",
  "from_label": "Coinbase Hot Wallet 42",
  "to_address": "0xE41316500B80bA8426cfAC8996adaf3f1671b1e7",
  "to_label": "DEX Liquidity Pool Contract B",
  "value_cbbtc": 134.49,
  "value_usd": 10560000.00,
  "sentiment_score": 9,
  "sentiment_label": "BEARISH",
  "impact_score": 2.41,
  "impact_level": "HIGH",
  "recommendation": "EXIT",
  "confidence": "HIGH",
  "address_source": "labeled",
  "disclaimer": "Signal only. Not financial advice."
}
```

### Field meanings

- `sentiment_score` (1–10): 1–3 BULLISH (exchange → cold wallet), 4–7 NEUTRAL (unknown / unlabelled), 8–10 BEARISH (cold wallet → exchange).
- `sentiment_label`: human-readable equivalent of the score band.
- `impact_score`: transaction value as a percentage of cbBTC 24h DEX volume on Base.
- `impact_level`: HIGH if > 2%, MEDIUM if 0.5–2%, LOW if < 0.5%.
- `recommendation`: HOLD for bullish + low impact; TIGHTEN_STOP for bearish + medium impact; EXIT for bearish + high impact.
- `confidence`: HIGH if both addresses are labelled, MEDIUM if one is labelled, LOW if both are unknown.
- `address_source`: `labeled` when from/to are in the address graph, `unlabeled` otherwise.

A NEUTRAL signal means the system could not classify the transfer's intent — usually one or both addresses are unknown. Treat NEUTRAL as "no decision input," not as "no movement."

## Decision recipe

This shows how to read a signal into a branching decision. The action functions belong to the agent — Banking Bodyguard does not prescribe position sizes, stop-loss percentages, or trade timing. The teaching content is the gating shape.

The same gating shape applies whether the agent manages a cbBTC-collateralized lending position, rebalances a Base DEX pool with cbBTC exposure, or sizes a perp hedge against a cbBTC position. Only the action functions differ.

```python
import requests

resp = requests.get(
    "https://bodyguard.finance/x402/signal/cbbtc/latest",
    headers={"X-PAYMENT": signed_x402_payload}  # see "Payment flow" below
)
signal = resp.json()

# Gate first on confidence — LOW confidence means at least one address is unknown.
if signal["confidence"] != "HIGH":
    pass  # not enough information; keep current exposure

# Strongest action signal: bearish + high impact + high confidence.
elif signal["recommendation"] == "EXIT" and signal["sentiment_score"] >= 8:
    your_reduce_exposure_action(signal)
    # e.g. reduce LP range, close part of position, open or scale a hedge

# Bearish + medium impact: prepare but don't fully exit.
elif signal["recommendation"] == "TIGHTEN_STOP":
    your_defensive_adjustment_action(signal)
    # e.g. shift LP range tighter, tighten stop-loss, partial hedge

# Bullish with non-trivial impact: accumulation candidate.
elif signal["sentiment_label"] == "BULLISH" and signal["impact_level"] != "LOW":
    your_increase_exposure_action(signal)
    # e.g. widen LP range, add to position, close existing hedge

else:
    pass  # HOLD or low-impact noise
```

The gating conditions matter more than the actions. `confidence == "HIGH"` is the cheapest filter against unknown-address noise. `sentiment_score >= 8` paired with `recommendation == "EXIT"` is the strongest action signal the service produces.

## Payment flow (x402 v2)

The endpoint follows the x402 protocol. The handshake:

1. Agent sends `GET /x402/signal/cbbtc/latest` with no payment header.
2. Server returns HTTP 402 with a `payment-required` header and a JSON challenge describing price (100000 atomic USDC = 0.10), recipient, network, and asset.
3. Agent signs an EIP-712 `TransferWithAuthorization` for the requested amount and recipient using its Base wallet key.
4. Agent retries with the signed payload base64-encoded in the `X-PAYMENT` header.
5. Server verifies the signature via Coinbase Developer Platform (CDP), settles the transfer on-chain, and returns the signal.

Using the official x402 SDK (TypeScript):

```typescript
import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.WALLET_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPayment = wrapFetchWithPayment(fetch, wallet);

const r = await fetchWithPayment("https://bodyguard.finance/x402/signal/cbbtc/latest");
const signal = await r.json();
```

Python equivalent (using `x402` SDK v2.9+):

```python
from x402.clients.requests import x402_requests
from eth_account import Account

account = Account.from_key(os.environ["WALLET_KEY"])
session = x402_requests(account)

r = session.get("https://bodyguard.finance/x402/signal/cbbtc/latest")
signal = r.json()
```

The wallet must hold USDC on Base. Gas is paid by the CDP facilitator; the wallet does not need ETH for the payment step.

## Latency

- Detection: under 10 seconds from block confirmation to signal availability in the database (10-second poll cadence on Base).
- Endpoint response: sub-500ms typical, plus x402 settlement (1–3 seconds on Base).
- Total signal-age at delivery: typically 10–15 seconds from on-chain event.

Polling cadence guidance: 10s for liquidation protection, 60s for active trading, 5–15 minutes for risk dashboards, daily for research.

## Coverage

- **Asset:** cbBTC (Coinbase Wrapped Bitcoin) only.
- **Chain:** Base Mainnet only.
- **Threshold:** transfers above 5 cbBTC.
- **Address graph:** 60+ labelled Base entities — Coinbase hot wallets, Morpho cbBTC vaults and position contracts, Aerodrome cbBTC pools, major DEX aggregators and bridges. Coverage exceeds 80% both-sides-labelled on whale flow as of May 2026.

WETH, other wrapped BTC variants, and other chains are out of scope. cbBTC on Ethereum mainnet is not covered.

## Anti-patterns

Things that look like reasonable integrations but produce bad agent behavior:

- **Acting on every BEARISH signal.** BEARISH spans scores 8, 9, 10 — only 9+ paired with HIGH or MEDIUM impact is actionable. Score 8 with LOW impact is noise.
- **Treating NEUTRAL as "no movement."** It means the system cannot interpret the transfer's intent. Default to your existing position; do not interpret it as a market read.
- **Ignoring `confidence`.** LOW confidence means at least one address is unknown. The recommendation field is still populated, but it should not drive automated action.
- **Using this as a BTC spot signal.** cbBTC on Base is a small single-digit-percent fraction of global BTC market cap. Flows here do not move BTC spot price reliably within 1 hour. They do front-run cbBTC oracle repricing on Base lending markets.
- **Rebalancing LP ranges on every signal.** Gas and re-deposit costs on Aerodrome or Uniswap V3 range shifts can outpace whale-flow alpha. Threshold on `impact_level == "HIGH"` and add a 5–15 minute cooldown between signal-triggered rebalances.
- **Opening a hedge on a single signal.** Pair the signal with current price action or wait for a confirming second signal in the same direction before committing hedge capital. One BEARISH+HIGH+EXIT is a warning, not a trigger.
- **Polling faster than 10 seconds.** The underlying watcher polls every 10 seconds. Faster client polling burns USDC and produces duplicate signals.
- **Auto-trading without price confirmation.** Treat the signal as one input. Confirm with current price, funding rate, and your position's risk parameters before executing.

## When NOT to use Banking Bodyguard

Be honest about the alternatives. Banking Bodyguard is the right choice when all three apply:

1. You are working with cbBTC on Base, not BTC or wBTC elsewhere.
2. You want scored, labelled, decision-ready output — not raw transfer events.
3. You want pay-per-call pricing without managing API keys or subscriptions.

If you only need raw whale transfer detection on multiple chains, a generic on-chain indexer or a free public mempool feed will give you the raw data at zero cost. You'll need to build labelling, scoring, and impact context yourself.

If you need scored signals across multiple assets and chains, a multi-chain analytics provider (Nansen, Arkham) is broader but priced per seat at $150–500/month, not per call.

If you need real-time push delivery rather than pull, this API is the wrong shape — a WebSocket stream is planned but not live.

Banking Bodyguard's specific value is the combination: cbBTC-on-Base specialisation, sub-10-second detection, labelled-address scoring, and per-call x402 pricing. Outside that intersection, other tools win.

## Track record

Live in production since April 2026. Sub-10-second detection latency from block confirmation. Address label coverage above 80% of whale flow across 60+ labelled Base entities.

Live metrics: `https://bodyguard.finance/health`
Public signal history with scoring outcomes: `https://bodyguard.finance/track-record.html`

## Disclaimer

Signals are probabilistic indicators on observed on-chain flow. Not financial advice. Past signal patterns do not predict future market behavior. Agents acting on signals do so at the operator's risk.

## Affiliate header (tool builders)
If you are building a wrapper, SDK, MCP tool, or any product that forwards
calls to Banking Bodyguard on behalf of users, add this header to earn
$0.02 USDC per forwarded call:

  x-affiliate-wallet: 0xYourEVMWallet

No registration. No minimum commitment. Your wallet address is your identity.
Balance: https://bodyguard.finance/affiliate/balance?wallet=0xYourWallet
Policy: https://bodyguard.finance/affiliate/policy
Payouts sweep daily at 02:00 UTC once balance exceeds $1.00 USDC.

## Other surfaces

- Free Telegram alert channel (HIGH impact and EXIT recommendations only): `https://t.me/+V5QAfdHgW9wwZjdl`
- OpenAPI documentation: `https://bodyguard.finance/docs`
- Affiliate program (20% per referred call): `https://bodyguard.finance/affiliate/policy`
- Contact: `@BankingBodygd` on X