Typescript SDK

SUI APIs & Commong Blockchain Fetching Methods

Method / HookTypeDescriptionExampleAction
getAdjustedPriceFunctionCalculates the NFT price in human-readable format using coin decimals.
getAdjustedPrice(offer: SellOffer) => "12.34"
selectedOfferDecimalsHook (useMemo)Determines the number of decimals for the selected offer's currency.
selectedOfferDecimals = 9
fetchUserBalancesAsync Function (useCallback)Fetches the user's ART20 token balances from the blockchain using client.getOwnedObjects with a filter for ART20::UserBalance.
fetchUserBalances() => ["0xobjId1", "0xobjId2", ...]
useContractAddressesHookReturns contract addresses (artinalsAddress, saleAddress, marketAddress, marketUpgradeAddress) based on the current network.
useContractAddresses() => { marketAddress: "0x...", ... }
useCoinsHookFetches coin metadata and user coin balances using SuiClient. It internally uses getCoins, fetchCoinMetadata, and fetchCoins.
useCoins() => [{ coinType: "0x...", totalBalance: "1000000000", decimals: 9, ... }, ...]

TypeScript Interfaces

InterfaceDescriptionExampleAction
BatchBuyOffersAcceptedRepresents a batch of accepted buy offers with total cost and total filled.
{
  accepter: "0xabc...",
  total_filled: "3",
  total_cost: "45000000000",
  timestamp: "1630000000000",
  ledger_id: "0xledger...",
  offers: [BuyOfferAccepted, ...]
}
BatchOffersAcceptedRepresents a batch of accepted sell offers.
{
  accepter: "0xdef...",
  total_filled: "2",
  total_cost: "30000000000",
  timestamp: "1630000001000",
  ledger_id: "0xledger...",
  offers: [OfferAccepted, ...]
}
BuyOfferAcceptedRepresents an accepted buy offer with payment details.
{
  offer_id: "0x123...",
  buyer: "0xbuyer...",
  collection_id: "0xcollection...",
  requested_asset_count: "2",
  offered_currency: { name: "TEST" },
  offered_amount: "50000000000",
  timestamp: "1630000002000",
  ledger_id: "0xledger..."
}
BuyOfferCancelledRepresents a cancelled buy offer.
{
  offer_id: "0x456...",
  buyer: "0xbuyer...",
  collection_id: "0xcollection...",
  requested_asset_count: "1",
  offered_currency: { name: "TEST" },
  offered_amount: "25000000000",
  timestamp: "1630000003000",
  ledger_id: "0xledger..."
}
BuyOfferCreatedRepresents a newly created buy offer.
{
  offer_id: "0x789...",
  buyer: "0xbuyer...",
  collection_id: "0xcollection...",
  requested_asset_count: "3",
  offered_currency: { name: "TEST" },
  offered_amount: "75000000000",
  timestamp: "1630000004000",
  ledger_id: "0xledger..."
}
OfferAcceptedRepresents an accepted sell offer with NFT asset IDs.
{
  offer_id: "0xabc...",
  offerer: "0xofferer...",
  accepter: "0xaccepter...",
  collection_id: "0xcollection...",
  offered_asset_ids: ["34", "62"],
  requested_currency: { name: "TEST" },
  requested_amount: "34000000000",
  timestamp: "1630000005000",
  ledger_id: "0xledger..."
}
OfferCancelledRepresents a cancelled sell offer.
{
  offer_id: "0xdef...",
  offerer: "0xofferer...",
  collection_id: "0xcollection...",
  offered_asset_ids: ["15", "20"],
  requested_currency: { name: "TEST" },
  requested_amount: "50000000000",
  timestamp: "1630000006000"
}
OfferCreatedRepresents a newly created sell offer.
{
  offer_id: "0xghi...",
  offerer: "0xofferer...",
  collection_id: "0xcollection...",
  offered_asset_ids: ["10", "22", "33"],
  requested_currency: { name: "TEST" },
  requested_amount: "60000000000",
  timestamp: "1630000007000",
  ledger_id: "0xledger..."
}
TradeLedgerCreatedRepresents a newly created trade ledger with collection details.
{
  collection_id: "0xcollection...",
  creator: "0xcreator...",
  name: "ART 6",
  description: "A sample NFT collection",
  uri: { url: "https://example.com/metadata.json" },
  logo_uri: { url: "https://example.com/logo.png" },
  current_supply: "10",
  max_supply: "100",
  is_mutable: true,
  has_deny_list_authority: false,
  deny_list_size: "0",
  currency_type: { name: "TEST" },
  ledger_id: "0xledger...",
  timestamp: "1630000008000"
}
TypeNameA simple type representing a type name.
{ name: "TEST" }
UrlA simple type representing a URL.
{ url: "https://example.com" }

Create Sell Offer


createSellOffer<CURRENCY>(
  registry: LedgerRegistry,
  ledger: TradeLedger,
  collectionCap: CollectionCap,
  nfts: NFT[],
  senderBalances: UserBalance[],
  requestedAmountPerNFT: number,
  nftAmount: number,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the provided NFT collection and user balances match the ledger.
- Extracts the first 'nftAmount' NFTs from the input 'nfts' vector.
- Deducts the corresponding user balance by reducing senderBalances.
- Creates a new sell offer with a specified price per NFT.
- Updates ledger indices (e.g. price index, offer table) for quick discovery.
- Emits an OfferCreated event with the offer details.

Sui Client Methods:
- Uses 'createRobustClient(network)' to create a Sui client.
- Builds a Transaction using 'new Transaction()' from @mysten/sui/transactions.
- Sets the gas budget via `tx.setGasBudget(200000000)`.
- Constructs a moveCall with:
  - target: `${marketAddress}::MARKET::create_sell_offer`
  - arguments: ledger registry, trade ledger, collection cap, NFT vector, user balance vector, price per NFT, nft amount, clock object.
  - typeArguments: [CURRENCY] (the token used for the offer)
- Serializes the transaction with `tx.serialize()` and signs it using `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

// Example function to create a sell offer.
async function createSellOfferExample() {
  const client = createRobustClient("testnet"); // or "mainnet"
  const tx = new Transaction();
  tx.setGasBudget(200000000);

  // Assume these objects are already defined:
  // registry, ledger, collectionCap, nfts, senderBalances, requestedAmountPerNFT, nftAmount, clock, ctx
  // And marketAddress & coinType are available from context/config.
  
  tx.moveCall({
    target: `${marketAddress}::MARKET::create_sell_offer`,
    arguments: [
      tx.object(registry),
      tx.object(ledger),
      tx.object(collectionCap),
      tx.makeMoveVec({ type: "NFT", elements: nfts.map(nft => tx.object(nft)) }),
      tx.makeMoveVec({ type: "UserBalance", elements: senderBalances.map(balance => tx.object(balance)) }),
      tx.pure.u64(requestedAmountPerNFT.toString()),
      tx.pure.u64(nftAmount.toString()),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "offerId": "0xabc123def456",
  "message": "Sell offer created successfully",
  "timestamp": "2023-04-01T12:00:00Z"
}

Create Buy Offer


create_buy_offer<CURRENCY>(
  registry: LedgerRegistry,
  ledger: TradeLedger,
  collectionCap: CollectionCap,
  payment: Coin<CURRENCY>,
  nftCount: number,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the buyer’s payment is sufficient and the collection details match.
- Locks the buyer's payment in a coin object.
- Creates a buy offer for a specified number of NFTs with a calculated price per NFT.
- Updates the ledger's buy offer indices.
- Emits a BuyOfferCreated event.

Sui Client Methods:
- Uses a Sui client to create a Transaction (`new Transaction()`).
- Sets gas budget via `tx.setGasBudget(200000000)`.
- Constructs a moveCall with target: `${marketAddress}::MARKET::create_buy_offer` and necessary arguments.
- Serializes and signs the transaction using `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function createBuyOfferExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);

  // Assume these objects are defined: registry, ledger, collectionCap, payment, nftCount, clock, ctx, marketAddress, coinType.
  tx.moveCall({
    target: `${marketAddress}::MARKET::create_buy_offer`,
    arguments: [
      tx.object(registry),
      tx.object(ledger),
      tx.object(collectionCap),
      payment, // Pre-prepared payment coin
      tx.pure.u64(nftCount.toString()),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "offerId": "0xbuyoffer123",
  "message": "Buy offer created successfully",
  "timestamp": "2023-04-01T15:00:00Z"
}

Cancel Offer (Sell Offer)


cancel_offer<CURRENCY>(
  ledger: TradeLedger,
  offerId: ID,
  collectionCap: CollectionCap,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the offer is open and that the caller is the offer owner.
- Returns the NFTs to the seller.
- Updates the offer status to CANCELLED.
- Emits an OfferCancelled event.

Sui Client Methods:
- Creates a Transaction using `new Transaction()`.
- Sets the gas budget via `tx.setGasBudget(200000000)`.
- Calls `tx.moveCall()` with target: `${marketAddress}::MARKET::cancel_offer` and passes required objects.
- Serializes and signs the transaction with `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function cancelOfferExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);
  
  // Assume ledger, offerId, collectionCap, clock, ctx, marketAddress, and coinType are defined.
  tx.moveCall({
    target: `${marketAddress}::MARKET::cancel_offer`,
    arguments: [
      tx.object(ledger),
      tx.object(offerId),
      tx.object(collectionCap),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });

  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "message": "Offer cancelled successfully; NFTs returned to seller.",
  "transactionDigest": "0xdef456789abc",
  "timestamp": "2023-04-01T14:00:00Z"
}

Cancel Buy Offer


cancel_buy_offer<CURRENCY>(
  ledger: TradeLedger,
  offerId: ID,
  collectionCap: CollectionCap,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the buy offer is open and that the caller is the buyer.
- Retrieves the locked payment stored in the dynamic field.
- Returns the payment coin to the buyer.
- Updates the buy offer status to CANCELLED.
- Emits a BuyOfferCancelled event.

Sui Client Methods:
- Creates a Transaction via `new Transaction()` from @mysten/sui/transactions.
- Sets the gas budget using `tx.setGasBudget(200000000)`.
- Constructs a moveCall with target: `${marketUpgradeAddress}::MARKET::cancel_buy_offer` and the required arguments.
- Serializes the transaction with `tx.serialize()` and signs it using `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function cancelBuyOfferExample() {
  const client = createRobustClient("testnet"); // or "mainnet"
  const tx = new Transaction();
  tx.setGasBudget(200000000);

  // Assume the following objects are defined:
  // ledger, offerId, collectionCap, clock, ctx, marketUpgradeAddress, and coinType.
  tx.moveCall({
    target: `${marketUpgradeAddress}::MARKET::cancel_buy_offer`,
    arguments: [
      tx.object(ledger),
      tx.object(offerId),
      tx.object(collectionCap),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });

  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "message": "Buy offer cancelled successfully; payment returned to buyer.",
  "transactionDigest": "0xcancelbuyoffer123",
  "timestamp": "2023-04-01T16:30:00Z"
}

Accept Offer


accept_offer<CURRENCY>(
  ledger: TradeLedger,
  offerId: ID,
  payment: Coin<CURRENCY>,
  collectionCap: CollectionCap,
  amountToBuy: number,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the sell offer is open and that the buyer's payment is sufficient.
- Splits the payment if necessary and transfers the payment to the seller.
- Transfers the specified number of NFTs from the ledger to the buyer.
- Updates the offer status to FILLED (or PARTIALLY_FILLED if only a portion is bought).
- Emits an OfferAccepted event.

Sui Client Methods:
- Uses `new Transaction()` to create a transaction.
- Sets gas budget via `tx.setGasBudget(200000000)`.
- Calls `tx.moveCall()` with target: `${marketAddress}::MARKET::accept_offer` and required arguments.
- Serializes the transaction and signs it using `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function acceptOfferExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);

  // Assume these objects are defined: ledger, offerId, payment, collectionCap, amountToBuy, clock, ctx, marketAddress, coinType.
  tx.moveCall({
    target: `${marketAddress}::MARKET::accept_offer`,
    arguments: [
      tx.object(ledger),
      tx.object(offerId),
      tx.object(payment),
      tx.object(collectionCap),
      tx.pure.u64(amountToBuy.toString()),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "message": "Offer accepted successfully; NFTs transferred.",
  "transactionDigest": "0x123456789abcdef",
  "timestamp": "2023-04-01T13:00:00Z"
}

Accept Buy Offer


accept_buy_offer<CURRENCY>(
  ledger: TradeLedger,
  offerId: ID,
  nfts: NFT[],
  senderBalances: UserBalance[],
  collectionCap: CollectionCap,
  amountToSell: number,
  clock: Clock,
  ctx: TxContext
): void

Description:
- Validates that the buy offer is open and that the seller has enough NFTs.
- Transfers NFTs from the seller to the buyer.
- Transfers the payment (locked in the buy offer) to the seller.
- Updates the buy offer status to FILLED or PARTIALLY_FILLED.
- Emits a BuyOfferAccepted event.

Sui Client Methods:
- Uses `new Transaction()` to create a transaction.
- Sets the gas budget with `tx.setGasBudget(200000000)`.
- Calls `tx.moveCall()` with target: `${marketAddress}::MARKET::accept_buy_offer`.
- Serializes the transaction and signs it with `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function acceptBuyOfferExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);
  
  // Assume ledger, offerId, nfts, senderBalances, collectionCap, amountToSell, clock, ctx, marketAddress, and coinType are defined.
  tx.moveCall({
    target: `${marketAddress}::MARKET::accept_buy_offer`,
    arguments: [
      tx.object(ledger),
      tx.object(offerId),
      tx.makeMoveVec({ type: "NFT", elements: nfts.map(nft => tx.object(nft)) }),
      tx.makeMoveVec({ type: "UserBalance", elements: senderBalances.map(balance => tx.object(balance)) }),
      tx.object(collectionCap),
      tx.pure.u64(amountToSell.toString()),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "message": "Buy offer accepted successfully; payment transferred.",
  "transactionDigest": "0xbuyofferacceptexample",
  "timestamp": "2023-04-01T16:00:00Z"
}

Batch Accept Sell Offers Method Documentation


batch_accept_offers<CURRENCY>(
  ledger: TradeLedger,
  payment: Coin<CURRENCY>,
  offerIds: ID[],
  fillAmounts: number[],
  collectionCap: CollectionCap,
  clock: Clock,
  ctx: TxContext
): number

Description:
- Processes multiple sell offers in one transaction.
- For each offer, calculates the payment for the partial fill.
- Splits the payment coin appropriately and updates each offer's status.
- Updates ledger indices and emits a BatchOffersAccepted event.
- Returns the total number of NFTs filled in the batch.

Sui Client Methods:
- Creates a Transaction with `new Transaction()` and sets the gas budget.
- Uses `tx.moveCall()` with target: `${marketAddress}::MARKET::batch_accept_offers`.
- Serializes and signs the transaction using `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function batchAcceptOffersExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);
  
  // Assume ledger, payment, offerIds, fillAmounts, collectionCap, clock, ctx, marketAddress, and coinType are defined.
  tx.moveCall({
    target: `${marketAddress}::MARKET::batch_accept_offers`,
    arguments: [
      tx.object(ledger),
      payment,
      offerIds,
      fillAmounts,
      tx.object(collectionCap),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "totalFilled": 3,
  "message": "Batch sell offers processed successfully",
  "transactionDigest": "0xbatchacceptoffersdigest",
  "timestamp": "2023-04-01T17:00:00Z"
}

Batch Accept Buy Offers Method Documentation


batch_accept_buy_offers<CURRENCY>(
  ledger: TradeLedger,
  offerIds: ID[],
  fillAmounts: number[],
  nfts: NFT[],
  senderBalances: UserBalance[],
  collectionCap: CollectionCap,
  clock: Clock,
  ctx: TxContext
): number

Description:
- Processes multiple buy offers in a single transaction.
- For each offer, transfers the specified number of NFTs from the seller.
- Adjusts the locked payment amounts for partial fills.
- Updates each buy offer's status (FILLED or PARTIALLY_FILLED).
- Emits a BatchBuyOffersAccepted event.
- Returns the total number of NFTs sold in the batch.

Sui Client Methods:
- Creates a Transaction and sets the gas budget.
- Uses `tx.moveCall()` with target: `${marketAddress}::MARKET::batch_accept_buy_offers`.
- Serializes the transaction and signs it with `signAndExecuteTransaction`.

import { createRobustClient } from "@/app/utils/createNetworkClient";
import { Transaction } from "@mysten/sui/transactions";
import { signAndExecuteTransaction } from "@mysten/dapp-kit";

async function batchAcceptBuyOffersExample() {
  const client = createRobustClient("testnet");
  const tx = new Transaction();
  tx.setGasBudget(200000000);
  
  // Assume ledger, offerIds, fillAmounts, nfts, senderBalances, collectionCap, clock, ctx, marketAddress, and coinType are defined.
  tx.moveCall({
    target: `${marketAddress}::MARKET::batch_accept_buy_offers`,
    arguments: [
      tx.object(ledger),
      offerIds,
      fillAmounts,
      tx.makeMoveVec({ type: "NFT", elements: nfts.map(nft => tx.object(nft)) }),
      tx.makeMoveVec({ type: "UserBalance", elements: senderBalances.map(balance => tx.object(balance)) }),
      tx.object(collectionCap),
      tx.object(clock)
    ],
    typeArguments: [coinType],
  });
  
  const serializedTx = await tx.serialize();
  const result = await signAndExecuteTransaction({ transaction: serializedTx });
  return result;
}
{
  "success": true,
  "totalFilled": 2,
  "message": "Batch buy offers processed successfully",
  "transactionDigest": "0xbatchacceptbuydigest",
  "timestamp": "2023-04-01T18:00:00Z"
}