bitrank v1.0.1

BitRank® Node.js Client SDK

The BitRank® Node.js Client is designed to make interfacing with BitRank® as simple as possible. Before you launch your app, make sure you have a BitRank® account and API key on hand, available at bitrankverified.com.

Quick Links:

• Getting started
• Example repository
• Testing API documentation
• Latest stable generated documentation

Getting Started

Before you begin, make sure you have a BitRank® account and API key on hand. Closed beta customers would have been instructed on where to acquire one; if you need any assistance, please contact us directly.

This README assumes you have a working knowledge of modern Node.js and JavaScript.

1. Installing

To begin, install the client with npm.

?> npm install --save bitrank

Load the BitRank library:

const BitRank = require('bitrank');

Or, if using named imports or similar:

import { BitRank } from 'bitrank';

2. Configuring the Client

The client takes the following configuration parameters:

You have two mutually inclusive ways to specify these parameters - either via a .bitrank file in your project root, or directly in the object you provide to the BitRank.Connect({...}) method.

.bitrank

apiKey=API_KEY_HERE
locale=en-us
timeout=2500

Load .bitrank file from project root:

let bitrank = await BitRank.Connect();
let bitrank = await BitRank.Connect({ dotfile: true, timeout: 6500 }); // Load dotfile but override timeout

Load .bitrank file from a different location:

let bitrank = await BitRank.Connect('/path/to/.bitrank');
let bitrank = await BitRank.Connect({
    dotfile: '/path/to/.bitrank',
    locale: 'fr-fr' // Override to French
})

Specify all parameters via the constructor:

let bitrank = await BitRank.Connect({
    apiKey: 'YOUR_KEY_HERE',
    locale: 'en-us',
    timeout: 5000
});

Values set in the constructor will always override values set in the .bitrank file; values left unspecified in both will be set to their defaults as shown in the table above.

Full example:

const BitRank = require('bitrank');

let bitrank = await BitRank.Connect(); // Just load the dotfile

3. Get a score

Now that the configuration is out of the way, let's get going!

let address = '34N3rdXP4hcXVzPdQHbne1p95AJW6QfzjM'; // Address linked to illegal pornography

try {
    let result = await bitrank.score(address);
} catch(e){
    console.log(typeof e);
    console.log(e.message);
}

console.log(`Score: ${result.score} (${result.localeTier()})`);
console.log(`Seen: ${result.seen}`); 
console.log(`Tier: ${result.scoreTier()}`); // The internal comparable score tier (see below table)
console.log(`Flag Count: ${result.flags.length}`);

What to do with a BitRank Verified® score

A BitRank Verified® score is a number between 0 - 100. The score tiers are as follows:

Neutral addresses are typically new and have very little history. The farther south from neutral, the more dangerous; the farther north, the more trustworthy.

If you wish to compare against named tiers, you can do so in your code:

// Example case - granting more freedom on platform based on trustworthiness.
if(result.score > bitrank.scores.good){
    // Trust this address and give it more "freedom" on your platform, 
} else if(result.score >= bitrank.scores.neutral){
    // Trust this address and give it limits on your platform.
} else {
    // Reject this address, as it's below neutral and probably isn't trustworthy.
}

Note that the scores object resides in the bitrank instance, not the BitRank class.

For simplicity's sake, we recommend using the named score tiers instead of arbitrary numbers. (ie. bitrank.scores.neutral vs 50)

What does "seen" mean?

Whether or not an address has been "seen" indicates whether or not the requested address has been seen, processed and scored by the BitRank algorithm. There are a two reasons we may have not seen an address (yet):

1. The address is brand new on the blockchain and we haven't had enough time to calculate a proper score.
2. The address is valid, but hasn't been used on the blockchain.

We serve a neutral score of 50 for all unseen addresses until we have finished our initial calculations for the address, which will then show seen === true. For unseen addresses, you may choose to either proceed, or temporarily deny requests on the given address until our algorithm has had a chance to score it accordingly.

Brand new addresses take between 20 to 40 minutes to show up in the BitRank database - so if you choose to delay on unseen addresses, we recommend checking once every 15 - 30 minutes to prevent using too many API requests within your usage tier.

Address flags

If you wish to check for any flags associated with this address, you may do so by using the Score.flags object, like so:

// If using require('bitrank'):
const Flag = BitRank.Flag; 
// Otherwise, if using es6 / typescript imports:
import { Flag } from 'bitrank'; 

let result = await bitrank.score(address);

for(let flag of result.flags){
    // Locale strings for display
    console.log(`Flag:   ${flag.localeName()}`);
    console.log(`Type:   ${flag.localeType()}`);
    console.log(`Impact: ${flag.localeImpact()}`);

    // Internal keys for comparison and business logic
    console.log(`Internal Key:    ${flag.slug}`);
    console.log(`Internal Type:   ${flag.type}`);
    console.log(`Internal Impact: ${flag.impact}`);
}

// Convenience method to get flags of a specific type:
let badFlags = result.getFlagsOfType(Flag.Type.BAD);

if(result.score >= bitrank.scores.acceptable && badFlags.length === 0){
    console.log("Accepted, welcome!");
} else {
    console.log("Don't call us; we'll call you.");
}

Error Handling

The BitRank SDK throws a common set of errors to describe errors that happen within the library. They are as follows:

The following methods throw these errors and should be wrapped with try/catch:

• BitRank.Connect() static connection method.
• bitrank.score() instance method
• bitrank.update() instance method

These errors can be imported like so:

let AuthError = require('bitrank').AuthError;
// or,
import { AuthError } from 'bitrank';

Testing API

For testing, you may make use of a special test API key, which is: testing.api.bitrank.io.

# .bitrank file
apiKey=testing.api.bitrank.io

This key allows full access to static metadata (the /init-data/<locale> call), as well as predictable output based on the address given.

Format

There are three address test types available:

• 1a | Seen addresses
• 1b | Unseen addresses
• Anything else returns random data

1a | Seen Addresses

Examples:

1a000xxxxxxxxxxxxxxxxxxx | Score 0, No flags
1a050xxxxxxxxxxxxxxxxxxx | Score 50, No flags
1a060xDxxxxxxxxxxxxxxxxx | Score 60, Dark market flag
1a070xVmxxxxxxxxxxxxxxxx | Score 70, Verified client, miner flag
1a070xVmxxxxxxxxxxxxxxxx | Score 70, Verified client, miner flags
1a100xExxxxxxxxxxxxxxxxx | Score 100, Exchange flag

Seen addresses work like so:

• They require a prefix like 1aNUMx - NUM being a number between 000 - 100, representing the score to return
• x is a reserved filler character; addresses must still be valid, so use it to fill up space until it's a correct address.
• They must be between 25-34 characters in length
• After the first x, you may add special alphabetical letters to the address that add flags to the result.

Special Alphabetical Letters:

• d | drug_trade
• D | dark_market
• m | miner
• M | mixer
• P | illegal_pornography
• T | terrorism
• V | verified_client
• E | exchange
• e | exchange_client

1b | Unseen Addresses

Any address that starts with 1b will return an unseen result, which is useful for testing your logic on brand new / non-existant addresses.

Example: 1bxxxxxxxxxxxxxxxxxxxxxx

All other addresses

Any other address will return random scores and flag combinations for testing.

BitRank® and Bitrank Verified® are registered trademarks of Blockchain Intelligence Group.

Copyright © 2017 Blockchain Intelligence Group, All Rights Reserved.