> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootexplus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> A fully typed TypeScript SDK for seamless integration with the Lootex Plus API. Features comprehensive NFT operations, marketplace functionality, and project wallet management with complete type safety and IntelliSense support.

### 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:

```typescript theme={null}
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.

```typescript theme={null}
// 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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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

Get trending collections for a specific time range.

```typescript theme={null}
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.

```typescript theme={null}
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).

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
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