TypeScript SDK

Key Features

Full TypeScript Support: Complete type definitions for all API endpoints and responses
IntelliSense Integration: Auto-completion and inline documentation in your IDE
Error Handling: Built-in error handling with typed error responses
Authentication: Flexible authentication with API keys and secret keys
Comprehensive Coverage: Support for all Lootex Plus API endpoints
Zero Dependencies: Lightweight with minimal external dependencies

Installation

npm install lootex-plus

Quick Start

Get started with the SDK in just a few lines of code:

import { createLootexPlusClient } from "lootex-plus";

// Initialize the client with your API credentials
const lootex = createLootexPlusClient({
  apiKey: 'YOUR_API_KEY',
  secretKey: 'YOUR_SECRET_KEY' // optional, only needed for server-wallet operations
});

// Fetch asset information
const { data, error } = await lootex.getAsset({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  tokenId: '1'
});

if (error) {
  console.error('Failed to fetch asset:', error);
  return;
}

console.log('Asset name:', data?.name);
console.log('Asset image:', data?.imageUrl);

Authentication

The SDK supports flexible authentication to match your use case:

API Key (Required)

Your API key is required for all endpoints and provides access to read operations, marketplace functionality, and asset management.

Secret Key (Optional)

Your secret key is only required for server-wallet operations like minting and transferring tokens. This provides enhanced security for sensitive operations.

// Basic setup for read-only operations
const client = createLootexPlusClient({
  apiKey: 'your-api-key'
});

// Full setup for all operations including project wallet
const client = createLootexPlusClient({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key' // enables mint and transfer operations
});

Note: Keep your secret key secure and never expose it in client-side code. Project wallet operations should only be performed in secure server environments.

API Reference

The SDK provides comprehensive access to all Lootex Plus API endpoints, organized into logical categories for easy navigation and usage.

Assets

Manage and explore NFT assets across supported blockchains.

Get Asset

Retrieve information about a specific NFT asset.

const { data, error } = await lootex.getAsset({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  tokenId: '1'
});

// data contains AssetDto with asset information
console.log(data?.name); // "Cool NFT"
console.log(data?.imageUrl); // "https://example.com/image.png"

Parameters:

chainId (number): The blockchain chain ID
contractAddress (string): The NFT contract address
tokenId (string): The token ID

Returns: AssetDto with asset details including name, description, image URL, schema, and listing information.

Search Assets

Explore and search for assets with various filters.

const { data, error } = await lootex.searchAssets({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  ownerAddress: '0x1234567890abcdef1234567890abcdef12345678',
  search: 'cool',
  isVerified: true,
  hasListings: true,
  page: 1,
  limit: 10
});

// data contains AssetPaginationDto with paginated results
console.log(data?.data); // Array of AssetDto
console.log(data?.pagination.total); // Total number of assets

Parameters:

chainId (number, optional): Filter by chain ID
contractAddress (string, optional): Filter by contract address
ownerAddress (string, optional): Filter by owner address
search (string, optional): Search by asset name
isVerified (boolean, optional): Filter verified assets only
hasListings (boolean, optional): Filter assets with active listings
page (number, optional): Page number for pagination
limit (number, optional): Number of items per page

Returns: AssetPaginationDto with paginated list of assets.

Collections

Discover and manage NFT collections with comprehensive metadata and verification status.

Get Collection

Retrieve information about a specific collection.

const { data, error } = await lootex.getCollection({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a'
});

// data contains CollectionDto with collection information
console.log(data?.name); // "Cool NFT Collection"
console.log(data?.isVerified); // true

Parameters:

chainId (number): The blockchain chain ID
contractAddress (string): The collection contract address

Returns: CollectionDto with collection details.

Search Collections

Explore and search for collections.

const { data, error } = await lootex.searchCollections({
  chainId: 1868,
  search: 'cool',
  isVerified: true,
  page: 1,
  limit: 10
});

// data contains paginated collection results
console.log(data?.data); // Array of CollectionDto

Parameters:

chainId (number, optional): Filter by chain ID
search (string, optional): Search by collection name
isVerified (boolean, optional): Filter verified collections only
page (number, optional): Page number for pagination
limit (number, optional): Number of items per page

Returns: Paginated list of collections. Get trending collections for a specific time range.

const { data, error } = await lootex.getTrendingCollections({
  chainId: 1868,
  timeRange: 'one_day' // 'one_hour' | 'one_day' | 'one_week' | 'one_month'
});

// data contains trending collections
console.log(data?.data); // Array of trending collections

Parameters:

chainId (number): The blockchain chain ID
timeRange (string, optional): Time range for trending data
- 'one_hour'
- 'one_day'
- 'one_week'
- 'one_month'

Returns: List of trending collections.

Orders

Create, manage, and interact with marketplace orders for buying, selling, and trading NFTs.

Get Order

Retrieve information about a specific order.

const { data, error } = await lootex.getOrder({
  hash: '0xaabdbab8b4485b784e00d80943964da179a92257248e665b0f035d4daabe85f8'
});

// data contains OrderDto with order information
console.log(data?.unitPrice); // 1
console.log(data?.priceSymbol); // "ETH"

Parameters:

hash (string): The order hash

Returns: OrderDto with order details.

Create Orders

Create new orders (requires signature).

const { data, error } = await lootex.createOrders({
  signature: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
});

// data contains created orders
console.log(data?.orders); // Array of created orders

Parameters:

signature (string): The signature for the orders

Returns: List of created orders.

List Orders

List orders for sale.

const { data, error } = await lootex.listOrders({
  chainId: 1868,
  accountAddress: '0x7D878A527e86321aECd80A493E584117A907A0AB',
  items: [
    {
      tokenAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
      tokenType: 'ERC721',
      tokenId: '142',
      unitPrice: '0.1',
      quantity: '1',
      currencyAddress: '0x4200000000000000000000000000000000000006',
      currencySymbol: 'WETH',
      currencyDecimals: 18,
      startTime: 1753328679,
      endTime: 1911066278,
      fees: [
        {
          recipient: '0x7D878A527e86321aECd80A493E584117A907A0AB',
          bps: 250
        }
      ]
    }
  ]
});

// data contains execution result
console.log(data?.success); // true

Parameters:

chainId (number): The blockchain chain ID
accountAddress (string): The account address listing the orders
items (ListOrderItemDto[]): Array of items to list

Returns: Execution result for listing orders.

Buy Orders

Buy existing orders.

const { data, error } = await lootex.buyOrders({
  chainId: 1868,
  orderHashes: [
    '0xaabdbab8b4485b784e00d80943964da179a92257248e665b0f035d4daabe85f8'
  ],
  accountAddress: '0x0000000000000000000000000000000000000000'
});

// data contains execution result
console.log(data?.success); // true

Parameters:

chainId (number): The blockchain chain ID
orderHashes (string[]): Array of order hashes to buy
accountAddress (string): The account address buying the orders

Returns: Execution result for buying orders.

Cancel Orders

Cancel existing orders.

const { data, error } = await lootex.cancelOrders({
  chainId: 1868,
  orderHashes: [
    '0xaabdbab8b4485b784e00d80943964da179a92257248e665b0f035d4daabe85f8'
  ]
});

// data contains execution result
console.log(data?.success); // true

Parameters:

chainId (number): The blockchain chain ID
orderHashes (string[]): Array of order hashes to cancel

Returns: Execution result for canceling orders.

Drops

Participate in NFT drops and claim tokens with built-in validation and stage management.

Get Drop

Retrieve information about a specific drop.

const { data, error } = await lootex.getDrop({
  chainId: 1868,
  contractAddress: '0xc87d591859d6497490d658337d91eb8ec1d625b6',
  accountAddress: '0x1234567890abcdef1234567890abcdef12345678' // optional
});

// data contains DropDto with drop information
console.log(data?.name); // "Cool Drop"
console.log(data?.claimStages); // Array of claim stages

Parameters:

chainId (number): The blockchain chain ID
contractAddress (string): The drop contract address
accountAddress (string, optional): The account address for personalized drop data

Returns: DropDto with drop details including claim stages and statistics.

Claim Drop

Claim tokens from a drop.

const { data, error } = await lootex.claimDrop({
  chainId: 1868,
  contractAddress: '0xc87d591859d6497490d658337d91eb8ec1d625b6',
  quantity: 1,
  accountAddress: '0x1234567890abcdef1234567890abcdef12345678',
  recipientAddress: '0x742D35Cc6634C0532925a3b8D4c4D9e2c8E0B3E9' // optional
});

// data contains claim result
console.log(data?.success); // true

Parameters:

chainId (number): The blockchain chain ID
contractAddress (string): The drop contract address
quantity (number): Number of tokens to claim
accountAddress (string): The account address claiming the drop
recipientAddress (string, optional): The recipient address (defaults to accountAddress)

Returns: Claim execution result.

Project Wallet

Perform secure server-side operations including minting and transferring tokens with enterprise-grade security.

Security Note: These operations require a secret key and should only be performed in secure server environments.

Mint

Mint new tokens using the project wallet.

const { data, error } = await lootex.serverWalletMint({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  recipientAddress: '0x742D35Cc6634C0532925a3b8D4c4D9e2c8E0B3E9',
  tokenId: 123, // optional for ERC721
  quantity: 1, // optional for ERC1155
  metadata: { // optional
    name: 'Cool NFT',
    description: 'This is a cool NFT'
  }
});

// data contains mint result
console.log(data?.transactionHash); // "0x..."

Parameters:

chainId (number): The blockchain chain ID
contractAddress (string): The contract address to mint from
recipientAddress (string): The recipient wallet address
tokenId (number, optional): Token ID for ERC721 mints
quantity (number, optional): Quantity for ERC1155 mints
metadata (Record, optional): Additional metadata

Returns: Mint execution result with transaction details.

Transfer

Transfer tokens using the project wallet.

const { data, error } = await lootex.serverWalletTransfer({
  type: 'erc721', // 'native' | 'erc20' | 'erc721' | 'erc1155'
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a', // required for erc20, erc721, erc1155
  recipientAddress: '0x742D35Cc6634C0532925a3b8D4c4D9e2c8E0B3E9',
  amount: '1000000000000000000', // required for native, erc20, erc1155
  tokenId: '123', // required for erc721, erc1155
  data: '0x', // optional for erc1155
  metadata: { // optional
    note: 'Transfer from project wallet'
  }
});

// data contains TransferResponseDto with transfer details
console.log(data?.transactionHash); // "0x..."
console.log(data?.status); // "pending"

Parameters:

type (string): Token type - 'native', 'erc20', 'erc721', or 'erc1155'
chainId (number): The blockchain chain ID
contractAddress (string, optional): Contract address (required for ERC20, ERC721, ERC1155)
recipientAddress (string): The recipient wallet address
amount (string, optional): Transfer amount in smallest unit (required for native, ERC20, ERC1155)
tokenId (string, optional): Token ID (required for ERC721, ERC1155)
data (string, optional): Additional data for ERC1155 transfers
metadata (Record, optional): Additional metadata

Returns: TransferResponseDto with transfer details including transaction hash and status.

Error Handling

The SDK provides consistent error handling across all methods. Each method returns an object with data and error properties, allowing you to handle errors gracefully:

const { data, error } = await lootex.getAsset({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  tokenId: '1'
});

if (error) {
  console.error('API Error:', error);
  return;
}

// Use data safely with optional chaining
console.log(data?.name);

Common Error Scenarios

Authentication Errors: Invalid or missing API keys
Validation Errors: Invalid parameters or missing required fields
Rate Limiting: Too many requests in a short time period
Network Errors: Connection issues or timeout
Server Errors: Internal API errors (rare)

Best Practices

// Always check for errors first
const { data, error } = await lootex.searchAssets({
  chainId: 1868,
  search: 'cool'
});

if (error) {
  // Handle specific error types
  if (error.status === 401) {
    console.error('Authentication failed. Check your API key.');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded. Try again later.');
  } else {
    console.error('Unexpected error:', error);
  }
  return;
}

// Process data safely
if (data?.data) {
  data.data.forEach(asset => {
    console.log(`Found asset: ${asset.name}`);
  });
}

TypeScript Support

The SDK is built with TypeScript from the ground up, providing complete type safety and excellent developer experience:

Full Type Safety

All parameters, return types, and error objects are fully typed:

import { createLootexPlusClient, type components } from "lootex-plus";

const client = createLootexPlusClient({
  apiKey: 'your-api-key'
});

// TypeScript provides full IntelliSense and type checking
const { data, error } = await client.getAsset({
  chainId: 1868,
  contractAddress: '0xfc8e7bda94874f6baa591dd70af0fda1fca201a',
  tokenId: '1'
});

// data is typed as components['schemas']['AssetDto'] | undefined
// error is typed with proper error structure

IDE Integration

Enjoy full IntelliSense support in VS Code, WebStorm, and other TypeScript-aware editors:

Auto-completion for all method parameters
Type checking for all return values
Inline documentation for all properties
Error detection for invalid parameter combinations

Complete Example

Here’s a comprehensive example demonstrating multiple SDK features in a real-world scenario:

import { createLootexPlusClient } from "lootex-plus";

// Initialize client with both API and secret keys for full functionality
const client = createLootexPlusClient({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key' // for project wallet operations
});

async function nftMarketplaceExample() {
  try {
    // 1. Search for trending collections
    console.log('🔍 Searching for trending collections...');
    const { data: trendingCollections, error: trendingError } = await client.getTrendingCollections({
      chainId: 1868,
      timeRange: 'one_day'
    });

    if (trendingError) {
      console.error('Failed to fetch trending collections:', trendingError);
      return;
    }

    console.log(`Found ${trendingCollections?.data?.length || 0} trending collections`);

    // 2. Get details of the first trending collection
    if (trendingCollections?.data?.[0]) {
      const collection = trendingCollections.data[0];
      console.log(`📊 Top collection: ${collection.name}`);

      // 3. Search for assets in this collection
      const { data: assets, error: assetsError } = await client.searchAssets({
        chainId: collection.chainId,
        contractAddress: collection.contractAddress,
        hasListings: true,
        limit: 5
      });

      if (assetsError) {
        console.error('Failed to fetch assets:', assetsError);
        return;
      }

      console.log(`Found ${assets?.data?.length || 0} assets with listings`);

      // 4. Get details of the first asset
      if (assets?.data?.[0]) {
        const asset = assets.data[0];
        console.log(`🎨 Asset: ${asset.name} (Token ID: ${asset.tokenId})`);

        // 5. Get the asset's current listing information
        if (asset.bestListing) {
          console.log(`💰 Best price: ${asset.bestListing.unitPrice} ${asset.bestListing.priceSymbol}`);
        }

        // 6. Example: Transfer the asset using project wallet (if you own it)
        if (client.serverWalletTransfer) {
          console.log('🚀 Attempting to transfer asset...');
          const { data: transfer, error: transferError } = await client.serverWalletTransfer({
            type: 'erc721',
            chainId: asset.chainId,
            contractAddress: asset.contractAddress,
            recipientAddress: '0x742D35Cc6634C0532925a3b8D4c4D9e2c8E0B3E9',
            tokenId: asset.tokenId,
            metadata: {
              note: 'Transfer from marketplace example'
            }
          });

          if (transferError) {
            console.error('Transfer failed:', transferError);
          } else {
            console.log(`✅ Transfer successful! Transaction: ${transfer?.transactionHash}`);
          }
        }
      }
    }

    // 7. Search for drops
    console.log('🎁 Searching for active drops...');
    const { data: drops, error: dropsError } = await client.getDrop({
      chainId: 1868,
      contractAddress: '0xc87d591859d6497490d658337d91eb8ec1d625b6',
      accountAddress: '0x1234567890abcdef1234567890abcdef12345678'
    });

    if (dropsError) {
      console.error('Failed to fetch drops:', dropsError);
    } else {
      console.log(`🎯 Found drop: ${drops?.name}`);
      console.log(`📅 Claim stages: ${drops?.claimStages?.length || 0}`);
    }

  } catch (error) {
    console.error('Unexpected error:', error);
  }
}

// Run the example
nftMarketplaceExample().catch(console.error);

This example demonstrates:

Error handling for each API call
Progressive data fetching from collections to assets
Project wallet operations with proper security
Real-world workflow from discovery to action
Comprehensive logging for debugging and monitoring

Getting started

Core APIs

Server Wallet APIs

Key Features

Installation

Quick Start

Authentication

API Key (Required)

Secret Key (Optional)

API Reference

Assets

Get Asset

Search Assets

Collections

Get Collection

Search Collections

Orders

Get Order

Create Orders

List Orders

Buy Orders

Cancel Orders

Drops

Get Drop

Claim Drop

Project Wallet

Mint

Transfer

Error Handling

Common Error Scenarios

Best Practices

TypeScript Support

Full Type Safety

IDE Integration

Complete Example

​Key Features

​Installation

​Quick Start

​Authentication

​API Key (Required)

​Secret Key (Optional)

​API Reference

​Assets

​Get Asset

​Search Assets

​Collections

​Get Collection

​Search Collections

​Get Trending Collections

​Orders

​Get Order

​Create Orders

​List Orders

​Buy Orders

​Cancel Orders

​Drops

​Get Drop

​Claim Drop

​Project Wallet

​Mint

​Transfer

​Error Handling

​Common Error Scenarios

​Best Practices

​TypeScript Support

​Full Type Safety

​IDE Integration

​Complete Example

Key Features

Installation

Quick Start

Authentication

API Key (Required)

Secret Key (Optional)

API Reference

Assets

Get Asset

Search Assets

Collections

Get Collection

Search Collections

Get Trending Collections

Orders

Get Order

Create Orders

List Orders

Buy Orders

Cancel Orders

Drops

Get Drop

Claim Drop

Project Wallet

Mint

Transfer

Error Handling

Common Error Scenarios

Best Practices

TypeScript Support

Full Type Safety

IDE Integration

Complete Example