@zenonft/sdk v1.0.2

ZenoNFT Marketplace SDK — 供 DApp、钱包、AI Agent 使用的 NFT 交易市场 SDK。

安装

npm install @zenonft/sdk

快速开始

import { ZenoNFTSDK } from '@zenonft/sdk';
import { createWalletClient, http } from 'viem';

const signer = createWalletClient({ ... });
const sdk = new ZenoNFTSDK({ chain: 'sepolia', signer });

签名安全

signer 由调用方注入（wallet/TEE/Agent），SDK 不管理私钥。

白标品牌配置

// 默认品牌
console.log(sdk.getBrand().name); // "ZenoNFT"

// 自定义品牌
sdk.setBrand({
  name: 'MyNFTMarket',
  shortName: 'MyNFT',
  primaryColor: '#ff6600',
  primaryColorHover: '#e55a00',
});

console.log(sdk.getBrand());
// { name: 'MyNFTMarket', shortName: 'MyNFT', primaryColor: '#ff6600', ... }

API 参考

ZenoNFTSDK（主入口）

| 属性/方法 | 类型 | 说明 | |---|---|---| | sdk.marketplace | MarketplaceSDK | 交易市场操作 | | sdk.factory | FactorySDK | 合集工厂 | | sdk.collection(address) | (addr: string) => CollectionSDK | 动态绑定合集 | | sdk.setSigner(signer) | (signer: WalletClient) => void | 设置/替换签名者 | | sdk.getChainConfig() | () => ChainConfig | 获取链配置 | | sdk.setBrand(config) | (config: Partial<BrandConfig>) => void | 设置白标品牌 | | sdk.getBrand() | () => BrandConfig | 获取当前品牌 |

MarketplaceSDK（交易市场）

写操作（需 signer）：

| 方法 | 参数 | 说明 | |---|---|---| | listItem(nftContract, tokenId, priceWei) | string, string\|number, string\|number\|bigint | 定价挂单 | | createAuction(nftContract, tokenId, startPrice, durationSec) | string, string\|number, string\|number\|bigint, number | 创建英式拍卖 | | buyItem(listingId, priceWei) | string\|number, string\|number\|bigint | 定价购买 | | placeBid(listingId, bidWei) | string\|number, string\|number\|bigint | 出价/竞拍 | | makeOffer(listingId, offerWei) | string\|number, string\|number\|bigint | 对固定价挂单出价 | | acceptOffer(listingId) | string\|number | 接受出价（仅卖家） | | endAuction(listingId) | string\|number | 结束拍卖 | | cancelListing(listingId) | string\|number | 取消挂单（仅卖家） |

只读查询：

| 方法 | 参数 | 返回 | |---|---|---| | getListing(listingId) | string\|number | Listing | | getActiveListings() | — | Listing[] | | getActiveListingsPaginated(offset, limit) | number, number | { result: Listing[], total: number } | | getListingCount() | — | number | | getOffer(listingId) | string\|number | Offer |

FactorySDK（合集工厂）

| 方法 | 参数 | 说明 | |---|---|---| | deployCollection(opts) | DeployCollectionOpts | 创建合集 | | deployAndBatchMint(opts) | DeployAndBatchMintOpts | 创建+批量铸造（一 TX） | | getAllCollections() | — | 返回 CollectionInfo[] | | getCollectionCount() | — | 合集数量 | | getDeployFee() | — | 部署费 (wei) |

DeployCollectionOpts：

{
  name: string;           // 合集名称
  symbol: string;         // 合集代号
  maxSupply: number | string | bigint;
  mintPrice?: number | string | bigint;   // 铸造价 (wei, 默认 0)
  royaltyBps?: number | string | bigint;  // 版税 (基点, 默认 0, 最大 1000)
  baseURI?: string;       // 元数据基 URI
  soulbound?: boolean;    // SBT? (默认 false)
  maxMintsPerAddress?: number | string | bigint;
}

CollectionSDK（合集实例）

通过 sdk.collection(address) 获取。

写操作（需 signer）：

| 方法 | 参数 | 说明 | |---|---|---| | mint(tokenURI) | string | 铸造 1 个 NFT | | mintBatch(quantity, tokenURI) | number, string | 批量铸造 | | ownerBatchMint(tokenURIs) | string[] | Owner 批量铸造 | | setMintingEnabled(enabled) | boolean | 开关铸造 | | setMintPrice(priceWei) | string\|number\|bigint | 改铸造价 | | setRoyalty(bps) | number | 版税 (≤1000) | | setBaseURI(uri) | string | 改基 URI | | setSoulbound(sbt) | boolean | 改 SBT 模式 | | addToWhitelist(addresses) | string[] | 加白名单 | | removeFromWhitelist(addresses) | string[] | 删白名单 | | withdraw() | — | 提取合约余额 |

只读查询：

| 方法 | 返回 | |---|---| | tokenURI(tokenId) | string | | totalMinted() | number | | ownerOf(tokenId) | string | | balanceOf(address) | number | | getInfo() | CollectionDetail |

类型

export type {
  SDKConfig, ChainConfig, BrandConfig,
  Listing, Offer, PaginatedListings,
  CollectionInfo, CollectionDetail,
  DeployCollectionOpts, DeployAndBatchMintOpts,
  TxResult, MintResult, DeployResult,
};
export { ZenoNFTSDK, DEFAULT_BRAND };

链支持

| 链 | Chain ID | 状态 | |---|---|---| | Sepolia | 11155111 | 已部署 |

合约地址 (Sepolia)

| 合约 | 地址 | |---|---| | NFTMarketplace | 0xeaD16C36B258D981a54B3A949732CEA953c5329A | | NFTFactory | 0xAc42Eb9E5f0A46CC56246258E5Ad9B87CfbcaA8A |