@blockedprotocol/points-sdk

Blocked Points SDK

Using the SDK

Use the SDK to integrate Blocked Points SDK into your app in minutes. The SDK is available in Typescript and Javascript.

Best Practices

• Make sure to keep your API key secure and do not expose it in client-side code.
• Use meaningful event names that clearly describe the action being performed.
• Use a maximum of 4 digits after the decimal point for your points.

Get Started

Get your API key

Contact Blocked Protocol team to receive your private keys

Installation

npm add @blockedprotocol/points-sdk

Initialize the client

Use the newBlockedSdk method to initialize the client, providing your API key and point system id.

import { newBlockedSdk } from "@blockedprotocol/points-sdk";

const blockedSdk = newBlockedSdk({
  apiKey: "YOUR_API_KEY",
  pointsSystemId: "YOUR_POINT_SYSTEM_ID",
});

By default it'll use production environment, but you can pass env: "development" to use development environment.

Add points and tag the event

Tagging each point assignment with an event name is important for tracking and analytics.

await blockedSdk.points.track("login", {
  points: 100,
  account: "11111111111111111111111111111111",
});

await blockedSdk.points.track("transfer_eth_cosmos", {
  points: 515,
  account: "22222222222222222222222222222222",
});

Substract points

You can substract points for account using the negative value. The following example will decrement 50 points:

await blockedSdk.points.track("penalty", {
  points: -50,
  account: "11111111111111111111111111111111",
});

Multiply points

You can multiply points. The following example will multiply points by 1.5:

await blockedSdk.points.track("top_user", {
  account: "11111111111111111111111111111111",
  multiplicator: 1.5,
});

Get points for an account

Get the points for an account using the getPoints method, providing the account address.

await blockedSdk.points.getPoints("11111111111111111111111111111111");
// => { points: 100 }

Get leaderboard

Get the leaderboard using the getLeaderboard method. The response defaults to the top 100 users. Pagination support coming soon

await blockedSdk.points.getLeaderboard();
// => [
//   { account: "11111111111111111111111111111111", points: 100 },
//   { account: "22222222222222222222222222222222", points: 515 }
// ]

Get Leaderboard Rank

Get the rank of an account in the leaderboard using the getLeaderboardRank method.

await blockedSdk.points.getLeaderboardRank("11111111111111111111111111111111");

// {
//   account: '11111111111111111111111111111111',
//   rank: 1,
//   points: 100
// }

Get events

Get the events for a specific event name using the getEvents method.

await blockedSdk.points.getEvents({
  account: "11111111111111111111111111111111", // filter by address
  event: "login", // filter by event name
});

// Returns an array of events
// => [
//   {
//     event: 'login',
//     account: '11111111111111111111111111111111',
//     timestamp: 1712326918956,
//     points: 100,
//   }
// ]

If you don't specify the event field, it'll return all events for a given account

Create User

User - is an entity allows to link multiple accounts and utilize referral system

Here's how you can create user:

await blockedSdk.users.create(["11111111111111111111111111111111"]);
// => { id: "<USER_ID>" }

Note: if account already linked to another user, error will be thrown.

Create user with referrer

If you know that account A has referred account B, you can create a user entity and provide the referral information.

Follow the code snippet to create user and specify referrer:

// 1. find referrer user
// if user doesn't exist for account, error will be thrown
// see step above on how to create user without referrer
const referrerUser = blockedSdk.users.findByAccount("A");
// 2. create user
await blockedSdk.users.create(["B"], referrerUser.id);
// => { id: "<USER_ID>" }

As a result you craeted user B referred by user A.

Link multiple wallets to user

You can link accounts to a user even after user entity was created.

If you know that user with account abc has also accounts aaa and bbb.

// 1. Find user with account `abc`
// if user doesn't exist for account, error will be thrown
// see step above on how to create user
const user = await blockedApi.users.findByAccount("abc");
// 2. Link accounts `aaa` and `bbb` to the same user
await blockedApi.users.linkAccounts(user.id, ["aaa", "bbb"]);

Get points for user

Returns cumulutive value for all accounts linked to user

const user = blockedSdk.users.findByAccount("11111111111111111111111111111111");
await blockedSdk.points.getPointsForUser(user.id);
// => { points: 100 }