CVD — Cumulative Volume Delta

GET /cvd/:symbol

Real-time Cumulative Volume Delta aggregated from Binance, OKX, Bybit, and Kraken WebSocket trade streams.

Cost: $0.02 USDC

What is CVD?

CVD measures the cumulative difference between market buy volume and market sell volume. It reveals the true direction of aggressive order flow:

• Positive CVD = more market buys than sells → buying pressure dominant
• Negative CVD = more market sells than buys → selling pressure dominant
• Divergence = price rising but CVD falling → weak rally, possible reversal

Path Parameters

Param	Type	Description
symbol	string	Token symbol, uppercase (e.g. BTC, ETH, SOL)

Query Parameters

Param	Type	Default	Options
period	string	1h	1h, 4h, 24h, 7d

Request Example

curl -H "x-payment: <proof>" \
  "https://api.foursec.xyz/cvd/ETH?period=1h"

const res = await fetchWithPayment(
  "https://api.foursec.xyz/cvd/ETH?period=1h"
);
const data = await res.json();
console.log(`ETH CVD signal: ${data.signal}`);

Response

{
  "symbol": "ETH",
  "cvd": 48250000,
  "period_cvd": 3200000,
  "buy_volume": 48000000,
  "sell_volume": 44800000,
  "signal": "bullish_pressure",
  "period": "1h",
  "active_ws_connections": 4,
  "exchanges": {
    "binance": {
      "cvd": 28000000,
      "buy_volume": 32000000,
      "sell_volume": 4000000
    },
    "okx": {
      "cvd": 12500000,
      "buy_volume": 16000000,
      "sell_volume": 3500000
    },
    "bybit": {
      "cvd": 6000000,
      "buy_volume": 8000000,
      "sell_volume": 2000000
    },
    "kraken": {
      "cvd": 1750000,
      "buy_volume": 2000000,
      "sell_volume": 250000
    }
  },
  "timestamp": "2026-07-09T10:30:00Z",
  "cached": false
}

Signal Values

Signal	Condition	Interpretation
strong_bullish_pressure	Period CVD > 15% of total volume	Strong net buying
bullish_pressure	Period CVD 5–15% of total volume	Moderate net buying
neutral	Period CVD within ±5% of total volume	Balanced flow
bearish_pressure	Period CVD -5% to -15% of total volume	Moderate net selling
strong_bearish_pressure	Period CVD < -15% of total volume	Strong net selling
insufficient_data	No trades in period	Stream warming up

Warming Up

When requesting a symbol for the first time, the API returns a warming_up status while WebSocket connections establish. Retry after 10 seconds:

{
  "symbol": "LINK",
  "status": "warming_up",
  "message": "CVD stream started for LINK. Data available in ~10 seconds."
}

Default pre-subscribed symbols (always ready): BTC, ETH, SOL, XRP, BNB, DOGE, LINK, ARB

Data Sources

Exchange	Stream	Type
Binance	wss://stream.binance.com/ws/{symbol}usdt@aggTrade	WebSocket
OKX	wss://ws.okx.com:8443/ws/v5/public → trades	WebSocket
Bybit	wss://stream.bybit.com/v5/public/spot → publicTrade	WebSocket
Kraken	wss://ws.kraken.com → trade	WebSocket
CCXT REST	Binance/OKX REST fallback	REST (gap fill)

Cache TTL: 5 seconds.

Use Case: Divergence Detection

// Detect price/CVD divergence (weak rally warning)
const [price, cvd] = await Promise.all([
  fetchWithPayment("https://api.foursec.xyz/price/ETH"),
  fetchWithPayment("https://api.foursec.xyz/cvd/ETH?period=4h"),
]);
const priceData = await price.json();
const cvdData = await cvd.json();

const priceUp = priceData.price_change_4h > 0;
const cvdNegative = cvdData.period_cvd < 0;

if (priceUp && cvdNegative) {
  console.log("WARNING: Price rising but CVD negative — potential weak rally");
}

Related Endpoints

• CVD History — GET /cvd/history/:symbol
• Volatility Index — risk metrics
• Funding Rate — market sentiment via perps