🚀 Kabila SDK for JavaScript

A modern JavaScript SDK for seamless integration with the Kabila NFT Marketplace
Supports user authentication, listing and purchasing NFTs, creating and accepting offers, and much more — all with a developer-friendly API.

📦 Installation • 🚀 Quick Start • 📘 Documentation • 💱 Currency

📋 Table of Contents

• 📦 Installation
• 🚀 Quick Start
  • 🔓 Public Operations Examples
  • 🔐 Authenticated Operations Examples
  • 🔐 Signature Authentication for Sensitive Operations
  • 🔐 Signature Required Operations Examples
• 📘 Full Documentation
  • 👤 Users API
  • 🏢 Market Manager API
  • 📊 Market Analytics API
• 💱 Supported Currency
• 🔐 Required Allowances & Signatures
• 🧱 Data Models

📦 Installation

npm install @kabila-tech/kabila-sdk-js

# Using yarn
yarn add @kabila-tech/kabila-sdk-js

# Using pnpm
pnpm add @kabila-tech/kabila-sdk-js

🚀 Quick Start

🔓 Public Operations Examples

Get NFTs

import { KabilaSdk } from '@kabila-tech/kabila-sdk-js';

const kabilaSdk = new KabilaSdk();

const result = await kabilaSdk.marketManager.nftItems.getItems(
  {
    limit: 10,
    skip: 0,
    orderBy: 'serialNumber',
    fields: ['tokenId', 'name', 'price', 'serialNumber', 'sellerId']
  },
  {
    tokenId: '0.0.2179656',
    filterAttributes: {
      Body: ['Green', 'X Ray'],
      Feet: ['Barefoot']
    }
  }
);

🔐 Authenticated Operations Examples

Login + Get Received Offers

import { KabilaSdk, AuthUtils } from '@kabila-tech/kabila-sdk-js';
import { DAppConnector, SignMessageParams } from '@hashgraph/hedera-wallet-connect';

// ⚠️  IMPORTANT: Initialize your own DAppConnector instance
// const dAppConnector = new DAppConnector(...);
// await dAppConnector.init({ logger: 'error' });

/* 🔑 Step 1: Sign message */
const address = '0.0.1234';
const params: SignMessageParams = {
  signerAccountId: 'hedera:mainnet:' + address,
  message: AuthUtils.getKabilaAuthMessage()
};

const { signatureMap } = await dAppConnector.signMessage(params);

/* 🔐 Step 2: Login */
const {
  data: { token, publicKey }
} = await kabilaSdk.users.login(address, signatureMap);
kabilaSdk.setAuth(token);

/* 📋 Step 3: Get offers */
const result = await kabilaSdk.marketManager.userOffers.getOffersReceived(address, { limit: 10 });

Buy NFT (Get + Execute Tx)

import { KabilaSdk } from '@kabila-tech/kabila-sdk-js';
import { DAppConnector, SignTransactionParams } from '@hashgraph/hedera-wallet-connect';
import { AccountAllowanceApproveTransaction, NftId, TokenId } from '@hashgraph/sdk';

const tokenId = '0.0.123';
const serialNumber = 155;

/* 🛒 Step 1: Get purchase transaction */
const { data: transaction } = await kabilaSdk.marketManager.nftItems.getNftItemsPurchaseTransaction([
  { tokenId, serialNumber }
]);

/* ✍️ Step 2: Sign transaction */
const params: SignTransactionParams = {
  signerAccountId: 'hedera:mainnet:' + address,
  transactionBody: transaction.transaction
};

const { signatureMap } = await dAppConnector.signTransaction(params);

/* ✅ Step 3: Execute transaction */
await kabilaSdk.marketManager.nftItems.executeNftItemsPurchaseTransaction(signatureMap);

List NFT

import { KabilaSdk, WHBAR_TOKEN_ID, MARKET_ACCOUNT_ID } from '@kabila-tech/kabila-sdk-js';
import { DAppConnector, SignTransactionParams } from '@hashgraph/hedera-wallet-connect';

const nftItemsToList: NftItemCreation[] = [
  {
    tokenId: '0.0.2179656',
    serialNumber: 1000,
    allowOffers: true,
    currency: WHBAR_TOKEN_ID,
    minOfferPrice: 300,
    price: 500
  }
];

/* 🔐 Step 1: Give allowance to MARKET_ACCOUNT_ID */
const client = Client.forTestnet();
const signer = dAppConnector.getSigner(AccountId.fromString(buyerAccountId));

const allowanceTx = new AccountAllowanceApproveTransaction()
  .approveTokenNftAllowance(
    new NftId(TokenId.fromString(nftItemsToList[0].tokenId), nftItemsToList[0].serialNumber),
    AccountId.fromString(buyerAccountId),
    AccountId.fromString(MARKET_ACCOUNT_ID)
  )
  .setTransactionId(TransactionId.generate(accountId))
  .setNodeAccountIds([<nodeAccountId>])
  .freeze();

const allowanceTxSigned = await signer.signTransaction(allowanceTx);
await allowanceTxSigned.execute(client);

/* 📋 Step 2: List NFT */
const { data: nftItemsListed } = await kabilaSdk.marketManager.nftItems.listNftItem(nftItemsToList);

🔐 Signature Authentication for Sensitive Operations

Some methods require an additional signature for sensitive operations. Use AuthUtils.getKabilaAuthMessage5min() to get the authentication message:

⚠️ Important: The getKabilaAuthMessage5min() method generates a time-based message that expires every 5 minutes. This provides additional security for sensitive operations.

import { AuthUtils } from '@kabila-tech/kabila-sdk-js';

/* 🔑 Get signature for sensitive operations */
const params: SignMessageParams = {
  signerAccountId: 'hedera:mainnet:' + address,
  message: AuthUtils.getKabilaAuthMessage5min()
};

const { signatureMap } = await dAppConnector.signMessage(params);
const signature = signatureMap; // Use this signature in the methods below

🔐 Signature Required Operations Examples

NFT Management Operations

/* 🏷️ Update NFT price */
const priceUpdate = {
  signature: signatureMap,
  price: 100,
  currency: WHBAR_TOKEN_ID,
  allowOffers: true,
  minOfferPrice: 50
};
await kabilaSdk.marketManager.nftItems.updateNftItemPrice(tokenId, serialNumber, priceUpdate);

/* 🗑️ Delist NFT */
const delistData = {
  signature: signatureMap,
  nftItems: [{ tokenId, serialNumber }]
};
await kabilaSdk.marketManager.nftItems.delistNftItem(delistData);

/* 💰 Update offer */
// Buyer updates offer (requires allowance, no signature)
const buyerOfferUpdate = {
  price: 80,
  signature: undefined
};
await kabilaSdk.marketManager.nftItemsOffers.updateNftItemOffer(offerId, buyerOfferUpdate);

// Seller updates offer (requires signature, no allowance)
const sellerOfferUpdate = {
  price: 90,
  signature: signatureMap
};
await kabilaSdk.marketManager.nftItemsOffers.updateNftItemOffer(offerId, sellerOfferUpdate);

📝 RequestOptions Examples

// Basic pagination
const basicOptions: Partial<RequestOptions> = {
  limit: 10,
  skip: 0
};

// Pagination with ordering
const orderedOptions: Partial<RequestOptions> = {
  limit: 20,
  skip: 10,
  orderBy: 'price',
  orderDir: 'desc'
};

// Multiple ordering fields
const multiOrderOptions: Partial<RequestOptions> = {
  limit: 25,
  orderBy: ['price', 'createdAt'],
  orderDir: ['desc', 'asc']
};

📘 Full Documentation

👤 Users API

| Method | Description | Returns | | ----------------------------- | -------------------------------- | ------------------------------------------------- | | login(accountId, signature) | Authenticate user with signature | ApiResult<{ token: string; publicKey: string }> |

login(accountId: string, signature: string): ApiResult<{ token: string; publicKey: string }>

🏢 Market Manager API

📖 Full API Documentation: Kabila Market Manager Docs

🎨 NFT Items

| Method | Description | Returns | Requirements | | -------------------------------------- | ------------------------------- | ------------------------------------ | ---------------------------- | | getItems() | Get NFTs with filtering options | ApiResult<NftItem[]> | - | | getItemById() | Get specific NFT by ID | ApiResult<NftItem> | - | | getNftItemsPurchaseTransaction() | Get purchase transaction | ApiResult<{ transaction: string }> | - | | executeNftItemsPurchaseTransaction() | Execute purchase transaction | ApiResult<void> | - | | listNftItem() | List NFTs for sale | ApiResult<NftItemId[]> | approveTokenNftAllowance() | | delistNftItem() | Remove NFTs from sale | ApiResult<void> | signature | | updateNftItemPrice() | Update NFT price | ApiResult<void> | signature |

// Get NFTs with filtering
getItems(requestOptions?: RequestOptions, extraFilters?: Object): ApiResult<NftItem[]>

// Get specific NFT
getItemById(tokenId: string, serialNumber: number, requestOptions?: RequestOptions): ApiResult<NftItem>

// Purchase flow
getNftItemsPurchaseTransaction(nftItemIds: NftItemId[], requestOptions?: RequestOptions, extraOptions?: Object): ApiResult<{ transaction: string }>
executeNftItemsPurchaseTransaction(signatureMap: string, requestOptions?: RequestOptions): ApiResult<void>

// Listing management
listNftItem(newNftItems: NftItemCreation[], requestOptions?: RequestOptions): ApiResult<NftItemId[]>
delistNftItem(nftItem: NftItemDelist, requestOptions?: RequestOptions): ApiResult<void>
updateNftItemPrice(tokenId: string, serialNumber: number, updatedNftItem: NftItemPriceEdition, requestOptions?: RequestOptions): ApiResult<void>

🎨 NFT Collections

| Method | Description | Returns | | ---------------------------------- | ------------------------------------ | ---------------------------------------- | | getCollectionById() | Get collection by token ID | ApiResult<NftCollection> | | getCollections() | Get collections | ApiResult<NftCollection[]> | | getCollectionsListed() | Get listed collections | ApiResult<NftStatusMap> | | getCollectionsAttributesStats() | Get collection attributes statistics | ApiResult<Attributes> | | getCollectionAttributes() | Get collection attributes | ApiResult<NftCollection> | | getCollectionNftItemsRarityMap() | Get NFT rarity map | ApiResult<NftCollectionNftItemsRarity> |

🎨 NFT Items Offers

| Method | Description | Returns | Requirements | | ---------------------------------- | --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- | | getNftItemsOffers() | Get all NFT offers | ApiResult<NftItemOffer[]> | - | | getNftItemOffers() | Get offers for specific NFT | ApiResult<NftItemOffer[]> | - | | createNftItemOffers() | Create new offers | ApiResult<NftItemOffer[]> | approveHbarAllowance() | | updateNftItemOffer() | Update offer price | ApiResult<{ data: NftItemOfferEdition[]; modifiedCount: number }> | approveHbarAllowance() (buyer only) + signature (seller only) | | deleteNftItemOffer() | Delete offer | ApiResult<NftItemId> | - | | getNftItemOfferTransaction() | Get offer transaction | ApiResult<{ transaction: string }> | - | | executeNftItemOfferTransaction() | Execute offer transaction | ApiResult<NftItem> | - |

🏷️ NFT Collection Offers

| Method | Description | Returns | Requirements | | ---------------------------------------- | ------------------------------------ | ------------------------------------ | ------------------------ | | getNftCollectionsOffers() | Get collection offers | ApiResult<NftCollectionOffer[]> | - | | createNftCollectionOffers() | Create collection offers | ApiResult<NftCollectionOffer[]> | approveHbarAllowance() | | getNftCollectionsOffersPrice() | Get total offer price | ApiResult<{ total: number }> | - | | deleteNftCollectionOffer() | Delete collection offer | ApiResult<void> | - | | gettNftCollectionOfferTransaction() | Get collection offer transaction | ApiResult<{ transaction: string }> | - | | executeNftCollectionOfferTransaction() | Execute collection offer transaction | ApiResult<{ _id: string }[]> | - |

👤 User Offers

| Method | Description | Returns | | ----------------------- | ------------------------------- | ------------------------ | | getOffersMade() | Get offers made by user | ApiResult<UserOffer[]> | | getOffersReceived() | Get offers received by user | ApiResult<UserOffer[]> | | getAmountOffersMade() | Get total amount of offers made | ApiResult<number> |

📊 Market Analytics API

📖 Full API Documentation: Kabila Market Analytics Docs

🎨 Activity

| Method | Description | Returns | | --------------- | ---------------------- | ------------------------------ | | getActivity() | Get NFT items activity | ApiResult<NftItemActivity[]> |

getActivity(requestOptions?: RequestOptions, extraFilters?: Object): ApiResult<NftItemActivity[]>

💱 Supported Currency

WHBAR_TOKEN_ID = '0.0.1062664';

🔐 Required Allowances & Signatures

Spender: MARKETPLACE_ACCOUNT_ID = '0.0.4824758'

Allowances

| Function | Required Allowance | Description | | ----------------------------- | ------------------------------------- | ------------------------------------------------------------- | | listNftItem() | approveTokenNftAllowance() | Allow marketplace to transfer your NFTs | | createNftItemOffers() | approveHbarAllowance() | Allow marketplace to spend your HBAR | | updateNftItemOffer() | approveHbarAllowance() (buyer only) | Allow marketplace to spend your HBAR when buyer updates offer | | createNftCollectionOffers() | approveHbarAllowance() | Allow marketplace to spend your HBAR |

Signature Requirements

| Function | Required Signature | Description | | --------------------------------------------------- | ------------------------- | ----------------------------------------- | | marketManager.nftItems.delistNftItem() | signature | Remove NFTs from sale | | marketManager.nftItems.updateNftItemPrice() | signature | Update NFT prices | | marketManager.nftItemsOffers.updateNftItemOffer() | signature (seller only) | Update offer prices when acting as seller |

🧱 Data Models

💡 Tip: Use these data models for full TypeScript support and type safety.

🎨 Core Types

ApiResult<T>

Generic wrapper for all API responses.

interface ApiResult<T> {
  data: T; // The actual response data
  status: number; // HTTP status code
  statusText: string; // HTTP status text
  headers: {}; // Response headers
}

RequestOptions

Configuration options for API requests including pagination, filtering, and authentication.

interface RequestOptions {
  limit: number; // Number of items to return
  skip: number; // Number of items to skip (for pagination)
  fields: string[]; // Specific fields to return
  search: string; // Search term for filtering
  orderBy: string | string[]; // Field(s) to order by
  orderDir: string | string[]; // Order direction ('asc' or 'desc')
  format: Format; // Response format
  auth: string; // Authentication token (Bearer token)
}

Format

Enum for response format options.

enum Format {
  WITH_PAGINATION = 'WITH_PAGINATION', // Include pagination metadata
  NO_PAGINATION = 'NO_PAGINATION' // Return only data without pagination
}

🎨 NFT Models

NftItem

Complete NFT item information.

interface NftItem {
  _id?: string; // Database ID
  allowOffers: boolean; // Whether offers are allowed
  attributes?: {
    // NFT attributes/traits
    traitType: string; // Attribute category
    value: string; // Attribute value
  };
  buyerId?: string; // Current buyer ID
  createdAt: Date; // Listing creation date
  currency: string; // Currency token ID
  description?: string; // NFT description
  endDate?: Date; // Auction end date
  imageCid?: string; // Image CID
  imageType?: string; // Image MIME type
  metadataCid?: string; // Metadata CID
  minOfferPrice?: number; // Minimum offer price
  name?: string; // NFT name
  price: number; // Current price
  rarity?: {
    // Rarity information
    rank?: number; // Rarity rank
    rarityScore?: number; // Rarity score
  };
  sellerId: string; // Seller account ID
  serialNumber: number; // NFT serial number
  status?: string; // Current status
  statusDate: Date; // Status update date
  tokenId: string; // Token ID
}

NftItemCreation

Data required to create a new NFT listing.

interface NftItemCreation {
  allowOffers: boolean; // Whether offers are allowed
  currency: string; // Currency token ID
  minOfferPrice: number; // Minimum offer price
  price: number; // Listing price
  serialNumber: number; // NFT serial number
  tokenId: string; // Token ID
}

NftItemId

Unique identifier for an NFT.

interface NftItemId {
  serialNumber: number; // NFT serial number
  tokenId: string; // Token ID
}

NftItemPriceEdition

Data for updating NFT price information.

interface NftItemPriceEdition {
  signature: string; // Required signature for price updates
  allowOffers: boolean; // Whether offers are allowed
  currency: string; // Currency token ID
  minOfferPrice?: number; // Minimum offer price
  price: number; // New price
}

NftItemDelist

Data for removing NFTs from sale.

interface NftItemDelist {
  signature: string; // Required signature for delisting
  nftItems: NftItemId[]; // Array of NFTs to delist
}

🎨 Collection Models

NftCollection

Complete NFT collection information.

interface NftCollection {
  _id?: string; // Database ID
  attributes?: Attribute[]; // Collection attributes
  createdAt?: Date; // Creation date
  creatorId?: string; // Creator account ID
  creatorName?: string; // Creator name
  description?: string; // Collection description
  highestCollectionOffer?: number; // Highest offer received
  holders?: number; // Number of holders
  imageCid: string; // Collection image CID
  imageType: string; // Image MIME type
  mainTag?: string; // Main category tag
  minPrice?: number; // Minimum price in collection
  minted?: number; // Number of minted NFTs
  name?: string; // Collection name
  networkVolume?: number; // Total trading volume
  nftsListed?: number; // Number of listed NFTs
  salesVolume: NftCollectionSalesVolume; // Network sales volume
  slug?: string; // Collection slug
  socialNetworks?: Array<string>; // Social media links
  supply?: number; // Total supply
  tokenId?: string; // Token ID
  verificationType?: number; // Verification status
}

| Value | Status | | ----- | ------------- | | -1 | SCAM | | 0 | NONE | | 2 | RRSS | | 4 | DOXXED | | 6 | FEATURED | | 8 | FEATURED_HOME | | 10 | VERIFIED |

Attribute

Individual attribute/trait information.

interface Attribute {
  count: number; // Number of NFTs with this attribute
  currency?: string; // Currency for pricing
  minPrice?: number; // Minimum price for this attribute
  rarityPct?: number; // Rarity percentage
  total?: number; // Total count
  traitType: string; // Attribute category
  value: string; // Attribute value
}

Attributes

Collection of attributes.

interface Attributes {
  attribute: Array<Attribute>; // Array of attributes
}

NftCollectionNftItemsRarity

Rarity mapping for collection NFTs.

interface NftCollectionNftItemsRarity {
  _id?: string; // Database ID
  nftItemsRarityMap?: NftItemsRarityMap[]; // Rarity mappings
  tokenId?: string; // Token ID
}

NftItemsRarity

Individual NFT rarity information.

interface NftItemsRarity {
  rank: number; // Rarity rank
  rarityScore: number; // Rarity score
}

NftItemsRarityMap

Mapping of serial numbers to rarity data.

interface NftItemsRarityMap {
  serialNumber: NftItemsRarity; // Serial number mapped to rarity
}

NftStatusMap

Boolean mapping for NFT status.

interface NftStatusMap {
  [key: number]: boolean; // Serial number to status mapping
}

NftCollectionSalesVolume

Network sales volume information for an NFT collection.

interface NftCollectionSalesVolume {
  updatedAt: Date; // Last update date
  last24h: number; // Sales volume in the last 24 hours
  previous24h: number; // Sales volume in the previous 24 hours
  last7d: number; // Sales volume in the last 7 days
  previous7d: number; // Sales volume in the previous 7 days
  last30d: number; // Sales volume in the last 30 days
  previous30d: number; // Sales volume in the previous 30 days
}

🎨 Offer Models

NftItemOffer

Complete NFT item offer information.

interface NftItemOffer {
  _id?: string; // Database ID
  buyerId: string; // Buyer account ID
  buyerPrice: number; // Buyer's offer price
  createdAt: Date; // Offer creation date
  currency: string; // Currency token ID
  initialPrice: number; // Initial offer price
  lastBidder: 'BUYER' | 'SELLER'; // Who made the last bid
  nftItem?: {
    // Associated NFT information
    imageCid: string; // NFT image CID
    imageType: string; // Image MIME type
    name: string; // NFT name
  };
  sellerId?: string; // Seller account ID
  sellerPrice?: number; // Seller's counter-offer
  serialNumber: number; // NFT serial number
  tokenId: string; // Token ID
  updatedAt: Date; // Last update date
}

NftItemOfferCreation

Data required to create a new NFT offer.

interface NftItemOfferCreation {
  currency: string; // Currency token ID
  price: number; // Offer price
  serialNumber: number; // NFT serial number
  tokenId: string; // Token ID
}

NftItemOfferEdition

Data for updating an existing offer.

interface NftItemOfferEdition {
  buyerId: string; // Buyer account ID
  buyerPrice: number; // Buyer's offer price
  currency: string; // Currency token ID
  sellerId: string; // Seller account ID
  sellerPrice: number; // Seller's counter-offer
  tokenId: string; // Token ID
}

Note: The updateNftItemOffer() method accepts { price: number; signature: string | undefined } as parameter:

• Buyer updates: Requires approveHbarAllowance() but no signature
• Seller updates: Requires signature but no allowance

NftCollectionOffer

Collection offer information.

interface NftCollectionOffer {
  _id?: string; // Database ID
  buyerId: string; // Buyer account ID
  tokenId: string; // Token ID
  price: number; // Offer price
  currency: string; // Currency token ID
  createdAt: string; // Creation date
  status?: string; // Offer status
  statusDate?: string; // Status update date
}

NftCollectionOfferCreation

Data required to create a collection offer.

interface NftCollectionOfferCreation {
  tokenId: string; // Token ID
  price: number; // Offer price
  currency: string; // Currency token ID
}

NftCollectionOfferAcceptance

Data for accepting collection offers.

interface NftCollectionOfferAcceptance {
  id: string; // Offer ID
  serialNumber: number; // NFT serial number
}

UserOffer

Extended offer information including NFT details.

interface UserOffer extends NftItemOffer {
  totalBuyerPrice: number; // Total price from buyer
  nftItemListed: NftItem; // Associated NFT item
}

UserOfferPrice

Summary of user's offer prices.

interface UserOfferPrice {
  totalPriceCollectionsOffers: number; // Total collection offers
  totalPriceNftItemsOffers: number; // Total NFT item offers
  totalPrice: number; // Combined total
}

📊 Market Analytics Models

NftItemActivity

interface NftItemActivity {
  tokenId: string; // Token ID
  serialNumber: number; // Serial number
  collectionName: string; // Collection name
  verificationType: number; // Verification type
  name: string; // NFT name
  imageCid: string; // Image CID
  imageType: string; // Image type
  rank: number; // Rarity rank
  activityType: string; // Activity type
  subactivityType: string; // Sub-activity type
  price: number; // Price
  currency: string; // Currency
  priceUsd: number; // Price in USD
  buyerId: string; // Buyer ID
  sellerId: string; // Seller ID
  createdAt: string; // Creation date
  listedAt: string; // Listing date
  additionalId: number; // Additional ID
  transactionId: string; // Transaction ID
}

Made with ❤️ by the Kabila Team

📖 Documentation • 🐛 Report Issues • 💬 Community