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

# Pump and Dump Detection API

> Composite scores flagging coins with suspicious derivatives, holder, liquidity, DEX-flow, and price behavior consistent with pump-and-dump risk.

Pump & Dump exposes a composite 0-10 score per coin built from derivatives positioning, holder concentration, liquidity quality, DEX flow, and price behavior. The pattern often signals artificial markup, distribution, or dump risk.

The signal is gated: a coin only qualifies when sufficient market coverage and multiple manipulation-risk signals align. Exact weights and thresholds are proprietary to reduce gaming.

The score updates every 30 minutes.

***

## Get pump and dump data

`GET /v1/pump-dump/data`

Returns coins ranked by their composite pump-and-dump divergence score, descending.

### Query parameters

**limit** `integer`

Maximum number of coins to return. `1` to `500`. Default `100`.

**min\_score** `number`

Filter to coins scoring at or above this threshold. `0` to `10`. Default `0`.

**phase** `string`

Filter to one phase: `setup`, `markup`, `distribution`, `dump`, or `dumping`.

**coin** `string`

One coin by its CoinGecko id (e.g. `pepe`): its row exactly as the scorer wrote it, whatever its score. A coin that stopped qualifying answers `score: null` with its sub-scores and phase cleared; an id with no row answers an empty list. `limit`, `min_score` and `phase` do not apply.

### Response fields

**coins** `array`

Array of scored coins, sorted by `score` descending.

**coins\[].coin\_id** `string`

Canonical coin slug.

**coins\[].symbol** `string`

Ticker symbol.

**coins\[].name** `string`

Display name.

**coins\[].score** `number | null`

Composite manipulation risk score from `0` to `10`. Higher means stronger alignment across derivatives, market structure, holder, liquidity, and flow signals. If funding, price or derivatives inputs are missing, the score is a conservative lower bound rather than a measured neutral reading; missing on-chain inputs are left out and the remaining weights re-normalize, so that gap can move the score either way. `null` only on a `coin` request for a coin that stopped qualifying.

**coins\[].signal\_coverage** `number`

Weighted input completeness from `0` to `1` across funding, price, derivatives, and on-chain groups (`0.81` is 81%).

**coins\[].signal\_coverage\_status** `string`

`full` when every signal group is observed, `partial` at a `signal_coverage` of `0.5` or more, otherwise `limited`. Compare scores only with their coverage in view.

**coins\[].incomplete\_signal\_groups** `string[]`

Signal families with one or more unavailable inputs.

**coins\[].score\_interpretation** `string`

`lower-bound-partial-inputs` when a funding, price or derivatives input is missing (it scores as zero), otherwise `fully-observed`. A row missing only on-chain inputs reads `fully-observed`: those are left out and the weights re-normalize, and the gap shows in `incomplete_signal_groups`.

**coins\[].avg\_funding\_72h** `number`

Average funding rate across exchanges over the trailing 72 hours, expressed as a decimal.

**coins\[].funding\_magnitude** `number`

Sub-score `[0, 1]` reflecting the absolute size of negative funding (`1.0 = -0.05%/8h or stronger`).

**coins\[].pump\_magnitude** `number`

Sub-score `[0, 1]` reflecting the size of the 7-day price move on a log scale (`100% pump ≈ 0.67`, saturates at large pumps).

**coins\[].divergence\_persistence** `number`

Sub-score `[0, 1]` reflecting consecutive days funding has stayed negative.

**coins\[].derivatives\_pressure** `number`

Sub-score `[0, 1]` summarizing funding, OI, basis, CVD, liquidation, and cross-venue positioning pressure. Basis and CVD exist only for the futures-covered majors; on other coins they are null and add nothing, so the sub-score is a lower bound.

**coins\[].holder\_concentration** `number | null`

Sub-score `[0, 1]` summarizing top-10 holder share and holder-count scarcity. `null` when no on-chain holder data is available.

**coins\[].market\_structure\_risk** `number | null`

Sub-score `[0, 1]` summarizing holder concentration, liquidity fragility, flow imbalance, and contract/security context. `null` when none of those inputs is observed.

**coins\[].dump\_pressure** `number`

Sub-score `[0, 1]` summarizing active downside pressure from market and derivatives signals.

**coins\[].manipulation\_phase** `string`

Current phase label: one of `setup`, `markup`, `distribution`, `dump-risk`, or `watch`.

**coins\[].price\_funding\_divergence** `number`

**Deprecated.** Alias of `pump_magnitude`. Will be removed after a deprecation window. New consumers should use `pump_magnitude` directly.

**coins\[].consecutive\_negative\_days** `integer`

Number of consecutive trading days with negative average funding.

**coins\[].return\_24h** `number`

Trailing 24h price return as a fraction (`0.0481` is +4.81%).

**coins\[].return\_7d** `number`

Trailing 7d price return as a fraction. Used as market context alongside holder, liquidity, flow, and derivatives signals.

**coins\[].top10\_holders\_share** `number | null`

Share of supply held by the top 10 holders, from `0` to `1`. `null` when unknown, including when contracts (treasury Safes, vesting, bridges, pools) hold over half of the top-10 share. Exchange hot wallets still count as holders.

**coins\[].oi\_change\_24h** `number | null`

24h open-interest change as a decimal, when futures data is available, over the contracts with a reading 24-28 hours before their latest (MEXC excluded): computed as `/v1/global/overview` computes `oiChange24h`.

**coins\[].cvd\_trend\_24h** `number | null`

Net taker flow over each venue's newest 24 hourly candles with exchange-reported taker-buy volume (at least 15, the newest at most 3 hours old), averaged over venues, as a decimal in \[-1, 1]; null when no venue qualifies. Price prediction scores the same figure as CVD.

**coins\[].basis\_rate\_avg** `number | null`

Average perp basis as a decimal, when spot/index and futures price context is available.

**coins\[].volume\_to\_liquidity\_24h** `number | null`

24h DEX volume divided by available liquidity. High values can indicate fragile churn.

**coins\[].holders\_change** `number | null`

Holder-count change since the previous successful scoring run, expressed as a decimal.

**coins\[].top10\_holders\_share\_change** `number | null`

Change in `top10_holders_share` since the previous successful scoring run: the difference of the two shares (`0.012` is a share up from `0.300` to `0.312`), not a relative change.

**coins\[].signal\_start\_date** `string`

ISO 8601 timestamp of when the divergence began.

**coins\[].updated\_at** `string`

ISO 8601 timestamp of the most recent score recomputation.

**count** `integer`

Number of rows in `coins`.

**data\_as\_of** `string | null`

Latest `updated_at` timestamp represented by the returned rows, in ISO 8601 format. `null` when no valid score timestamp is available.

**stale** `boolean`

`true` when `data_as_of` is missing, invalid, or more than 1 hour old.

**freshness\_sla\_seconds** `integer`

Maximum supported score age in seconds. Currently `3600` (1 hour).

**description** `string`

Plain-language summary of the signal for client display.

**signal** `object`

Methodology metadata: `methodology`, `gate`, `update_frequency`, and the list of `exchanges` monitored.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/pump-dump/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d limit=20 \
  -d min_score=4
```

```ts TypeScript theme={null}
const params = new URLSearchParams({ limit: '20', min_score: '4' })
const res = await fetch(
  `https://www.sharpe.ai/api/v1/pump-dump/data?${params}`,
  { headers: { Authorization: 'Bearer sk_live_your_key_here' } },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/pump-dump/data",
    params={"limit": 20, "min_score": 4},
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "coins": [
      {
        "coin_id": "example-token",
        "symbol": "EXMP",
        "name": "Example Token",
        "score": 7.6,
        "signal_coverage": 0.72,
        "signal_coverage_status": "partial",
        "incomplete_signal_groups": ["derivatives"],
        "score_interpretation": "lower-bound-partial-inputs",
        "avg_funding_72h": -0.00021,
        "funding_magnitude": 0.74,
        "pump_magnitude": 0.78,
        "divergence_persistence": 0.71,
        "derivatives_pressure": 0.66,
        "holder_concentration": 0.92,
        "market_structure_risk": 0.84,
        "dump_pressure": 0.52,
        "manipulation_phase": "distribution",
        "price_funding_divergence": 0.78,
        "consecutive_negative_days": 5,
        "return_24h": 0.0481,
        "return_7d": 0.182,
        "signal_start_date": "2026-04-21T00:00:00Z",
        "updated_at": "2026-04-26T07:00:00Z"
      }
    ],
    "count": 1,
    "data_as_of": "2026-04-26T07:00:00Z",
    "stale": false,
    "freshness_sla_seconds": 3600,
    "description": "Pump and dump risk scores based on derivatives positioning, holder concentration, liquidity quality, and DEX flow.",
    "signal": {
      "methodology": "Composite 0-10 risk score built from derivatives positioning, market structure, holder concentration, liquidity fragility, and flow imbalance. Exact weighting is proprietary to reduce gaming.",
      "gate": "Requires sufficient cross-exchange futures coverage plus at least one strong manipulation-risk setup, markup, distribution, or dump-risk condition.",
      "update_frequency": "every 30 minutes",
      "exchanges": [
        "Binance", "Bybit", "OKX", "Gate.io", "Bitget", "Hyperliquid",
        "Deribit", "HTX", "BingX", "KuCoin", "MEXC"
      ]
    }
  },
  "meta": {
    "request_id": "req_pumpdump_xyz789",
    "timestamp": "2026-04-26T07:00:05Z",
    "elapsed_ms": 12
  }
}
```

The response header `X-Sharpe-Data-State` is `ok` or `stale` using the same 1-hour SLA. Stale rows remain available with HTTP `200`, but clients should treat them as historical context rather than a current trading signal. A database or query failure answers `503` (`service_unavailable`, `Retry-After: 30`) in the normal API error envelope.

***

## How the score is built

The score is a composite risk model capped at 10. It uses multiple signal families:

* **Derivatives pressure:** funding, open interest, basis, true taker-flow/CVD, and liquidation context.
* **Holder concentration:** top-10 holder share and holder-count context.
* **Liquidity and flow quality:** liquidity depth, volume-to-liquidity churn, and buy/sell imbalance.
* **Phase detection:** setup, markup, distribution, and dump-risk behavior.

We publish the signal families and validation process, but not the exact formula, weights, or thresholds. That keeps the leaderboard harder to game while still making the approach understandable to users.

Unavailable derivatives, price and funding inputs contribute no risk. This intentionally keeps a partial-input score conservative, but it also means the number is a lower bound rather than directly comparable with a fully observed row. Unavailable on-chain inputs are left out instead and the remaining weights re-normalize, so an on-chain gap can move the score either way. Always inspect `signal_coverage`, `signal_coverage_status`, and `incomplete_signal_groups` alongside `score`.

[See the insider selling signal](https://docs.sharpe.ai/insider-selling.md)


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