RWA Product Overview

This page explains the contract and accounting model behind the RWA API. The API does not replace on-chain rules. It helps you build StockRouter calldata, submit or delegate transactions, and track state across wallet balances, Cashier, Stock, and asynchronous settlement.

If you are debugging a concrete trade, start with trader-questions.md. This page explains the system design; the playbook turns it into request, execution, and reconciliation checks.

Overall Design

The RWA API supports funding, market and limit orders, cash and stock movement between wallet and contracts, and portfolio state queries. It behaves like a trading account at the API layer, but accounting and permissions are enforced by on-chain contracts. The API prepares the right transactions and tracks asynchronous results after those transactions are mined.

The system is built from on-chain contracts plus backend processing. The contracts hold accounting state and enforce the transaction path. Backend processing connects that on-chain state to market execution, final settlement, status updates, and API indexing.

Core on-chain contracts:

Contract

Role

StockRouter

Public entrypoint. It receives transactions, uses ERC-20 allowance as spender when wallet tokens are needed, and calls Cashier or Stock with the original user address.

Cashier

Tracks mUSD. The API surfaces this as mUsdBalance. Deposits increase it; withdrawals deduct it.

Stock

Tracks stock order state and stock tokens credited to users as Stock.stockBalance, surfaced by the API as exchangeBalance. Plain sells spend this balance.

OneClickRouter

Optional delegated execution router. It forwards approved One Click actions to StockRouter while preserving the original user address.

With these contracts, a user can:

User need

What the product supports

Fund account

Convert approved USDC into mUSD.

Buy stock

Use mUSD, or use /orders/with-deposit/* to deposit cash and buy in one transaction.

Sell stock

Sell from exchangeBalance, or use /orders/with-deposit/* to deposit approved wallet stock and sell in one transaction.

Withdraw cash

Convert mUSD back to USDC.

Move stock

Use /stock/deposits/* to deposit wallet stock into Stock, or /stock/withdrawals/* to withdraw exchangeBalance to wallet.

Track portfolio

Read wallet balances, mUsdBalance, exchangeBalance, orders, and cash operation status.

The API prepares StockRouter transactions and indexes the lifecycle after submission. A mined transaction is not always the final business state; orders, cash operations, and portfolio balances can update after backend processing and settlement.

Core Accounting Concepts

mUSD

mUSD is a 1:1 USD-backed accounting unit reflecting real-time purchasing power. It is a digital representation of credit exclusively for MondayTrade RWA trading. mUSD is not a cryptocurrency, stablecoin, or transferable virtual asset. In this API guide, treat mUSD as the accounting balance a user can use to buy RWA stock or request a withdrawal.

Concept

Where it lives

What it means

mUSD

Cashier

Used for buys and withdrawals. The API surfaces this as mUsdBalance.

USDC wallet balance

User wallet

ERC-20 cash token. Must be deposited before it becomes mUSD.

Stock wallet balance

User wallet

ERC-20 stock token held directly by the user. StockRouter can pull it only after user approval.

Stock.stockBalance

Stock contract

Accounting record for ERC-20 stock tokens held by Stock and credited to the user. The API surfaces this as exchangeBalance. Bought stock lands here; plain sells spend from here.

walletAllowance

ERC-20 allowance

Whether StockRouter can pull a wallet token for a deposit or other token-pulling flow.

Stock walletBalance and exchangeBalance are different. walletBalance is the ERC-20 stock token in the user's wallet. exchangeBalance is the API view of Stock.stockBalance, where stock is held by Stock and credited to the user. Plain sells spend exchangeBalance; wallet-held stock must be approved before StockRouter can pull it into Stock for selling.

Deposit and Withdrawal Conversion

Cash movement is not just an on-chain token transfer. Deposited USDC ultimately needs to become USD usable for trading and settlement, and withdrawals need cash to come back before USDC can be paid out. That final cash path can take time.

To reduce API-visible waiting time, Cashier uses pre-funded buffers. When a buffer can safely cover the request, Cashier can apply the result immediately while final cash settlement catches up later.

Deposits convert wallet cash tokens into mUSD. The user first approves StockRouter as the cash token spender, then submits a deposit; StockRouter transfers the token to Cashier. If the deposit is instant, Cashier credits mUSD immediately. If it is queued, mUSD is credited after final cash settlement.

Withdrawals convert mUSD back into wallet cash tokens. The user requests a withdrawal through StockRouter, and Cashier deducts mUSD. If the withdrawal is instant, USDC is sent to the wallet immediately. If it is queued, USDC is sent after final cash settlement.

A mined transaction means the request reached the contracts. For queued operations, the final mUSD credit or USDC payout can happen later. See cash/buffer-mechanism.md for buffer rules.

Buy and Sell Paths

Plain buy: spends existing mUSD.
Order-with-deposit buy: uses approved cash token allowance, requires instant deposit, credits mUSD, then places the buy in one transaction.
Plain sell: spends existing exchangeBalance, the API view of Stock.stockBalance.
Order-with-deposit sell: transfers approved wallet stock into Stock, then places the sell in one transaction.

Buy paths lock mUSD before execution. A plain buy uses existing mUSD; an order-with-deposit buy first transfers approved cash token to Cashier and credits mUSD, but only when instant deposit is available and the buffer can cover the conversion.

Sell paths lock stock before execution. A plain sell uses existing exchangeBalance; an order-with-deposit sell first transfers approved wallet stock into Stock and credits it there.

Market buys specify maximum mUSD to spend; market sells specify stock quantity. Limit orders specify quantity, limit price, and timeInForce; current production contracts accept only DAY. Limit orders can remain open and can be canceled while open. txHash is available as soon as the transaction is broadcast. orderId is created by the on-chain placement transaction and becomes available after the transaction is mined and indexed.

Cash endpoints are only for cash-token flows into or out of Cashier. Use /stock/deposits/* and /stock/withdrawals/* for stock token movement.

Any router flow that pulls wallet tokens requires ERC-20 approve first. Cash deposits require approval for the cash token; stock deposits require approval for the stock token. See cash/deposits.md.

Fees

Fees can appear in both cash operations and order results. Do not hardcode fee assumptions; read the returned fields from operation and order responses.

Area

Common fields

Meaning

Cash operations

amount, creditAmount, feeAmount

Token amount, resulting mUSD, and cash operation fee when present.

Order history

mintFee, protocolFee, settlePay, settleReceive

Trading/mint/protocol fees and final fill amounts when present.

For deposits, the credited mUsdBalance may differ from the token amount if a fee applies. For orders, final received stock or cash depends on traditional-market execution: orders can fill at the executed price, partially fill, or receive no fill. Use settlement fields such as settlePay, settleReceive, mintFee, and protocolFee as the authoritative final amounts, not only the original order input.

Contract stack (integrator view)

State-changing transactions go through StockRouter. When wallet tokens are needed, StockRouter uses the user's ERC-20 allowance as spender and transfers the tokens to Cashier or Stock; it does not custody deposits as the final destination.

Use x-api-p: MondayTrade for MondayTrade RWA trading. The active API docs do not require other product contexts.

Router operations map to API flows

Calldata responses give toAddress, value, and callData for your wallet client. toAddress is the StockRouter address. See guides/demo-code.md.

User action

Router method

Self-submit endpoint

One Click endpoint

Deposit cash

deposit

POST /cash/deposits/calldata then /tx

POST /cash/deposits/send

Withdraw cash

withdraw

POST /cash/withdrawals/calldata then /tx

POST /cash/withdrawals/send

Market buy or plain sell

placeMarketOrder

POST /orders/calldata then /tx

POST /orders/send

Limit buy or plain sell

placeLimitOrder

POST /orders/calldata then /tx

POST /orders/send

Cancel limit

cancelLimitOrder

DELETE /orders/{orderId}/calldata

DELETE /orders/{orderId}/send

Stock deposit and withdrawal are exposed through /stock/deposits/* and /stock/withdrawals/*.

Portfolio API vs on-chain state

Use GET /users/{userId}/balance as the API view of wallet and exchange state.

Field

Meaning

Integration note

mUsdBalance

mUSD tracked by Cashier

Use for buy power and withdrawable credit

walletBalance

ERC-20 tokens in wallet

Custody balance; StockRouter needs allowance before it can pull tokens

exchangeBalance

API name for Stock.stockBalance

Use for plain sell availability

walletAllowance

Token approval to spender / StockRouter

Check before token-pulling flows

Bought stock normally appears as exchangeBalance first because the ERC-20 stock tokens are held by Stock and credited to the user there. A user can withdraw stock from Stock.stockBalance to wallet custody. If wallet-held stock should be sold, the user must approve StockRouter; the selected flow can then deposit the stock into Stock.stockBalance separately or as part of the sell transaction. For API checks, use mUsdBalance for buy power and exchangeBalance for sell power.

Two execution modes (same contracts)

Mode

How it works

Self-submit

API returns calldata; the user wallet signs and broadcasts the StockRouter transaction; the integration records txHash.

One Click

User signs delegation once; /send submits through OneClickRouter to the same StockRouter methods.

One Click is scoped for safety: the delegate wallet is bound to one user wallet, limited to supported RWA router actions, cannot freely transfer user ERC-20 tokens, and can be disabled.

Design principles

Principle

What it means for integrators

Router-only entry

API calldata targets StockRouter; state-changing integrations should not call Cashier or Stock directly.

Lock then settle

Open orders lock mUSD or Stock.stockBalance; final balances update asynchronously.

Off-chain execution

Quotes and fills come from trading services; chain state catches up asynchronously.

Wallet vs exchange

Portfolio shows both wallet and exchange balances; plain sells use exchangeBalance, while wallet-held stock can be pulled into Stock by an approved StockRouter flow.

Cash timing

Deposits/withdrawals can be instant or queued; watch operationStatus.