Interacting with Different Types of Contracts

In the evolving landscape of Web3 and decentralized marketplaces, understanding how to interact with various smart contracts is essential for developers building NFT trading platforms, wallet services, or decentralized exchanges. This guide dives deep into the mechanics of interacting with two core contract types: aggregator contracts and self-operated marketplace contracts. Whether you're integrating NFT trading functionality or enabling seamless token swaps, mastering these interactions unlocks powerful capabilities in decentralized ecosystems.

We'll explore the structure, parameters, and execution logic behind each contract type, providing clear technical insights for developers working within wallet-as-a-service (WaaS) environments or leveraging Web3 APIs.

Understanding Aggregator Contracts

Aggregator contracts streamline interactions across multiple decentralized marketplaces by consolidating trade execution logic into a single interface. The primary entry point for these operations is the trade API, which encapsulates calldata from various underlying marketplace contracts.

This abstraction allows developers to execute complex cross-market trades without needing to directly interface with each individual protocol—significantly reducing integration complexity.

MarketRegistry: The Contract Registry

At the heart of the aggregation system lies the MarketRegistry contract. This registry maintains a list of all supported marketplace contracts, ensuring only verified and compatible protocols are used during trade execution.

Key parameters in MarketRegistry include:

• marketId: A custom identifier assigned to each registered market.
• value: The amount of native currency (e.g., ETH on Ethereum, MATIC on Polygon) being sent with the transaction.
• orderHash: A unique cryptographic hash representing the order details.
• tradeData: Calldata generated from external marketplaces, typically derived using the Marketplace API. This data contains encoded function calls and arguments required to fulfill trades on target platforms.

By referencing this registry, the aggregator ensures secure and accurate routing of transactions across supported markets.

AggregatorParamV3: Defining Trade Behavior

To specify how a trade should be executed, developers use the AggregatorParamV3 struct. This configuration object defines critical aspects of the transaction, including asset types, payment details, and user roles.

Relevant fields include:

• actionType: Specifies the operation type. Supported values:

  • 1: _SEAPORT_BUY_ETH
  • 2: _SEAPORT_BUY_ERC20
  • 3: _SEAPORT_ACCEPT
• payAmount: Amount of ERC20 tokens to pay for the asset.
• payToken: Address of the ERC20 token used for payment.
• tokenAddress: Contract address of the NFT (ERC721 or ERC1155).
• tokenId: Identifier of the specific NFT being traded.
• amount: Number of tokens involved (especially relevant for ERC1155).

• tradeType: Defines the token standard:

  • 0: NATIVE (ETH/MATIC)
  • 1: ERC721
  • 2: ERC1155
  • 3: ERC721_WITH_CRITERIA
  • 4: ERC1155_WITH_CRITERIA
  • 5: ERC20
• extraData: Encoded addresses for the order maker, taker, and universal approval delegate.

👉 Discover how to simplify multi-market NFT trades with advanced aggregation tools.

Atomic Execution Control: isAtomic Flag

The isAtomic boolean flag determines error handling behavior during batched order executions:

• When set to true, any failure in one order will revert the entire batch—ensuring all-or-nothing execution.
• When set to false, failed orders are skipped while others proceed, allowing partial success in bulk operations.

This flexibility is crucial when dealing with volatile markets or uncertain order validity.

Working with Self-Operated Marketplace Contracts

Unlike aggregators that interface with third-party markets, self-operated marketplace contracts allow platforms to manage their own NFT listings and trades directly on-chain. These contracts support key functionalities like listing creation, order fulfillment, and cancellation.

1. Creating Fixed-Price Listings

Fixed-price listings enable users to offer NFTs at a set price, waiting for buyers to execute the purchase. When creating such a listing:

• An order is generated off-chain.
• The seller signs the order using their private key.
• The signed order is stored and later used for fulfillment.

This process leverages cryptographic signatures to ensure authenticity and prevent tampering. For implementation details, refer to order creation best practices in WaaS integrations.

2. Fulfilling Orders

Two primary methods are available for executing trades: fulfillBasicOrder and fulfillAdvancedOrder. Each serves different use cases based on complexity and flexibility needs.

2.1 fulfillBasicOrder

This method is optimized for simple, direct trades where terms are straightforward and require minimal validation.

Key parameters include:

• considerationToken, considerationIdentifier, considerationAmount: Define what the buyer receives.
• offerer, zone, offerToken, offerIdentifier, offerAmount: Specify what is being sold and by whom.
• basicOrderType: Indicates the kind of trade (e.g., NFT for ETH).
• Timing controls: startTime, endTime, and zoneHash define validity windows.
• Security features: salt adds randomness; offererConduitKey and fulfillerConduitKey control token transfer conduits.
• Payout management: additionalRecipients lists secondary beneficiaries and their shares.

This interface is ideal for high-throughput scenarios where gas efficiency is paramount.

2.2 fulfillAdvancedOrder

For more complex trading scenarios—such as auctions, bundle sales, or conditional offers—the fulfillAdvancedOrder function provides granular control.

Core components:

• fulfillerConduitKey: Identifies the conduit through which the buyer’s tokens are transferred.
• recipient: Optional recipient address; defaults to msg.sender if not specified.

• CriteriaResolver: Validates Merkle proofs for criterion-based orders (e.g., allowlist mints).

  • orderIndex, side, index: Locate specific items within multi-item orders.
  • identifier, criteriaProof: Prove eligibility for criterion-based NFTs.

The AdvancedOrder struct contains:

• numerator / denominator: Enable partial fills (e.g., fill 1/3 of an order).
• signature: Seller’s cryptographic proof authorizing the trade.

• parameters: Detailed order specs including:

  • offerer, zone, startTime, endTime, salt, conduitKey
  • orderType: Combines traits like open/restricted and full/partial execution rights.
  • totalOriginalConsiderationItems: Ensures consistency when additional recipients are added.

Offer and consideration items follow similar structures:

• token: Asset contract address.
• identifierOrCriteria: Can be a single ID, zero (for fungible), or a Merkle root.
• startAmount / endAmount: Define pricing curves—equal for fixed prices, variable in time-based auctions.

Item types (ItemType) distinguish between:

• NATIVE: Native blockchain currency.
• ERC721_WITH_CRITERIA: Multiple eligible NFTs via Merkle tree.
• ERC1155_WITH_CRITERIA: Batch-minted semi-fungible tokens under criteria.

👉 Learn how to build scalable NFT marketplaces using advanced order fulfillment logic.

3. Canceling Listings (Delisting)

Orders can be canceled either individually or in batches. Only the offerer (seller) or zone (authorized operator) may initiate cancellation.

The OrderComponents data structure mirrors OrderParameters, with the addition of a counter field that tracks trade attempts or prevents replay attacks.

This mechanism ensures secure, revocable commitments—critical for maintaining user trust in dynamic markets.

Frequently Asked Questions

Q: What is the main advantage of using an aggregator contract?
A: Aggregator contracts reduce development overhead by unifying access to multiple marketplaces through a single interface, enabling cross-platform liquidity aggregation with minimal integration effort.

Q: Can I partially fulfill an NFT order?
A: Yes—using the fulfillAdvancedOrder method with a numerator/denominator pair allows partial execution, useful for batched ERC1155 sales or fractional offers.

Q: Who can cancel an active listing?
A: Only the original offerer or designated zone address has permission to cancel or modify an existing order.

Q: How does criteria-based trading work?
A: It uses Merkle trees to define eligibility without revealing full lists. Users provide a Merkle proof via criteriaProof to claim reserved NFTs.

Q: Is it possible to route payments to multiple recipients?
A: Absolutely—via the additionalRecipients array, you can distribute proceeds across several addresses during fulfillment.

Q: What role does conduitKey play in trade execution?
A: The conduitKey points to a pre-approved contract that securely handles token transfers on behalf of users, reducing approval overhead and improving safety.

👉 Start building powerful Web3 trading experiences today—explore comprehensive API documentation.

By mastering interactions with both aggregator and self-operated marketplace contracts, developers gain full control over NFT trading logic, enabling innovative applications in decentralized commerce. From atomic batch trades to dynamic pricing models, these tools form the backbone of modern Web3 market infrastructure.

Core Keywords: aggregator contract, self-operated marketplace, fulfillAdvancedOrder, NFT trading, Web3 API, order fulfillment, smart contract interaction, wallet-as-a-service