合约与 NFT API

合约与 NFT API 提供了 9 个方法，用于部署智能合约、读写合约状态以及管理 NFT。

合约方法

方法	参数	返回值	描述
getUserContracts(options?)	options?: ContractListOptions	ApiResponse<Contract[]>	列出已认证用户部署的合约。
getContractDetails(contractAddress, chainId)	contractAddress: string, chainId: string	ApiResponse<Contract>	返回已部署合约的元数据和 ABI。
readContract(params)	params: ContractReadParams	ApiResponse<unknown>	调用合约上的只读（view/pure）函数。
writeContract(params)	params: ContractWriteParams	ApiResponse<ContractWriteResult>	向合约发送状态变更交易。
deployContract(params)	params: ContractDeployParams	ApiResponse<ContractDeployResult>	将编译后的合约部署到链上。

NFT 方法

方法	参数	返回值	描述
getUserNFTs(walletAddress, options?)	walletAddress: string, options?: NFTListOptions	ApiResponse<NFT[]>	列出某钱包地址持有的 NFT。
getNFTDetails(contractAddress, tokenId, chainId)	contractAddress: string, tokenId: string, chainId: string	ApiResponse<NFT>	返回特定 NFT 的元数据。
getNFTCollection(contractAddress, chainId, options?)	contractAddress: string, chainId: string, options?: NFTCollectionOptions	ApiResponse<NFTCollection>	返回集合级别的元数据和代币列表。
transferNFT(params)	params: NFTTransferParams	ApiResponse<NFTTransfer>	将 NFT 从一个地址转移到另一个地址。

类型

Contract

interface Contract {
  address: string;
  chainId: string;
  name: string;
  /** Contract type / standard (e.g. "ERC20", "ERC721", "custom"). */
  type: string;
  abi: Record<string, unknown>[];
  deployedBy: string;
  deployTxHash: string;
  blockNumber: number;
  verified: boolean;
  createdAt: string;
}

ContractListOptions

interface ContractListOptions {
  chainId?: string;
  type?: string;
  limit?: number;
  cursor?: string;
}

ContractReadParams

interface ContractReadParams {
  /** Contract address. */
  contractAddress: string;
  /** Chain ID. */
  chainId: string;
  /** Function name to call. */
  functionName: string;
  /** ABI of the contract (or at least the target function). */
  abi: Record<string, unknown>[];
  /** Arguments to pass to the function. */
  args?: unknown[];
}

ContractWriteParams

interface ContractWriteParams {
  /** Contract address. */
  contractAddress: string;
  /** Chain ID. */
  chainId: string;
  /** Function name to call. */
  functionName: string;
  /** ABI of the contract (or at least the target function). */
  abi: Record<string, unknown>[];
  /** Arguments to pass to the function. */
  args?: unknown[];
  /** Wallet address sending the transaction. */
  from: string;
  /** Native value to send (in wei). */
  value?: string;
  /** Gas limit override. */
  gasLimit?: string;
}

ContractWriteResult

interface ContractWriteResult {
  txId: string;
  txHash?: string;
  status: 'queued' | 'submitted' | 'confirmed' | 'failed';
}

ContractDeployParams

interface ContractDeployParams {
  /** Chain to deploy on. */
  chainId: string;
  /** Compiled bytecode (hex string). */
  bytecode: string;
  /** Contract ABI. */
  abi: Record<string, unknown>[];
  /** Constructor arguments. */
  constructorArgs?: unknown[];
  /** Wallet address deploying the contract. */
  from: string;
  /** Optional: human-readable name for dashboard tracking. */
  name?: string;
}

ContractDeployResult

interface ContractDeployResult {
  txId: string;
  txHash?: string;
  contractAddress?: string;
  status: 'queued' | 'submitted' | 'confirmed' | 'failed';
}

NFT

interface NFT {
  contractAddress: string;
  tokenId: string;
  chainId: string;
  name: string;
  description?: string;
  imageUrl?: string;
  animationUrl?: string;
  attributes: { trait_type: string; value: string | number }[];
  owner: string;
  standard: 'ERC721' | 'ERC1155';
  balance?: string;
}

NFTListOptions

interface NFTListOptions {
  chainId?: string;
  contractAddress?: string;
  limit?: number;
  cursor?: string;
}

NFTCollection

interface NFTCollection {
  contractAddress: string;
  chainId: string;
  name: string;
  symbol: string;
  description?: string;
  imageUrl?: string;
  totalSupply: string;
  standard: 'ERC721' | 'ERC1155';
  floorPrice?: string;
  tokens: NFT[];
  hasMore: boolean;
  cursor?: string;
}

NFTCollectionOptions

interface NFTCollectionOptions {
  limit?: number;
  cursor?: string;
}

NFTTransferParams

interface NFTTransferParams {
  contractAddress: string;
  tokenId: string;
  chainId: string;
  from: string;
  to: string;
  /** For ERC1155, the quantity to transfer. Default 1. */
  amount?: string;
}

NFTTransfer

interface NFTTransfer {
  txId: string;
  txHash?: string;
  status: 'queued' | 'submitted' | 'confirmed' | 'failed';
  contractAddress: string;
  tokenId: string;
  from: string;
  to: string;
}

示例

读取合约

const res = await engine.readContract({
  contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  chainId: 'ethereum',
  functionName: 'balanceOf',
  abi: [
    {
      name: 'balanceOf',
      type: 'function',
      stateMutability: 'view',
      inputs: [{ name: 'account', type: 'address' }],
      outputs: [{ name: '', type: 'uint256' }],
    },
  ],
  args: ['0xABC...'],
});

if (res.success) {
  console.log('USDC balance (raw):', res.data);
}

写入合约

const res = await engine.writeContract({
  contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  chainId: 'ethereum',
  functionName: 'transfer',
  abi: [
    {
      name: 'transfer',
      type: 'function',
      stateMutability: 'nonpayable',
      inputs: [
        { name: 'to', type: 'address' },
        { name: 'amount', type: 'uint256' },
      ],
      outputs: [{ name: '', type: 'bool' }],
    },
  ],
  args: ['0xDEF...', '1000000'],
  from: '0xABC...',
});

if (res.success && res.data) {
  console.log('Transaction queued:', res.data.txId);
}

部署合约

const res = await engine.deployContract({
  chainId: 'ethereum',
  bytecode: '0x6080604052...',
  abi: compiledAbi,
  constructorArgs: ['My Token', 'MTK', 18],
  from: '0xABC...',
  name: 'MyToken',
});

if (res.success && res.data) {
  console.log('Deploy tx:', res.data.txId);
  // Poll until confirmed to get the contract address
}

列出 NFT

const res = await engine.getUserNFTs('0xABC...', {
  chainId: 'ethereum',
  limit: 20,
});

if (res.success && res.data) {
  for (const nft of res.data) {
    console.log(`${nft.name} (#${nft.tokenId}) - ${nft.contractAddress}`);
  }
}

转移 NFT

const res = await engine.transferNFT({
  contractAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  tokenId: '1234',
  chainId: 'ethereum',
  from: '0xABC...',
  to: '0xDEF...',
});

if (res.success && res.data) {
  console.log('NFT transfer queued:', res.data.txId);
}

后续步骤

• Wallet API -- 钱包余额和交易。
• Webhooks API -- 订阅合约事件。