npm package: @hokko_io/marketplace
Description: Hokko.io Marketplace SDK
Latest version: 0.1.19

# Hokko Marketplace SDK

The official TypeScript SDK for interacting with the Hokko marketplace on the Sui blockchain. This SDK provides easy-to-use interfaces for trading NFTs, managing listings, making offers, and launching NFT collections.

## Installation

```bash
npm install @hokko_io/marketplace
# or
bun add @hokko_io/marketplace
```

## Quick Start

### Initialize the SDKs

```typescript
import { TradingSDK } from '@hokko_io/marketplace';
import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
import { KioskClient } from '@mysten/kiosk';

// Initialize Sui client
const suiClient = new SuiClient({
  url: getFullnodeUrl('mainnet'), // or 'testnet', 'devnet'
});

// Initialize Kiosk client
const kioskClient = new KioskClient({
  client: suiClient,
  network: 'mainnet', // or 'testnet', 'devnet'
});

// Initialize SDKs
// Reach out to us for the url
const tradingSDK = new TradingSDK('https://api.hokko.io', kioskClient);
```

## Trading SDK

### List an NFT

```typescript
import { Transaction } from '@mysten/sui/transactions';

const tx = new Transaction();

const transaction = await tradingSDK.list({
  tokenId: '0x123...', // NFT object ID
  price: 1000000000, // Price in MIST (1 SUI = 1,000,000,000 MIST)
  address: '0xabc...', // Your wallet address
  tx,
});

// Sign and execute the transaction
const result = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction
});
```

### Buy an NFT

```typescript
const tx = new Transaction();

const transaction = await tradingSDK.buy({
  listingId: '0x456...', // Listing object ID
  address: '0xdef...', // Buyer's wallet address
  tx,
});

// Sign and execute the transaction
const result = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction,
});
```

### Make Collection Offer

```typescript
const tx = new Transaction();

const transaction = await tradingSDK.makeCollectionOffer({
  type: '0x789::my_nft::MyNFT', // NFT type
  address: '0xghi...', // Your wallet address
  price: 500000000, // Offer price in MIST
  quantity: 3, // Number of NFTs you want to buy
  tx,
});

// Sign and execute the transaction
const result = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction,
});
```

### Accept Collection Offer

```typescript
const tx = new Transaction();

const transaction = await tradingSDK.acceptCollectionOffer({
  offerId: '0x789...', // Offer object ID
  address: '0xjkl...', // Your wallet address
  tokenId: '0x123...', // NFT you want to sell
  tx,
});

// Sign and execute the transaction
const result = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction,
});
```

<!-- ## Launchpad SDK -->
<!---->
<!-- ### Initialize a Launchpad Collection -->
<!---->
<!-- ```typescript -->
<!-- const tx = new Transaction(); -->
<!---->
<!-- const transaction = await launchpadSDK.initialize({ -->
<!--   tx, -->
<!--   type: '0x123::my_collection::MyCollection', -->
<!--   name: 'My Awesome Collection', -->
<!--   description: 'A collection of awesome NFTs', -->
<!--   supply: 1000, -->
<!--   price: 100000000, // 0.1 SUI in MIST -->
<!--   startTime: Date.now() + 86400000, // Start in 24 hours -->
<!--   maxItemsPerAddress: 5, -->
<!--   coverUrl: 'https://example.com/cover.jpg', -->
<!--   publisher: '0xabc...', // Publisher object ID -->
<!--   policy: '0xdef...', // Transfer policy object ID -->
<!--   policyCap: '0xghi...', // Policy cap object ID -->
<!--   whitelistConfig: { -->
<!--     price: 50000000, // 0.05 SUI for whitelist -->
<!--     supply: 100, -->
<!--     startTime: Date.now() + 43200000, // Whitelist starts in 12 hours -->
<!--   }, -->
<!-- }); -->
<!---->
<!-- // Sign and execute the transaction -->
<!-- const result = await suiClient.signAndExecuteTransaction({ -->
<!--   signer: keypair, -->
<!--   transaction, -->
<!-- }); -->
<!-- ``` -->
<!---->
<!-- ### Mint from Launchpad -->
<!---->
<!-- ```typescript -->
<!-- const tx = new Transaction(); -->
<!---->
<!-- // Split coins for payment -->
<!-- const [payment] = tx.splitCoins(tx.gas, [100000000]); // 0.1 SUI -->
<!---->
<!-- const transaction = await launchpadSDK.mint({ -->
<!--   tx, -->
<!--   type: '0x123::my_collection::MyCollection', -->
<!--   items: [payment], // Payment coins -->
<!--   auth: tx.pure.address('0x...'), // Authentication object if needed -->
<!--   collection: '0xjkl...', // Collection object ID -->
<!--   policy: '0xdef...', // Transfer policy object ID -->
<!--   payments: [payment], -->
<!-- }); -->
<!---->
<!-- // Sign and execute the transaction -->
<!-- const result = await suiClient.signAndExecuteTransaction({ -->
<!--   signer: keypair, -->
<!--   transaction, -->
<!-- }); -->
<!-- ``` -->
<!---->
## Advanced Usage

### Using Override Parameters for Better Performance

The SDK supports override parameters to skip API calls when you already have the required data:

```typescript
// List with override kiosk data
const tx = new Transaction();

const transaction = await tradingSDK.list({
  tokenId: '0x123...',
  price: 1000000000,
  address: '0xabc...',
  tx,
  overrideKiosk: {
    kioskId: '0xkiosk...',
    kioskOwnerCap: '0xcap...',
    isPersonal: true,
  },
});

// Buy multiple NFTs
const tx2 = new Transaction();

const transaction2 = await tradingSDK.multipleBuy({
  listings: [
    {
      tokenId: '0x123...',
      price: 1000000000,
      kiosk: '0xkiosk1...',
      sharedPurchaseCap: '0xcap1...',
      collectionType: '0x::collection::Type',
      kioskStandard: true,
    },
    {
      tokenId: '0x456...',
      price: 2000000000,
      kiosk: '0xkiosk2...',
      sharedPurchaseCap: '0xcap2...',
      collectionType: '0x::collection::Type',
      kioskStandard: true,
    },
  ],
  address: '0xbuyer...',
  tx: tx2,
});

// Sign and execute the transactions
const result1 = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction,
});

const result2 = await suiClient.signAndExecuteTransaction({
  signer: keypair,
  transaction: transaction2,
});
```

### Error Handling

```typescript
try {
  const tx = new Transaction();
  
  const transaction = await tradingSDK.buy({
    listingId: '0x456...',
    address: '0xdef...',
    tx,
  });
  
  const result = await suiClient.signAndExecuteTransaction({
    signer: keypair,
    transaction,
  });
  
  console.log('Transaction successful:', result.digest);
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('Listing not found or already sold');
  } else if (error.message.includes('insufficient funds')) {
    console.error('Not enough SUI to complete the transaction');
  } else {
    console.error('Transaction failed:', error.message);
  }
}
```

## API Reference

### TradingSDK Methods

- `list()` - List an NFT for sale
- `delist()` - Remove a listing
- `updateListing()` - Update listing price
- `buy()` - Purchase a single NFT
- `multipleBuy()` - Purchase multiple NFTs
- `makeCollectionOffer()` - Make an offer on a collection
- `acceptCollectionOffer()` - Accept a collection offer
- `revokeCollectionOffer()` - Revoke a collection offer
- `makeNftOffer()` - Make an offer on a specific NFT
- `acceptOffer()` - Accept an NFT offer
- `revokeNftOffer()` - Revoke an NFT offer
- `rejectOffer()` - Reject an NFT offer

<!-- ### LaunchpadSDK Methods -->
<!---->
<!-- - `initialize()` - Initialize a new launchpad collection -->
<!-- - `mint()` - Mint NFTs from a launchpad -->
<!-- - `changeTimestamp()` - Update launch timestamps -->
<!-- - `setupWhitelist()` - Configure whitelist addresses -->
<!-- - `pause()` - Pause a launchpad -->
<!-- - `resume()` - Resume a paused launchpad -->
<!-- - `withdraw()` - Withdraw funds from a launchpad -->

## Types

All TypeScript interfaces are exported from the package for type safety:

```typescript
import type {
  ListingArgs,
  BuyListingArgs,
  CollectionMakeOfferArgs,
  initializeLaunchpadArgs,
  MintArgs,
} from '@hokko_io/marketplace';
```

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

## License

MIT License - see LICENSE file for details.