Webdevelop Docs

Appearance

Service: Secondary Market & Trading Engine ​

The Secondary Market & Trading Engine provides the core infrastructure for post-issuance liquidity, transforming static, tokenized assets (Offers) into tradable, discoverable financial instruments. It addresses the fundamental problems of private asset illiquidity—high friction, siloed investor pools, opaque pricing, counterparty risk, and complex compliance—by providing a compliant, automated trading environment.

This engine orchestrates the entire lifecycle of a trade, from order placement and compliance checks to on-chain settlement.

This engine is built on five key pillars:

  • Continuous Compliance: Enforces the Offers's specific rules (e.g., investor accreditation, jurisdiction, lockups) on every single trade. It integrates with a Regulatory Compliance Engine to ensure no prohibited transfers can occur.

  • Transparent Price Discovery: Provides a central, permissioned venue for all eligible investors to view market depth and place orders, establishing a fair market price through a unified order book.

  • Atomic Settlement (DvP): Leverages smart contracts for "Delivery vs. Payment" (DvP) settlement. This eliminates counterparty risk by ensuring the RWA token and the payment (e.g., stablecoin) are exchanged in a single, indivisible on-chain transaction.

  • Unified Order Book: Aggregates all buy/sell interest for each asset into a high-performance, off-chain order book for rapid matching, ensuring the best execution price.

  • Market Integrity & Auditability: Creates a verifiable, immutable record (Trade) for every completed transaction, providing a transparent history for investors, issuers, and regulators.

  • Unlock Investor Liquidity: Provides a clear, compliant path for primary investors to exit their positions and for new investors to gain access.

  • Attract New Capital: Makes your platform's Offers significantly more attractive to investors, as liquidity is a primary consideration.

  • Frictionless Trading: Automates the entire trade lifecycle, reducing settlement times from days (in TradFi) to seconds.

  • Actionable Market Data: Provides real-time trade and volume data, giving issuers and investors the insights they need.

Core Technical Components & APIs ​

This engine introduces Order and Trade models and interacts heavily with your existing Profile, Offers, and EVM infrastructure.

Primary Models:

  • Order Model(future): The central record for an investor's intent to buy or sell.

  • Trade Model(future): The immutable record of a completed, matched trade.

  • Offer Model: Used to fetch the asset's specific trading rules, compliance requirements, and associated EVM Contract address.

  • Profile Model: Used (via a Regulatory Compliance Engine) to verify an investor's identity, jurisdiction, and accreditation status before a trade.

  • EVM Wallet: Used to check the seller's token balance and the buyer's stablecoin balance.

  • EVM Transfer: This model logs the successful on-chain transfers that result from a settled Trade.

Governing Logic:

  • Order Matching Logic: The core "engine" that scans the Order Book and matches compatible buy/sell orders (e.g., Price-Time Priority). This logic runs off-chain for performance.

  • Pre-Trade Compliance Check: The most critical logic. This function is called before any Order is accepted into the book. It must verify:

    1. Seller: Is not in a lockup period?

    2. Buyer: Is eligible (KYC'd, accredited) for this specific Offer?

    3. Offer-Level: Will this trade violate any Offer rules (e.g., maximum number of investors)?

Primary APIs:

  • trading-api(future): Exposed to the Investor Portal. Used to create, cancel, and view the status of Orders and to fetch Trade history.

  • market-data-api(future): Provides real-time order book depth, last traded price, and volume data to the Investor Portal and Issuer Portal.

  • settlement-api(future): Called by the matching engine (after a match) to orchestrate the on-chain atomic swap.

  • evm-api: To execute the final on-chain DvP settlement transaction.

  • kyc-api/user-api: Used by the engine to query the Regulatory Compliance Engine for the pre-trade checks.

The Process Lifecycle & Key Capabilities ​

The engine manages the entire trade lifecycle through four distinct, automated phases.

Phase 1: Order Placement & Pre-Trade Validation ​

This phase ensures that only valid, compliant orders enter the marketplace.

  • Initiation: An investor, via the Investor Portal, submits a buy or sell Order using the trading-api.

  • Validation: The engine immediately performs two critical checks:

    1. Balance Check: Calls the evm-api to verify the seller's EVM Wallet holds the required quantity of tokens, OR the buyer's EVM Wallet holds the required stablecoin (e.g., price * quantity).

    2. Compliance Check: Calls the compliance-api to run the Pre-Trade Compliance Check logic against both the buyer and seller.

  • Placement: If both checks pass, the Order is created with an OPEN status and placed into the live, off-chain order book for that asset. If either check fails, the trading-api returns a specific error (e.g., "Insufficient Funds," "Buyer Not Eligible").

Phase 2: Order Matching (Off-Chain) ​

This is the high-speed "engine" component that finds trades.

  • Order Book Management: The engine maintains the Order Book for all tradable assets, updating it in real-time as Orders are placed or cancelled.

  • Matching Logic: The Order Matching Logic (Price-Time Priority) continuously scans the book. When a buy Order's price is greater than or equal to a sell Order's price, it finds a match.

  • Trade Creation: Upon a match, the engine "locks" the corresponding Orders (or parts of them, for partial fills) and creates an immutable Trade record with a PENDING_SETTLEMENT status.

Phase 3: Automated Execution & Settlement (On-Chain) ​

This phase orchestrates the on-chain "atomic swap" to finalize the trade.

  • Trigger: A new Trade record is created with PENDING_SETTLEMENT status.

  • Action: The engine immediately calls the internal settlement-api, passing the Trade details .

  • Atomic Swap: The settlement-api constructs and calls the evm-api to execute a single, atomic smart contract transaction. This contract function does the following:

    1. Transfers the RWA tokens from the Seller's EVM Wallet to the Buyer's EVM Wallet.

    2. Simultaneously transfers the stablecoin payment from the Buyer's EVM Wallet to the Seller's EVM Wallet.

    • If either transfer fails (e.g., seller's balance changed), the entire transaction reverts. No funds or assets are lost.

Phase 4: Confirmation & Post-Trade Update ​

This phase cleans up the records after a successful on-chain settlement.

  • Confirmation: The engine listens for the successful SETTLED event from the on-chain transaction.

  • Logging: The Trade record is updated to COMPLETED, and the settlement_tx_hash is stored. The corresponding EVM Transfer records are created.

  • Order Update: The Order records that made up the Trade are updated to FILLED (or PARTIALLY_FILLED if only a portion was matched).

  • Notification: The engine calls the notification-api to alert both the buyer and seller that their trade has been successfully executed.

  • Cap Table Update: An event is sent to the Cap Table to update the official, off-chain list of token holders for the Offer.

Advanced Scenarios & Platform Resilience ​

  • Pre-Trade Compliance Failures: If any pre-trade check fails, the trading-api rejects the Order immediately. This is a critical feature: a non-compliant order never even touches the order book.

  • On-Chain Settlement Failures: If the atomic swap fails on-chain (e.g., out of gas, or the seller moved their tokens), the Trade is marked FAILED. The "locked" Orders are automatically returned to the OPEN state in the order book to be matched again.

  • Order Cancellations: An investor can call the trading-api to cancel any Order that has an OPEN status. The engine ensures a "race condition" is handled where an Order cannot be cancelled at the same moment it is being matched.

  • Administrative Controls: The Issuer Portal has the ability to pause trading for a specific Offer (by instructing the engine to reject all new Orders) or to administratively cancel any Order in the book.