How Masayume uses DreamDEX

DreamDEX supplies the event markets that Masayume uses. The Somnia Markets SDK, installed as @somnia-chain/markets-sdk version 0.28.1, connects our TypeScript application to market discovery, books, prices, balances and trading. Masayume adds the user experience, risk checks, agents, X integration and its own contracts around those markets. The configured network is Somnia Shannon testnet, chain 50312.

This guide is an implementation map for judges and developers. Every call below is present in the reviewed application source. It describes the SDK capabilities we use, not every capability the SDK offers. The dependency is pinned in the market package.

Start with the integration boundary

Download the architecture image (PNG) · Download the vector image (SVG)

The map in three paths:

• Public reads: Masayume web, agents and X → account-free Markets SDK reader → DreamDEX indexer, chain and price data.
• Direct wallet: fresh SDK quote → separate signer and checked submitter → SDK trader → DreamDEX orders and settlement.
• Vault or specialist ticket: fresh market facts → authorized signer → Masayume contracts → DreamDEX orders, redemption or OracleHub resolution, depending on the product. Range and Moonshot use oracle settlement rather than placing a venue order.

Product screens and operator services call our @masayume/markets package. That package owns the SDK imports and adapts SDK data into the types used by the rest of the app.

1. Read: configureMarkets creates one account-free SomniaMarkets runtime per browser tab or server process. Its configuration supplies the chain, indexer, WebSocket, pinned addresses and price feed.
2. Share: marketsProvider exposes the same market-reading interface to the web app, strategy runner and X executor. React hooks and the book coordinator share live subscriptions.
3. Sign: createSubmitterSession creates a separate SDK instance for one signer and role. Its nonce queue serializes sends. The public reader never gains that account's authority.
4. Execute: the common submitter chooses the direct SDK trader or a Masayume contract route, verifies the result and records actual fills.

Follow runtime construction, the shared read interface, signing sessions and order routing. The system map shows the wider app and service boundaries.

Which SDK calls power which features?

The client below is the SDK client returned by our shared runtime. trader belongs to a signing session. File links point to an immutable reviewed commit.

Test-funds onboarding: the tUSDC mint above remains a wallet-signed SDK call. Masayume's separate STT faucet first sends eligible wallets a bounded native-token top-up through viem/RPC, with durable PostgreSQL reservations. That STT transfer is Masayume infrastructure, not a DreamDEX SDK faucet feature. The wallet guide connects the two prompts, and configuration describes its limits and funding key.

Supporting calls include getErc20Metadata for collateral decimals, getErc20Allowance for funding checks, and getLiveStatus/getWatchStatus for subscription health. The SDK also supplies Shannon chain/address defaults, interval helpers, typed errors and React query keys. Our address check detects drift from the pinned deployment manifest. These primitives are inside the same market package; the contract reference lists the upstream and Masayume-owned addresses separately.

Trace one call from the app to DreamDEX

Consider a BTC UP ticket for one active Window:

1. The market adapter discovers the Window and its opening print through SDK reads.
2. Live book subscriptions update the ticket. The SDK's quote helpers translate the requested tUSDC stake into outcome quantity, cost and a protective price.
3. On confirmation, the submitter checks fresh chain state, fees, funding, expiry and a fresh quote. A cached screen value is not sufficient permission to send.
4. A direct wallet route calls trader.placeOrder. A Trading Balance or delegated route calls Masayume's EventVault writer instead; its on-chain venue gateway reaches DreamDEX's market and order-book contracts.
5. The result records the transaction and actual cost/quantity from execution evidence. A submitted transaction, an unfilled order and a filled position have different states.
6. At resolution, the owner or the authorized settlement path redeems the held outcome tokens. A grant's proceeds return to available Trading Balance; settlement does not silently renew its spending budget.

The two execution paths meet the same venue, but the JavaScript SDK does not implement our Solidity permission logic. Follow the vault adapter into VenueGateway for that contract-to-contract connection.

How agents and X reuse the integration

Momentum and AI agents use the same market discovery, price feed, opening prints and executable quotes. readAgentContext combines those SDK-backed reads into a fresh model input, including normalized price units and both sides' costs. The language-model call, decision journal and strategy risk rules belong to Masayume. A model verdict still needs to pass the trade gates.

Both strategy execution and X execution submit through this route:

route: { kind: "vault-grant", grantId }

That is an excerpt of the route shape, not a standalone trading script. A strategy uses a STRATEGY grant; X uses a separate EXECUTOR grant. The X account-to-wallet link identifies whose permission to inspect. It does not itself authorize spending.

Read agent context, subscriber execution, strategy settlement and X execution. The agent architecture and X architecture explain their database and recovery responsibilities.

How the specialist products connect

These are Masayume contracts and rules using DreamDEX infrastructure. They are not additional features supplied by the TypeScript SDK.

Our directly integrated Somnia tools are the Markets SDK, DreamDEX contracts/indexer, RPC/WebSocket and price-feed/OracleHub paths described here. The reviewed application does not make a separate direct Reactor or Somnia Data Streams SDK call. Upstream automation is not presented as an application-owned integration.

Follow the live evidence

The 6–7 September 2026 rehearsal used faucet assets only. These dated records demonstrate specific paths, not a promise of future returns or current service health.

The acceptance ledger preserves failures, the invalid pre-fix Momentum signal, test/deployment revisions and evidence limits. Source links currently require repository access; the public guide, transaction links and demo can be read independently.

Read this with an AI tool

Use llms.txt for the documentation index, this guide as Markdown, or llms-full.txt for all guide text with canonical URLs and source notes. The correct index filename is lowercase llms.txt.

For upstream reference material, see DreamDEX Event Contracts documentation and its llms.txt. The call-site map above is verified against Masayume's installed SDK version and source, independently of changes to upstream documentation.