The investor journey
1. Find a project
GET /platform/v1/rwa/projects/{code} for the complete terms. Project status can be draft, funding, active, distributing, defaulted, redeemed, or paused.
2. Buy tokens
The request amount is the gross USDT amount. The configuredrwa_subscription fee is charged on top and the token quantity is calculated from the net amount.
3. Trade a title on the internal secondary book
Secondary trading is an internal RFQ between two verified accounts in the same organization. Creating an offer locks the exact title quantity. The lock is released by cancellation or expiry, and an offer can be claimed by only one taker.rwa_secondary_offer_open. The taker accepts with
POST /platform/v1/rwa/secondary/offers/{offerID}/accept and an
idempotency_key. Settlement is atomic: the title moves to the taker, the
agreed USDT proceeds go to the maker, and the configured
rwa_secondary percent-plus-fixed fee is charged to the taker. The ledger
entries are secondary_hold, secondary_release, secondary_fill,
secondary_proceeds and secondary_charge. A closed offer emits
rwa_secondary_offer_closed; a settled offer emits
rwa_secondary_filled.
Do not retry with a new key after a timeout. Reusing the maker or taker key
replays the stored result. Creating an offer with a TTL outside 15–1440
minutes returns 400 invalid_ttl; accepting an already expired offer returns
410 offer_expired. Self-trade returns 400; a second winner returns 409.
4. Reports, default and final redemption
Holders can list and retrieve only approved monthly reports. A report period isYYYY-MM, and approval freezes NAV and yield values. The server checks
gross_sales = units_sold × realized_price and
royalty_due = floor(net_payable × royalty_pct / 100) using exact decimal
arithmetic. The maker proposes; a different named admin approves or rejects.
If a project opts into automatic default, the daily sweep uses cure_days.
Missing (NULL) cure configuration is fail-safe manual. One pre-alert is
emitted before rwa_default_declared with stage=prealert; declaration
uses stage=declared. A platform admin can cure with the project PATCH,
including after the deadline when the transition is valid. Default evidence
is retained for 90 days.
Final redemption is an admin maker-checker distribution with is_final=true.
It requires the attestation to declare the exact cap remainder, including an
exact zero; escrow must cover that amount (>=), and the queue must be clean
with no unresolved offers. The project is paused, open offers are cancelled,
and prior final proposals are superseded. Checker approval pays the remainder,
burns all remaining titles and marks the project redeemed. Post-close burns
are parked for review; they are never silently credited.
5. Monitor holdings and distributions
from, to, and page; retrieve an individual resource with its ID. Every subscription, redemption, and distribution has a PDF receipt endpoint.
6. Redeem
Redemption returns USDT at the project subscription price (par) and atomically debits the RWA token balance.States and errors
Common RWA errors are documented in Errors. In particular,
rwa_window_closed, rwa_cap_exceeded, rwa_fee_exceeds_amount, rwa_redeem_disabled, and rwa_escrow_insufficient are business outcomes, not retryable transport failures. For timeouts or 5xx responses, query the resource using the same idempotency key before taking action.
Webhooks
Subscribe torwa_subscription_completed, rwa_distribution_credited,
rwa_redeem_completed, rwa_secondary_offer_open,
rwa_secondary_offer_closed, and rwa_secondary_filled. Verify the webhook
signature and return a 2xx only after durable processing. Payloads contain the
operation ID, project code, exact decimal amounts, and status. See Webhooks.
FAQ
Is the token price floating?
Is the token price floating?
No. F1 redeems at the project’s subscription price. The published project terms are the source of truth.
Can I retry a failed request?
Can I retry a failed request?
For an ambiguous timeout or 5xx, first retrieve the original resource with the same idempotency key. Never send the financial operation again with a new key unless you intentionally want a new operation.
Why did my distribution differ from my current balance?
Why did my distribution differ from my current balance?
Entitlement uses the balance at the ex-date snapshot. Transfers after that snapshot do not change that period’s share.
Is the blockchain bridge available?
Is the blockchain bridge available?
No. The compiled contract exposes
bridge_enabled, but the bridge flow is F2 and must not be treated as available in F1.