# Bitcoin Address Monitor & Whale Alert - New Transactions (`centorprat/bitcoin-address-monitor-whale-alert`) Actor

Watch Bitcoin addresses. Each run reads the public blockchain (keyless) and reports only NEW transactions since the last run - optionally only large 'whale' moves or one direction. Schedule it + set a webhook for alerts. Read-only, agent-callable.

- **URL**: https://apify.com/centorprat/bitcoin-address-monitor-whale-alert.md
- **Developed by:** [Centor Prat](https://apify.com/centorprat) (community)
- **Categories:** Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.50 / 1,000 watch runs

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Bitcoin Address Monitor & Whale Alert — New Transactions

Watch any set of Bitcoin addresses and get told the moment they move funds. Each run reads the **public** blockchain (keyless) and, because it remembers what it saw last time, reports **only the NEW transactions** since the previous run — optionally only large "whale" moves, or only one direction. Schedule it + set a webhook and it becomes a standing alarm. Read-only, public ledger only — agent-callable.

For on-chain analysts, treasury/ops teams watching their own wallets, researchers tracking known addresses, and AI agents that need a change-trigger on a wallet.

### What it does

- Reads each watched address's recent transactions from a keyless explorer (Blockstream Esplora, mempool.space fallback).
- **Diffs** against the previous run (state persisted in a named key-value store, stable per watch) and surfaces only what's **new**.
- Classifies each new transaction: **direction** (in/out), **value** (BTC + sats), counterparties, confirmation/time.
- Optional **whale filter** (`minValueBtc`) and **direction** filter.
- First run records a **silent baseline** (no history spam); later runs report and (with a webhook) alert only on new activity.

| Output field | Meaning |
|---|---|
| `signal` | baseline-established / new-activity / whale-move / no-new-matching-activity |
| `balanceBtc` | current balance |
| `newTransactions[]` | each new tx: `direction`, `valueBtc`, `counterparties`, `time`, `txid` |
| `newCount` / `largestMoveBtc` | how many new + the biggest move |

### Why not just ask an AI agent?

An agent has no memory between runs and no scheduler. This actor keeps **durable state** per watch, so it can tell *new* from *already-seen* across days of scheduled runs, and fire a webhook exactly when a wallet moves — a standing monitor an agent can't be, plus the deterministic diff/filtering at scale.

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `addresses` | array of strings | ✅ | Bitcoin addresses to watch. |
| `minValueBtc` | integer | | Only alert on moves ≥ this many BTC (0 = all). |
| `direction` | string | | `both` / `in` / `out`. |
| `webhookUrl` | string | | POST new transactions here when found. |

**Example input**

```json
{
  "addresses": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"],
  "minValueBtc": 10,
  "direction": "both"
}
```

### Output

One record per watched address. **Example** (a run that found new activity):

```json
{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "signal": "new-activity",
  "balanceBtc": 57.66512665,
  "newCount": 2,
  "largestMoveBtc": 0.5,
  "newTransactions": [
    {"txid": "c99e446ab2d4...", "direction": "in", "valueBtc": 0.5, "counterparties": ["bc1q..."], "confirmed": true, "time": "2026-10-17T01:40:00+00:00"}
  ]
}
```

The **first** run instead returns `signal: "baseline-established"` and alerts on nothing.

### Use cases

- **Whale watching** — alert when a known large wallet moves ≥ N BTC.
- **Your own treasury** — get pinged the moment funds leave or arrive at a company wallet.
- **Investigations** — standing watch on an address of interest.
- **AI agents** — a scheduled change-trigger: the agent acts only when the wallet moves.

### Alerts / scheduling

1. Set `addresses` (+ optional `minValueBtc` / `direction`) and `webhookUrl`.
2. Schedule the actor (e.g. every 10 min or hourly) in Apify.
3. The first run is a silent baseline; after that, each run that finds new transactions POSTs them to your webhook (Slack/Discord/email via Make/Zapier).

### Ready-made tasks

- [Bitcoin Whale Alert - Large Transfers from Watched Wallets](https://apify.com/centorprat/bitcoin-address-monitor-whale-alert/examples/bitcoin-whale-alert)

### For AI agents / MCP

```
https://mcp.apify.com/?tools=actors,docs,centorprat/bitcoin-address-monitor-whale-alert
```

Loads as `centorprat--bitcoin-address-monitor-whale-alert`. Claude Code:

```
claude mcp add apify -- npx -y @apify/actors-mcp-server --actors centorprat/bitcoin-address-monitor-whale-alert
```

### FAQ

**Which chain?** Bitcoin mainnet (bech32 `bc1…` and base58 `1…`/`3…`).

**Does it need a key?** No — keyless public explorers.

**How does it know what's new?** It stores the transaction ids it has seen (per watch) in a named key-value store, so it survives between scheduled runs and diffs against them.

**What's a "whale-move"?** A new transaction at or above your `minValueBtc` (or ≥ 50 BTC if you leave the threshold at 0).

**Will the first run spam me with history?** No — the first run is a silent baseline.

**Cost?** Pay-per-event: a small base per run + a premium per new transaction alerted — quiet runs cost only the base.

**Is it legal?** It reads the public Bitcoin ledger only. Alerts are factual on-chain events, never accusations about who owns an address or why funds moved.

### Data & attribution

Public Bitcoin blockchain via the keyless Blockstream Esplora API (mempool.space fallback). No keys, no personal data. Signals, not advice.

### Related actors

- [Bitcoin Wallet & Transaction Tracer](https://apify.com/centorprat/bitcoin-wallet-transaction-tracer)
- [Crypto Address Risk & AML Screener](https://apify.com/centorprat/crypto-address-risk-aml-screener)

# Actor input Schema

## `addresses` (type: `array`):

Bitcoin addresses to monitor (bc1... / 1... / 3...).

## `minValueBtc` (type: `integer`):

Only alert on new transactions moving at least this many BTC (0 = every new transaction). Set e.g. 10 for a whale alert.

## `direction` (type: `string`):

Which transactions to alert on.

## `webhookUrl` (type: `string`):

If set, new transactions are POSTed here as JSON when a run finds them (Slack/Discord/email via Make/Zapier).

## Actor input object example

```json
{
  "addresses": [
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  ],
  "minValueBtc": 0,
  "direction": "both"
}
```

# Actor output Schema

## `monitor` (type: `string`):

Per watched address: balance, the NEW transactions since the previous run (value, direction, counterparties, time), and a signal (baseline / new-activity / whale-move / no-new-matching-activity). First run records a silent baseline.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
    ],
    "minValueBtc": 0
};

// Run the Actor and wait for it to finish
const run = await client.actor("centorprat/bitcoin-address-monitor-whale-alert").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "addresses": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"],
    "minValueBtc": 0,
}

# Run the Actor and wait for it to finish
run = client.actor("centorprat/bitcoin-address-monitor-whale-alert").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  ],
  "minValueBtc": 0
}' |
apify call centorprat/bitcoin-address-monitor-whale-alert --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,centorprat/bitcoin-address-monitor-whale-alert"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0s93ch9YylqGBGGt0/builds/IFrVmgNYcjwFd6aNp/openapi.json