CoinClustering

Address clustering for bitcoin based cryptocurrencies

Under construction!

Prerequisites

Node and NPM

Bitcoin core or API compatible client such as Litecoin core or Dash core

bitcoin.conf / dash.conf / litecoin.conf...

server=1
txindex=1
rest=1
rpcuser=[your username]
rpcpassword=[your password]

Installation

1. npm install -g coin-clustering
2. Create a new directory, for example 'BitcoinClustering'
3. Navigate to the directory and create a new file "config.js"
4. Edit config.js according to the below example. Altcoin excamples can be found here.

let config = {
  protocol: 'http',
  user: '[rpcuser from bitcoin.conf]',
  pass: '[rpcpassword from bitcoin.conf]',
  host: '127.0.0.1',
  port: 8332,
  listen_port: 3006,
  pubkeyhash: 0x00,
  scripthash: 0x05,
  segwitprefix: "bc",
  dbcache: 3000
};

module.exports = config; 

5. run coin-clustering in the same directory with config.js

Indexing the bitcoin blockchain can take more or less than a week depending on your hardware. Most altcoins should take much shorter.

HTTP API

Clusters

GET /clusters

Query parameters

• gt, gte, lt, lte (optional) = balanceSats / balanceSats-clusterId
• reverse (optional) = true/false, defalt: false
• limit (optional) = integer (0...1000), defalt: 100

Example

Request

/clusters?limit=3&reverse=true&lte=10000000000000

Response

[
  {
    "clusterId": 17034506,
    "balance": 9816291286270
  },
  {
    "clusterId": 388710763,
    "balance": 8594734769541
  },
  {
    "clusterId": 421208391,
    "balance": 8366430196393
  }
]

GET /clusters/:id/summary

Example

Request

/clusters/17034506/summary

Response

{
  "balance": 9816291286270,
  "firstTransaction": {
    "txid": "2cdce8e3758f9a94975c0b3e1c55729312980cffa0471acfce4d2d308a16b381",
    "height": 256893,
    "n": 4
  },
  "lastTransaction": {
    "txid": "76d4119daa59769f4d694cca9feb1123ebf026e3640ed4ba438c044c809285d8",
    "height": 565263,
    "n": 232
  },
  "addressCount": 114458
}

GET /clusters/:id/transactions

Query parameters

• gt, gte, lt, lte (optional)
• reverse (optional) = true/false, defalt: false
• limit (optional) = integer (0...1000), defalt: 100
• include-delta (optional) = true/false, defalt: false

Example

Request

/clusters/17034506/transactions?limit=3&reverse=true&include-delta=true

Response

[
  {
    "txid": "76d4119daa59769f4d694cca9feb1123ebf026e3640ed4ba438c044c809285d8",
    "height": 565263,
    "n": 232,
    "delta": 95712
  },
  {
    "txid": "55ceaaf9ed5ebf96abed887223a8044afa93119043038321a3d17b982c4337ce",
    "height": 565262,
    "n": 967,
    "delta": 97234
  },
  {
    "txid": "a3f9982bb76d42cc8f68afd12a9a11c6122a30e71ee57cdbd52af767069755e9",
    "height": 563671,
    "n": 571,
    "delta": 615000
  }
]

GET /clusters/:id/addresses

Query parameters

• gt, gte, lt, lte (optional)
• reverse (optional) = true/false, defalt: false
• limit (optional) = integer (0...1000), defalt: 100

Example

Request

/clusters/17034506/addresses?limit=3&reverse=true

Response

[
  {
    "balance": 2322761515776,
    "address": "1AnwDVbwsLBVwRfqN2x9Eo4YEJSPXo2cwG"
  },
  {
    "balance": 2221116525338,
    "address": "14eQD1QQb8QFVG8YFwGz7skyzsvBLWLwJS"
  },
  {
    "balance": 970712966598,
    "address": "1Kd6zLb9iAjcrgq8HzWnoWNVLYYWjp3swA"
  }
]

GET /clusters/:id/balance-candlesticks

Addresses

GET /addresses/:address/cluster_id

/addresses/1AnwDVbwsLBVwRfqN2x9Eo4YEJSPXo2cwG/cluster_id

17034506

GET /addresses/:address/transactions

Query parameters

• gt, gte, lt, lte (optional)
• reverse (optional) = true/false, defalt: false
• limit (optional) = integer (0...1000), defalt: 100

GET /addresses/:address/balance-candlesticks

Transactions

GET /transactions/:txid/cluster-balance-changes

GET /transactions/:txid/details

Miscellaneous

GET /status

Limitations

Stays 10 blocks behind the latest block to avoid having to deal with blockchain reorganizations.