# Masayume Docs — full text
Documentation origin: https://docs.masayume.app
Application origin: https://masayume.app
Application source revision: 73493cba29aa365125f0da39f91376a612d1add7
Reviewed: 2026-09-07
Each guide includes its canonical URL. Resolve relative documentation links against the docs origin; AppLink components refer to the application origin. Source notes link to the reviewed application code and require repository access.
# Your guide to Masayume.
Make your first call, play a game, or launch an agent. Learn one step at a time.
Canonical URL: https://docs.masayume.app/
Application origin: https://masayume.app
Reviewed: 2026-09-07
## One app. A few ways to explore. [#one-app-a-few-ways-to-explore]
## What would you like to do? [#what-would-you-like-to-do]
## More resources [#more-resources]
You can browse markets and try Practice without connecting a wallet. Trades and funded games use test funds on **Somnia Shannon testnet**. Start with [your wallet and balances](/start/wallet) before placing a call.
* [Find every part of the app](/start/find-your-way).
* [See how Masayume fits together](/architecture/overview).
* [Check what is available and what needs setup](/help/availability).
* [Find a plain explanation of a word](/help/glossary).
---
# Copy and manage a strategy
Fund a limited runner, change its caps, pause it or withdraw.
Canonical URL: https://docs.masayume.app/agents/copy
Application origin: https://masayume.app
Reviewed: 2026-09-07
Copying lets a strategy runner open supported positions using a budget you grant. Your funds remain accounted to your wallet through Trading Balance. The runner can make losing calls, so inspect its limits and real record before copying.
## Review the strategy [#review-the-strategy]
Open Strategies → **Copy a strategy**. Check current health, **Track record**, limits, public playbook and decision memory. The **Published strategies** filters can narrow the list to strategies with settled history or a playbook; a filter or card ranking is not a performance guarantee.
A runner with no recent decisions may be waiting, offline or missing configuration. Read the status instead of interpreting an empty history as a clean winning record.
## Start copying [#start-copying]
1. Open the strategy's copy drawer and read its runner health and current permission state.
2. Enter **Total budget** and **Most per trade**. The individual limit must fit within both your budget and the creator's ceiling.
3. Review the effective per-trade, daily, open-position and entry-price limits. The permission lasts 30 days.
4. Read **Subscription fee**, **Additional wallet deposit** and the wallet total plus network gas. Available Vault funds and released unused permission budget can reduce the extra deposit.
5. Choose **Fund permission and copy**, then complete the wallet prompts.
6. Wait until the current Vault permission and registry subscription both establish that the copy is active. An active permission still needs a signal and fresh risk checks before a trade.
Joining grants/funds the Vault and then subscribes in the registry. These are separate contract actions, with a token approval if needed. Do not stop after the first transaction and assume the subscription is active. The subscription fee is separate from the trading budget and is charged again on a resume or limits change.
The writer rechecks the fee around approval and limits the registry's token allowance to the reviewed fee, including zero. A higher fee cannot silently use an old unlimited allowance; review any changed fee before continuing.
## Manage your desk [#manage-your-desk]
| Control | What happens |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Add budget without changing limits** | Moves available Vault funds into this permission in one transaction, without another subscription fee. Deposit through Portfolio's Trading Balance first if needed. |
| **Update budget and limits** | Replaces the permission and subscribes with the reviewed limits and current fee. |
| **Pause future copies** | Revokes the grant, then unsubscribes. It stops future copied orders. |
| **Withdraw available funds** | Withdraws to the owner. Using this copy's unspent budget first revokes its permission. |
| **Resume with these limits** | Re-establishes permission and subscription, including the current subscription fee. |
Pause does not close open positions. The runner can settle positions from earlier grants after a pause or revocation, with proceeds credited to the owner's available Trading Balance. An unresolved runner transaction can delay settlement while its outcome is checked. Unspent released budget becomes available immediately after confirmed revocation; already-spent positions are separate.
## Recover from a partial setup [#recover-from-a-partial-setup]
Because these actions have multiple steps, a later failure can follow a successful deposit or revocation. Reopen the desk, check the current balance, grant and subscription, and inspect the transaction receipts before repeating the whole flow.
The browser saves progress for the specific wallet and strategy. **Permission saved. Subscription remains.** means the first step completed but copying is not active yet. Choose **Check and finish subscription** to verify the existing grant and continue. The flow checks the saved operation rather than depositing the whole budget again. **Release this permission** provides a way to revoke an interrupted setup. If release confirmation is lost, **Check permission release** verifies the saved historical grant before clearing the setup; it does not silently subscribe or release an unrelated replacement grant.
An uncertain transaction stays **An interrupted step needs checking** until its receipt can be established. Keep the same browser's saved progress and inspect the permission and subscription links. A replacement grant that differs from the saved setup cannot count as its completed first step. A pending setup for another strategy must be finished or released first.
## Follow what it actually did [#follow-what-it-actually-did]
In **Your strategies**, select the strategy to see your permission and its separate **Operation**. **Copying enabled** confirms permission; **Watching**, **Reading a Window**, **Held** and **Awaiting settlement** describe a verified constraint or the latest recognized runner report. At your open-position limit, a position must settle before another can open. Daily spending limits reset at 00:00 UTC.
Paused, expired, replaced and exhausted permissions keep their own labels. Open positions remain visible separately. Missing or stale runner data shows **Unavailable**, while an unknown transaction holds new submissions rather than being resent.
**Filled in last scan** and **Held in last scan** describe the runner's report across all subscribers. Expand its timestamped report and inspect your own receipts in **Recent copy-trades**. The health poll runs once a minute, so a brief AI read can complete between checks.
Read the decision memory and recent copy trades. A model's UP/DOWN call can still be held by the gate; a sent order can still return no fill. Settled outcomes are the evidence for realized results.
See [memory and playbooks](/agents/memory-market) for those distinctions and [balances](/trading/balances) to trace available money.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/strategies/LiveDesk.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/LiveDesk.tsx)
- [web/src/features/strategies/CopyDrawer.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CopyDrawer.tsx)
- [web/src/features/strategies/useDeskWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/useDeskWrites.ts)
- [web/src/features/strategies/format.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/format.ts)
- [web/src/features/strategies/StrategyActivity.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StrategyActivity.tsx)
- [web/src/features/strategies/activity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/activity.ts)
- [web/src/features/strategies/lifecycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/lifecycle.ts)
- [web/src/features/strategies/copy-progress.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy-progress.ts)
- [web/src/features/strategies/copy-setup.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy-setup.ts)
- [web/src/features/strategies/copy-release.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy-release.ts)
- [packages/markets/src/strategies/write.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/write.ts)
---
# Launch an agent
Publish a Momentum or AI strategy and choose who runs it.
Canonical URL: https://docs.masayume.app/agents/launch
Application origin: https://masayume.app
Reviewed: 2026-09-07
Launch from Strategies → **Create**. Use **Copy a strategy** to browse published strategies and **Your strategies** to manage your own. The **Agents** page is a leaderboard.
Publishing records the strategy and its limits. It does not deposit money or authorize trades from your wallet. A follower must set up a funded copy, and a running process must pick up the strategy before it can act.
The builder has four steps and remains visible before wallet connection. Your name and portrait stay consistent through the review and published strategy. Connect at Publish when ready to sign. Existing screenshots elsewhere in these guides retain their original capture dates.
### Identity & approach [#identity--approach]
Enter an **Agent name** and choose **AI Agent** for a model-guided read or **Momentum** for a fixed price rule. Use **Choose another portrait** if you want a different identity before publication.
The strategy can consider all live assets in this deployment's venue. This form does not restrict it to one coin.
### Behavior & limits [#behavior--limits]
For AI Agent, enter a **Persona**, choose a **Posture**, and select allowed **Windows**. Keep the brief clear about the market behavior you want it to read. Persona text is public; do not put API keys, private wallet information or confidential instructions in it.
The posture's displayed confidence, price and loss-breaker rules affect which decisions may pass. Keep at least one supported Window length selected.
For Momentum, choose **Minimum move from the opening price**. The runner compares each Window's opening print with its fresh EMA: a large enough rise can call Up, a large enough fall can call Down, and a smaller move holds. There is no lookback setting in this builder.
Set **Most per trade** and **Most per day**. The daily limit must cover the per-trade limit. These form the strategy's outer spending envelope; followers can choose tighter limits. The published envelope allows at most two open positions per follower.
### Test read [#test-read]
For an AI Agent, choose **Run test read →** to make one real model read of a live Window using the draft. Read the side, explanation and any reason the gate would hold. A readable Hold is a valid test result. Changing the behavior or limits clears that preview result.
A dry read sends no order and stores no decision. It needs a configured model and a readable live Window; those failures are shown separately. A good dry read is not a guarantee of later returns.
The test is optional. **Continue without a test result →** lets you proceed while keeping the missing test visible in the review. Momentum shows **Rule preview · no live market read**: it describes the configured thresholds without calling a model or proving today's market is tradable.
### Publish [#publish]
Choose **Let Masayume run it** if the deployment offers a configured house runner, or **Run your own bot** for your own execution wallet.
For self-hosting, enter the **Runner wallet** that will sign orders. Publishing does not install or start that process. Follow the [self-host guide](/builders/self-host-agent) for its runtime and credentials.
Set the **Subscription fee** and optionally add a **Public playbook**. The registry charges that fee on each subscription, including a resume or limits change. Set it to zero for free subscriptions. Name, brief, playbook and runner address are public.
Review the identity, behavior, hard limits, test result, fee and runner address. Choose **Publish agent →** and confirm the wallet transaction. If the transaction outcome is uncertain, inspect the linked receipt and **Your strategies** before publishing again; the draft remains available.
Publication estimates gas for the exact metadata. If the wallet lacks native testnet gas, the error shows its available amount and the minimum needed for this step. Add gas and retry; the next attempt clears the old error while keeping the draft. A successful publication keeps its receipt and explains the separate funding and copy steps.
## Verify it is doing work [#verify-it-is-doing-work]
Open the strategy record and look for a recent health update and real decision. A strategy ID and a successful registry transaction prove publication. They do not prove that the runner is alive, that a model has answered or that a trade has filled.
Open **Your strategies**, select the published agent and [set up a funded copy](/agents/copy) when you want it to trade for you. Publication, copy permission, model decisions, fills and settlement are separate evidence.
The decision history should distinguish held calls, sent orders, fills and settlement outcomes. If nothing has happened, use [agent troubleshooting](/help/troubleshooting#an-agent-is-published-but-not-trading) before asking followers to increase funding.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/strategies/CreatorStudio.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CreatorStudio.tsx)
- [web/src/features/strategies/StudioForm.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StudioForm.tsx)
- [web/src/features/strategies/StudioAgentFields.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StudioAgentFields.tsx)
- [web/src/features/strategies/studio-draft.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/studio-draft.ts)
- [web/src/features/strategies/StrategiesScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StrategiesScreen.tsx)
- [web/src/features/strategies/identity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/identity.ts)
- [web/src/features/strategies/dry-read-session.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/dry-read-session.ts)
- [web/src/features/strategies/useDryRead.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/useDryRead.ts)
- [packages/markets/src/strategies/write.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/write.ts)
- [services/ops/src/actors/strategy-runner/decide.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/decide.ts)
---
# Read memory and playbooks
Inspect real decisions and understand the current Memory Market boundary.
Canonical URL: https://docs.masayume.app/agents/memory-market
Application origin: https://masayume.app
Reviewed: 2026-09-07
A strategy's memory helps explain what it read, why it called a side, whether the gate allowed an order and what happened afterward. Its playbook is the creator's optional public description.
These are useful evidence to inspect before copying. They are not interchangeable with settled trading returns.
## Read a decision [#read-a-decision]
1. Open Strategies and select the strategy or its memory panel.
2. Check the decision's Window and time.
3. Read the model's side, confidence and reason where an AI decision is available.
4. Check whether the execution gate **held** or **sent** it.
5. Follow the actual fill and later settlement outcome when recorded.
A hold can be an intentional result, such as insufficient confidence or a limit being reached. A sent order means an attempt was submitted; the fill record tells you whether a position was obtained.
## Read a public playbook [#read-a-public-playbook]
Open the playbook from a strategy card or copy drawer. The creator can describe their approach during publication. That text is public plaintext. Treat it as the creator's explanation and compare it with the observed decisions and results.
Publishing a playbook does not make its claims independently verified. The code and contract limits decide what the runner can execute, and the records show what it actually did.
## What Memory Market supports today [#what-memory-market-supports-today]
The interface includes a Memory Market area, but a paid, encrypted market for sealed memories is not implemented. There is no complete buy, decrypt, sell or revenue-collection workflow to follow in this build.
The current usable pieces are public playbooks and actual stored runner decisions when their data service is configured. Do not send funds expecting the disclosure panel to deliver a private memory package.
## Why memory can be empty [#why-memory-can-be-empty]
A newly published strategy may not have been read by a runner yet. A model can be unconfigured. The decision store can be unavailable. A **Dry read** deliberately sends no order and stores no decision, so it does not populate this history.
Read the shown state rather than assuming an empty panel proves inactivity or a successful track record. [Agent architecture](/architecture/agents) explains the distinction between the chain's strategy record, the live runner and its stored decision history.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/strategies/AgentMemory.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/AgentMemory.tsx)
- [web/src/features/strategies/MemoryMarket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/MemoryMarket.tsx)
- [web/src/features/strategies/CopyDrawer.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CopyDrawer.tsx)
- [web/src/features/strategies/StudioForm.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StudioForm.tsx)
---
# Understand agents and strategies
Choose between copying a strategy, publishing one and asking Sensei.
Canonical URL: https://docs.masayume.app/agents/overview
Application origin: https://masayume.app
Reviewed: 2026-09-07
An agent is a runner that reads supported markets and can place buys within the permissions its followers have granted. A strategy describes what it should look for and sets the outer limits on its activity.
You decide whether to copy, how much to fund and when to stop. The runner's buying authority does not give it a path to withdraw your Vault balance to itself. Trades can still lose their stake.
## Pick your next step [#pick-your-next-step]
| I want to… | Go to |
| ------------------------------------------------------- | ----------------------------------------------- |
| Let an existing runner make bounded calls with my funds | [Copy a strategy](/agents/copy) |
| Publish my own Momentum or AI strategy | [Launch an agent](/agents/launch) |
| Operate the process and wallet that runs a strategy | [Self-host an agent](/builders/self-host-agent) |
| Read a runner's actual decisions and public playbook | [Memory and playbooks](/agents/memory-market) |
| Ask for a recommendation before placing my own order | [Sensei](/explore/sensei) |
## Strategies and Agents are different screens [#strategies-and-agents-are-different-screens]
Strategies offers **Create**, **Copy a strategy** and **Your strategies**. Create opens the four-step builder, Copy a strategy lists published strategies, and Your strategies manages the selected permission and operation.
Agents is the **Agent Leaderboard**. It compares runner addresses using entrusted capital and executed copy-trade records. Entrusted funds alone do not prove that a runner is profitable or even currently active.
## Read status before performance [#read-status-before-performance]
A strategy can be published while its runner has never started. An AI runner can be online while its model is unconfigured, or choose to hold after a successful read. A missing history service can make its health unknown.
Look for recent decisions, actual fills and settled results together. **Holding** is different from **offline**, and a model recommendation is different from a submitted or filled trade.
## What the limits control [#what-the-limits-control]
The strategy defines an outer envelope. Each follower's grant can be stricter. Before sending, the runner's fixed checks and the contracts enforce the permitted budget, trade size, daily spend, open Windows, price limits and expiry as applicable.
An AI strategy can choose UP, DOWN or hold from its supported decision format. It does not receive unrestricted wallet signing authority. [Agent architecture](/architecture/agents) shows the flow from market read to decision, checks, order and stored outcome.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/strategies/StrategiesScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StrategiesScreen.tsx)
- [web/src/features/strategies/AgentsScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/AgentsScreen.tsx)
- [web/src/features/strategies/CreatorStudio.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CreatorStudio.tsx)
- [web/src/features/strategies/AgentMemory.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/AgentMemory.tsx)
---
# How agents make a call
A model reads the market; fixed rules and your grant control execution.
Canonical URL: https://docs.masayume.app/architecture/agents
Application origin: https://masayume.app
Reviewed: 2026-09-07
An AI agent reads a Window and answers **Up, Down or Hold** with a confidence figure and a short reason. It cannot sign a transaction or choose an arbitrary amount. Fixed rules check the answer before the runner considers your spending permission.
## What the agent sees [#what-the-agent-sees]
The prompt includes the opening print, current EMA and spot price, up to 12 samples of the price path, and separate executable quotes for both sides. It also includes a short record of recent decisions and settled outcomes.
The oracle opening print uses two decimals; the live price feed declares its own scale, currently eighteen decimals. The strategy adapter normalizes the opening print to that feed scale before comparing prices or formatting the prompt. An unreadable scale holds the read. It leaves the provider's original oracle units intact for settlement and market displays.
For each chosen cadence, the runner aims to read the Window once, starting a quarter of the way through. The decision slot closes before the final no-entry period. It reserves that decision in the database before calling the model. A failed, interrupted or missing model answer becomes Hold; a restart does not request a second answer for the same strategy and Window. Studio's optional Test read is a separate preview.
## What the fixed gate checks [#what-the-fixed-gate-checks]
| Posture | Confidence floor | Side-price ceiling | Loss breaker |
| -------- | ---------------- | ------------------ | ------------------------------- |
| Guarded | 75% | 70 cents | 3 straight losses; 6-hour pause |
| Balanced | 65% | 85 cents | 4 straight losses; 4-hour pause |
| Active | 55% | 95 cents | 5 straight losses; 2-hour pause |
There is also a daily loss line: 25%, 40% or 60% of the strategy envelope's daily spend ceiling respectively. It is based on realized losses and pauses until the next UTC day. The loss-streak cooldown starts at the relevant settlement time, so restarting the process cannot shorten it. Unreadable or stale settlement history holds new entries; it is not treated as zero losses. Confidence is the model's self-report, not a measured guarantee of winning.
## What your grant checks [#what-your-grant-checks]
After the gate permits a side, the runner reads each subscriber's current grant. It skips someone who already holds that Window. Stake is bounded by the per-trade cap, today's spend headroom and remaining budget. The contract enforces the grant again when the order executes.
Positions and their proceeds belong to the subscriber. Pause revokes future spending and releases unused budget. The runner can still settle positions from earlier grants, including after a strategy or subscription is paused. Their proceeds return to the owner's available Trading Balance.
The runner reserves an execution attempt before sending an order. Repeated cycles and restarts reconcile that attempt against exact chain evidence instead of resending it. An unresolved attempt holds all new submissions by that runner, including settlement sends, until its outcome is established. The pause does not transfer funds to the runner.
Settlement attribution comes from each held side's matching owner, market, historical grant and real fill. One owner can have positions from different strategies, so the discovering strategy is not automatically their origin. Missing or conflicting provenance holds automated settlement and new entries; the owner can inspect and settle from Portfolio.
## What memory means here [#what-memory-means-here]
Decision rows retain model identity, prompt hash, reason, gate decision and execution counts. The recent record is matched against chain settlement. This helps the prompt and loss checks use prior outcomes.
It does not retrain the model. The database is required for new runner trades: when execution or risk records cannot be read or saved, the runner holds. A blank page still does not prove inactivity because the page itself can have a read failure. Check health, recorded decisions and transactions separately.
## Other strategies and Sensei [#other-strategies-and-sensei]
Momentum compares the Window's opening print with the fresh EMA. A move beyond the selected positive threshold can call Up; a move beyond its negative can call Down; a smaller move holds. The builder exposes that threshold and does not offer a historical lookback control. Legacy lookback metadata does not alter this live comparison. The current builder offers AI Agent and Momentum; mean-reversion code is not a selectable creation path.
Sensei is a separate chat companion. It reads the snapshot supplied by the app and offers a view. Its snapshot converts oracle cents into whole dollars for both the opening line and chart samples. Its route does not execute trades.
Use [Launch an agent](/agents/launch) for the user flow, or [Host your own agent](/builders/self-host-agent) for the runner setup.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/brain/src/agent-decide.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/brain/src/agent-decide.ts)
- [packages/brain/src/agent-read.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/brain/src/agent-read.ts)
- [packages/core/src/strategies/agent.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/strategies/agent.ts)
- [services/ops/src/actors/strategy-runner/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/index.ts)
- [services/ops/src/actors/strategy-runner/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/execute.ts)
- [services/ops/src/actors/strategy-runner/agent-record.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/agent-record.ts)
- [services/ops/src/actors/strategy-runner/agent.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/agent.ts)
- [services/ops/src/actors/strategy-runner/lifecycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/lifecycle.ts)
- [packages/db/src/strategy-decisions.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-decisions.ts)
- [packages/db/src/strategy-attempts.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-attempts.ts)
- [packages/markets/src/strategies/agent-context.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/agent-context.ts)
- [packages/markets/src/strategies/price-basis.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/price-basis.ts)
- [web/src/features/strategies/activity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/activity.ts)
- [web/src/features/sensei/useSenseiSnapshot.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/useSenseiSnapshot.ts)
- [web/src/features/sensei/units.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/units.ts)
- [contracts/src/strategy/StrategyRegistry.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/strategy/StrategyRegistry.sol)
---
# Where the records live
Chain ownership, server history and browser recovery material.
Canonical URL: https://docs.masayume.app/architecture/data
Application origin: https://masayume.app
Reviewed: 2026-09-07
Masayume uses several kinds of storage because a wallet balance, a chat message and an agent's explanation answer different questions.
## The record for each feature [#the-record-for-each-feature]
| Record | Main location |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Markets, fills, holdings and settlement | DreamDEX contracts and their indexer |
| Trading Balance, grants and owned vault positions | EventVault |
| Range, Parlay, Boost and private slot state | Their named Masayume contracts |
| Duel entry, deck commitment, picks, payouts and credits | GameArena |
| Strategy creator, runner, spec and subscription consent | StrategyRegistry |
| Agent decision reservations, execution attempts, heartbeats and readable history | Postgres, joined with chain facts |
| X links, mention claims, execution journals, receipts, reply delivery, service checks and polling cursor | Postgres |
| Comments, Takes and bettor records | Postgres |
| Duel history, ratings, arcade scores and Lucky draws | Postgres |
| Encrypted committed-deck material | Operator file journal, plus optional Postgres copy |
| Private claim and browser signing convenience | Browser-held recovery/session material |
## The database is optional for browsing [#the-database-is-optional-for-browsing]
Public market reads can work without a database. That does not mean every feature works without one. X relay, social activity, durable agent memory, Lucky draws, scoreboards, duel history and the settler's worklist depend on stored records.
When a store is unavailable, “not connected here” is different from “you have no history.” Pages should preserve that distinction.
The implementation uses the `postgres` driver and SQL schema definitions. On first use, an idempotent schema creation runs under a transaction and advisory lock. There is no separate Drizzle migration command in the current workspace.
## X execution and reply records [#x-execution-and-reply-records]
An X mention is claimed once in `x_receipts` before execution. When replies are enabled, its `x_reply_delivery` entry is created in that same database transaction. The final execution receipt is written later; posting the reply is a separate operation.
The receipt keeps the claimed sender id and handle, with the requested amount separate from optional booked cost, quantity and resolved Window details in `details` JSONB. Sender snapshots are preserved when later execution facts arrive. Older rows can lack booked fields. Their requested budget must not be presented as a measured fill cost.
The delivery record keeps the exact text, optional media id, posting state and acknowledged reply id. Delivery `sent` means X acknowledged a reply, not that a trade filled or a market was won. An ambiguous post is held for inspection rather than automatically posted again.
Acknowledged reply ids also identify the relay's own receipts during mention polling. Those receipts cannot become new commands. Startup suppresses unfinished recursive reply deliveries while preserving sent acknowledgements for audit; acquisition and pre-post checks repeat the same exclusion.
The X transaction journal persists its intent before broadcast and the hash when broadcast returns. Recovery validates the receipt or searches from the saved block using the expected executor nonce, then matches exact EventVault execution facts. An unresolved receipt is not resent, and missing evidence remains unknown. Older incomplete rows can still require investigation.
The runner separately records each strategy decision before a model call and each execution attempt before an order send. These reservations preserve once-per-Window behavior across restarts. Stale or missing risk data blocks new entries. Neither durable database history nor a recovery scan replaces the contract's authority over funds.
## Private-looking is not encrypted [#private-looking-is-not-encrypted]
Market Rooms are access-controlled at the API. A wallet proves its address and eligibility before receiving a room token. The server can read comments; the messages are not end-to-end encrypted.
Strategy Persona and Playbook text are published openly. The Memory Market does not currently provide an encrypted store for purchasable private playbooks.
PrivateDesk avoids putting an owner beside each market slot on-chain, but the server knows both halves while processing it. See [Private mode](/architecture/private) for the exact limit.
## Recovery needs the right record [#recovery-needs-the-right-record]
A chart screenshot is not a receipt. An agent's reason is not a trade confirmation. A database projection is not the authority to move somebody's funds. Keep transaction hashes and claim material when the app provides them, and inspect the matching contract when an action's result is unknown.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/db/src/client.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/client.ts)
- [packages/db/src/migrate.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/migrate.ts)
- [packages/db/src/schema.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/schema.ts)
- [packages/db/src/schema-x.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/schema-x.ts)
- [packages/db/src/schema-x-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/schema-x-delivery.ts)
- [packages/db/src/x.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x.ts)
- [packages/db/src/x-reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-reply-delivery.ts)
- [packages/db/src/schema-strategies.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/schema-strategies.ts)
- [packages/db/src/strategy-decisions.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-decisions.ts)
- [packages/db/src/strategy-attempts.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-attempts.ts)
- [services/ops/src/actors/x-relay/execution-journal.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execution-journal.ts)
- [packages/db/src/x-health.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-health.ts)
- [packages/db/src/schema-games.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/schema-games.ts)
- [contracts/src/vault/VaultTally.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/vault/VaultTally.sol)
- [web/src/features/private/claims-store.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/claims-store.ts)
- [web/src/features/room/gate.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/room/gate.server.ts)
---
# Earn and market making
What your reserve shares represent and why liquidity matters.
Canonical URL: https://docs.masayume.app/architecture/earn
Application origin: https://masayume.app
Reviewed: 2026-09-07
The market-making vault supplies orders for people taking the other side of a Window. Depositors receive shares in that vault. The value of a share changes with the vault's trading results.
## What the maker actually does [#what-the-maker-actually-does]
The operator's maker key places a paired quote: a post-only bid and ask within the contract's price and spread limits. It cannot use the maker entry point to submit arbitrary taker orders.
The contract caps quantity, capital per Window, total deployment and the number of open Windows. The operator watches for price changes, cancels stale quotes and replaces them when appropriate.
When the vault holds both halves of a complete set, they can be merged back into collateral. Once a Window resolves, its remaining inventory can be settled through the venue.
## What a share means [#what-a-share-means]
Share accounting includes idle and deployed capital. Your shares are a claim on the vault's value, not a fixed number of dollars and not a guaranteed rate of return.
Withdrawals draw on idle capital. The contract also refuses withdrawal while expired Windows still need settlement. A displayed position can therefore be valuable without all of it being available for immediate withdrawal.
## The other reserves [#the-other-reserves]
Parlay and Range reserves play a different role: they back specialist tickets. They earn lost stakes and pay winning tickets. LeverageReserve finances boosted positions and takes the risk that a sale will not repay the financing.
| Reserve | Capital is committed to |
| ------------ | ---------------------------------------- |
| Market maker | Resting orders and market inventory |
| Parlay | Maximum payouts for multi-Window tickets |
| Range | Maximum payouts for closing-price bands |
| Leverage | Financed capital in boosted positions |
A contract having a supplier function does not mean every deposit route is presented on every app page. Use the app's actual Earn controls and review the named contract and terms before signing.
Open Earn to inspect the available vault and its current figures.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [contracts/src/maker/MarketMakerVault.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/maker/MarketMakerVault.sol)
- [contracts/src/maker/MakerGateway.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/maker/MakerGateway.sol)
- [services/ops/src/actors/market-maker/decide.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/market-maker/decide.ts)
- [services/ops/src/actors/market-maker/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/market-maker/env.ts)
- [contracts/src/parlay/ParlayReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/parlay/ParlayReserve.sol)
- [contracts/src/range/RangeReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/RangeReserve.sol)
---
# Windows, trades and balances
How a call becomes a filled position, and where its payout goes.
Canonical URL: https://docs.masayume.app/architecture/event-contracts
Application origin: https://masayume.app
Reviewed: 2026-09-07
A Window asks whether an asset's closing price will finish at or above its opening print. Up wins at or above the print; Down wins below it. Your cost comes from orders available in the market.
## From quote to receipt [#from-quote-to-receipt]
1. The app reads a live Window and quotes your chosen side at your stake.
2. Before sending, it rechecks the chain status, time left, current quote and available funds.
3. Your signer submits an immediate-or-cancel order with a protective limit.
4. Available matching orders fill. The remainder is cancelled.
5. The receipt records the quantity and cost that actually filled.
Up and Down quotes are read independently. Do not calculate one as 100 cents minus the other: a live order book may have different available prices on each side.
## A sent transaction is not always a filled call [#a-sent-transaction-is-not-always-a-filled-call]
| State | Meaning |
| -------------- | ------------------------------------------------------------------------------------ |
| Requote | The new price is outside the confirmed limit. Review it before sending. |
| Submitted | A transaction is in progress. |
| Filled | A receipt proves contracts were bought. A partial fill records only what matched. |
| Nothing filled | The transaction landed, but no order matched. |
| Reverted | The contract refused the transaction. |
| Unknown | The app cannot yet tell whether the send landed. Check recovery before repeating it. |
An unknown send is recorded and is not automatically retried. This avoids a second purchase while the first may still be pending.
## Wallet balance and Trading Balance [#wallet-balance-and-trading-balance]
Direct-wallet trading buys positions from your wallet. **Trading Balance** uses Masayume's EventVault. The vault holds the venue tokens and records which person owns each position.
Deposits add to your available balance. A grant moves part of that balance into a budget for one actor. Revoking returns the unused budget. Sale proceeds and settled payouts return to your balance; they do not become the actor's money.
Anyone may trigger settlement of a vault position, but its proceeds are credited to its recorded owner. Withdrawal pays that owner.
## Permission types [#permission-types]
| Grant | Typical signer |
| -------- | --------------------------------- |
| Session | Your browser's convenience key |
| Executor | The X mention executor |
| Strategy | The runner of a strategy you copy |
Each grant has an expiry, budget and caps for a trade, daily spend, open positions and optionally price. Daily spend resets on UTC days. Replacing a grant of the same type revokes the previous one.
These are real contract limits. The ordinary wallet order lane also has a Daily Stop extension point, but its default currently allows orders through. It is not a universal daily-loss protection service.
## How a Parlay differs [#how-a-parlay-differs]
A Parlay combines several Window sides into one ticket. ParlayReserve reads each leg's order book while opening it, calculates the ticket price and reserves the whole maximum payout in advance.
Each leg resolves from its market. All legs must win. A losing leg ends the ticket; a voided leg while the ticket is live refunds the stake. Winning tickets require a claim, which always pays their owner. Read the ticket's actual maximum payout and cost before signing.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/markets/src/submitter/order-lane.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/order-lane.ts)
- [packages/markets/src/submitter/steps/send.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/steps/send.ts)
- [packages/markets/src/submitter/stop-gate.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/stop-gate.ts)
- [contracts/src/vault/EventVault.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/vault/EventVault.sol)
- [contracts/src/parlay/ParlayReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/parlay/ParlayReserve.sol)
- [contracts/src/parlay/ParlayPricing.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/parlay/ParlayPricing.sol)
---
# How the games work
Real market duels, verifiable draws and replayed arcade scores.
Canonical URL: https://docs.masayume.app/architecture/games
Application origin: https://masayume.app
Reviewed: 2026-09-07
The games share Masayume's market data, but they do not all use the same proof or payout system.
| Game type | What is checked |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| Duel | The deck commitment, actual market fills, market payouts and side-pot rules are recorded on-chain. |
| Lucky | Disclosed seeds reproduce the draw; a separately confirmed market ticket supplies any financial result. |
| Line Rider / Candle Hop | A server replays the input trace and verifies the score. Scores are off-chain. |
## A duel from queue to claim [#a-duel-from-queue-to-claim]
1. Two players queue by mode and tier. Matchmaking considers rating and waiting time.
2. The players commit and reveal their seeds. The server builds a deck from eligible live Windows and saves encrypted reveal material before publishing the commitment.
3. The creator opens a match naming the challenger and deposits the side-pot. The challenger joins and matches it.
4. The committed deck is revealed. The contract checks its hash, unique cards, venue and remaining play time.
5. Each player picks a side on each card. Every recorded pick is an actual filled market order.
6. Resolved cards credit market payouts. The greater total of payout minus actual cost wins the side-pot. A tie splits it.
7. Credits are claimed to the recorded player, even when someone else triggers the claim.
A browser agent key can sign picks after entry. Its authority is limited to one seat and match, with a budget based on the deck and tier. A sponsor may fund its transaction fees; the player still supplies the pot and stakes.
## If play is interrupted [#if-play-is-interrupted]
An unjoined match can be cancelled or refunded after its deadline. If the deck is not revealed in time, both pots can be refunded. After the pick deadline, a completed player beats an incomplete opponent by forfeit; two incomplete decks return both side-pots.
Already bought market positions are separate from the side-pot. They remain settleable even when a match is refunded. The current automatic settler skips refunded matches, so those remaining cards may need a manual contract recovery action.
A reconnect requests a fresh match snapshot. Queue state is temporary; committed deck material has an encrypted file journal and optional database copy.
## Lucky does not place a bet by spinning [#lucky-does-not-place-a-bet-by-spinning]
The server commits its seed before the browser contributes one. Together they derive an asset, side and target multiplier. The app then finds an eligible, fillable Window and shows its ticket. You still review and confirm it through the ordinary transaction flow.
The disclosed proof lets you reproduce the draw. It does not guarantee that a suitable market exists or that its future payout will win.
## Arcade and seasons [#arcade-and-seasons]
Line Rider and Candle Hop run seeded, fixed-step engines. The server accepts a score only when replaying the recorded inputs reproduces it. That proves consistency with the engine, not that a human played unaided. Their scores are not on-chain prize evidence.
Season standings and eligibility are stored off-chain. The prize contract holds collateral, but an admin chooses and sends the one-time distribution. The displayed end time is informational; payout is not automatically triggered by the timestamp.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [contracts/src/games/GameArena.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/GameArena.sol)
- [contracts/src/games/ArenaAgents.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/ArenaAgents.sol)
- [contracts/src/games/ArenaMatches.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/ArenaMatches.sol)
- [contracts/src/games/SeasonPrizePool.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/SeasonPrizePool.sol)
- [services/ops/src/actors/matchmaker/seal.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/matchmaker/seal.ts)
- [services/ops/src/actors/duel-settler/decide.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/duel-settler/decide.ts)
- [web/src/features/games/arcade/score.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/score.server.ts)
- [web/src/features/games/lucky/lucky.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/lucky.server.ts)
---
# Boost and knock-outs
How extra buying power is funded, and why a position can close early.
Canonical URL: https://docs.masayume.app/architecture/leverage
Application origin: https://masayume.app
Reviewed: 2026-09-07
Boost uses your stake plus capital from LeverageReserve to buy more contracts on a Window. The reserve charges a premium and is repaid first when the position exits.
## Opening a boosted call [#opening-a-boosted-call]
The contract reads the current book, sizes what the stake and financed capital can buy, and sends an immediate-or-cancel order. It records the actual fill. Unused stake is returned, and your minimum-quantity guard limits how much a moved book can change the purchase.
There are public caps on leverage, financing per position and Window, total exposure and open positions. An empty reserve or insufficient market depth can prevent opening.
## Three ways a position exits [#three-ways-a-position-exits]
| Exit | Who can start it | What happens |
| --------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
| Cash out | Position owner | Sell into current bids, repay the reserve, return the rest to the owner. |
| Knock out | Anyone, when the maintenance condition is met | Sell the position after its book value reaches the maintenance line. |
| Settle | Anyone, after market resolution or void | Redeem the venue contracts, repay the reserve, return any remainder to the owner. |
The maintenance line relates to the financed amount. It is checked against what the book would pay, not just the asset's displayed spot price.
## Why the final result may differ from your expectation [#why-the-final-result-may-differ-from-your-expectation]
A boosted position can knock out **before the Window closes**, even if the asset later recovers. Thin bids may prevent an immediate sale. A partial sale leaves a smaller position open with the remaining financing claim.
The owner's loss is bounded by the stake charged to that position. This does not make the stake safe: it can all be lost. The reserve absorbs financed capital it cannot recover on a completed exit.
## What the keeper does [#what-the-keeper-does]
The leverage keeper watches open positions. It checks the market's settled status and current maintenance mark, then calls the contract functions already available to everyone. It provides prompt action; it does not decide a price or choose a payout recipient.
If the keeper is unavailable, those contract actions remain possible, but automatic timing is no longer assured. A healthy app page alone does not prove the keeper is running.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [contracts/src/leverage/LeverageReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/leverage/LeverageReserve.sol)
- [contracts/src/leverage/LeverageGateway.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/leverage/LeverageGateway.sol)
- [contracts/src/leverage/LeverageMath.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/leverage/LeverageMath.sol)
- [services/ops/src/actors/leverage-keeper/decide.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/leverage-keeper/decide.ts)
---
# How Masayume fits together
The app, the markets and the services behind each action.
Canonical URL: https://docs.masayume.app/architecture/overview
Application origin: https://masayume.app
Reviewed: 2026-09-07
Masayume brings several ways to use the same price markets into one app. A normal call, a copied trade and a duel pick all depend on a real market Window. Each feature adds its own rules around that market.
## The four parts [#the-four-parts]
| Part | What it does for you |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| The app | Shows prices, explains tickets, connects your wallet and displays your receipts. |
| DreamDEX on Somnia | Supplies the market contracts, live orders, fills and settlement. |
| Masayume contracts | Hold trading balances, enforce spending permissions and manage specialist tickets, reserve shares and duels. |
| Masayume services | Find opponents, run strategies, read X mentions, provide AI answers and keep useful history. |
The checked-in app configuration points to **Somnia Shannon testnet, chain 50312**. Test collateral and STT for transaction fees have different jobs. A displayed test balance is not a claim about real-money value.
## Reading is separate from signing [#reading-is-separate-from-signing]
The market reader has no account or signing key. It reads the indexer, price feed and chain. Every signer gets a separate session, bound to one account and one role.
Your wallet signs ordinary transactions. A browser key can sign under permission you granted. A strategy runner or X executor acts under its own bounded grant. Sharing a market data connection does not make those signers share a wallet.
## What decides the result? [#what-decides-the-result]
The browser does not declare a winning trade. Market contracts and oracle answers determine settlement; receipts record actual fills. Masayume's contracts apply the rules for their ticket type.
Server responsibilities vary. Private mode relies on a desk to connect a claim back to its owner. Season prizes use an admin-controlled payout. Arcade scores are checked by replay on a server. These distinctions are explained on the relevant pages.
## Choose a deeper view [#choose-a-deeper-view]
* [DreamDEX SDK: features, exact calls and source code](/builders/dreamdex-sdk)
* [Ordinary calls, balances and Parlays](/architecture/event-contracts)
* [Range pricing and settlement](/architecture/range)
* [Boost and knock-outs](/architecture/leverage)
* [Earn and market making](/architecture/earn)
* [Private mode and its trust boundary](/architecture/private)
* [AI agents and spending controls](/architecture/agents)
* [Games and their different proofs](/architecture/games)
* [X identity and execution](/architecture/x)
For the current deployment, use Status. A contract address in the source is a deployment record; it does not establish that every connected service is running today.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/markets/src/runtime/read-runtime.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/runtime/read-runtime.ts)
- [packages/markets/src/sessions/submitter-session.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/sessions/submitter-session.ts)
- [services/ops/src/main.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/main.ts)
- [packages/db/src/client.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/client.ts)
- [packages/markets/src/addresses.masayume.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/addresses.masayume.json)
---
# What private mode protects
Separate transaction records, a local claim ticket and an explicit desk dependency.
Canonical URL: https://docs.masayume.app/architecture/private
Application origin: https://masayume.app
Reviewed: 2026-09-07
Private mode separates the record naming your wallet from the record naming your market ticket. It does not make your activity anonymous. The desk sees the connection, and observers may match transaction amounts and timing.
## Your private balance [#your-private-balance]
PrivateDesk is a separate contract with its own balance and spending allowance. You deposit, set how much the desk may spend, and withdraw your unused balance yourself. Revoking the allowance prevents new private spending.
This balance is separate from your wallet, Trading Balance and any open ticket.
## One private bet uses three transactions [#one-private-bet-uses-three-transactions]
1. **Charge.** The desk moves the approved stake from your balance into a pool. This record names your wallet.
2. **Fund.** The desk moves that amount into a fresh slot. This record names the slot.
3. **Buy.** The desk buys the market side in the slot. The slot stores the position without a wallet owner field.
The browser first signs the exact instruction. The service derives opaque identifiers from the signature, checks funds and quote, then performs the steps. Those identifiers let it inspect chain state if a reply is lost, rather than charging the same instruction again blindly.
## Keep the claim ticket [#keep-the-claim-ticket]
The desk returns a signed claim linking the slot to its owner. The return path uses that claim: settle the market position, sweep the slot back to the pool, then credit the recorded owner's private balance.
The contract may allow anyone to trigger the market settlement, but reconnecting pooled funds to an owner still requires the desk. Treat the claim as recovery material and use the app's claim controls before clearing browser storage.
## What you still trust [#what-you-still-trust]
The desk key is held on the server. It can perform pool and slot operations. The contract's own design acknowledges that a compromised desk can credit pooled funds to an address it chooses. The owner's allowance limits what can be charged from their balance; it does not eliminate the desk's trust role.
Once funds are credited to your private balance, only your wallet withdraws them. Do not extend that owner-only withdrawal rule into a claim that every intermediate private operation is trustless.
If the chain is slow, the app may show an unknown result. Reuse the existing recovery instruction or claim. Creating a new instruction is a different request, and should not be used to guess whether the previous one succeeded.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [contracts/src/private/PrivateDesk.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/private/PrivateDesk.sol)
- [packages/markets/src/private/keys.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/private/keys.ts)
- [packages/markets/src/private/desk-open.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/private/desk-open.ts)
- [packages/markets/src/private/desk-cashout.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/private/desk-cashout.ts)
- [web/src/features/private/desk.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/desk.server.ts)
---
# How Range is priced
A band on the closing price, backed by a funded reserve.
Canonical URL: https://docs.masayume.app/architecture/range
Application origin: https://masayume.app
Reviewed: 2026-09-07
Range lets you choose a lower and upper price, then call **Inside** or **Outside** at the Window's close. It concerns the final closing print. The price can cross either boundary during the Window without deciding the result.
## The three pricing inputs [#the-three-pricing-inputs]
| Input | Where it comes from |
| ------------------- | --------------------------------------------------------------------- |
| Opening print | The existing OracleHub answer for the start of the Window |
| Current market view | Available depth on the Window's Up and Down order books |
| Expected movement | A public volatility parameter for that asset, combined with time left |
RangeReserve uses those inputs to price the chosen band, applies its margin and calculates the stake for the requested maximum payout. The house's volatility is a parameter, not a promise about future prices.
The contract checks the asset against the Window's actual OracleHub question. It does not trust an arbitrary asset label supplied by the browser. It reuses existing oracle questions; Masayume does not schedule a new oracle job for each Range ticket.
## What is backed before you sign? [#what-is-backed-before-you-sign]
The reserve locks the house-funded part of the maximum payout when your stake enters. Your stake plus that locked amount cover the ticket's payout.
A quote can be refused because the book is too thin or wide, too little time remains, the requested odds are outside allowed bounds, or the reserve has reached its liquidity or exposure limit. That refusal is preferable to showing a ticket the contract cannot fund.
## What decides Inside or Outside? [#what-decides-inside-or-outside]
After the oracle answers the Window's closing question:
* A closing print between the boundaries, including both boundaries, wins Inside.
* A closing print below the lower boundary or above the upper boundary wins Outside.
* A voided oracle answer refunds the stake.
* An unanswered question can be voided after the contract's configured stale delay.
Anyone can trigger settlement or claim, but a winning claim pays the ticket owner. A pending oracle answer is not a losing result.
## Reserve suppliers [#reserve-suppliers]
Suppliers own shares in the reserve. Losing stakes increase reserve capital; winning tickets consume it. Capital already locked behind tickets cannot be withdrawn as idle liquidity. This is exposure to ticket outcomes, not fixed-interest savings.
Moonshot also uses the Range machinery to present a target-oriented band. Its displayed multiplier still depends on an admissible, funded quote; the interface does not create a separate guaranteed payout rail.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [contracts/src/range/RangeReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/RangeReserve.sol)
- [contracts/src/range/RangePricing.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/RangePricing.sol)
- [contracts/src/range/RangeMath.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/RangeMath.sol)
- [contracts/src/range/WindowQuestion.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/WindowQuestion.sol)
- [packages/core/src/range/moonshot.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/range/moonshot.ts)
---
# Live updates and recovery
How market books and game rooms stay current without confusing a display with a receipt.
Canonical URL: https://docs.masayume.app/architecture/realtime
Application origin: https://masayume.app
Reviewed: 2026-09-07
Market updates and game-room messages use different paths. Both help the screen stay current. Neither turns an unconfirmed action into a confirmed fill.
## Market books [#market-books]
The shared market reader connects to Somnia Markets SDK, the DreamDEX indexer, the configured price feed and chain WebSocket. One coordinator holds a watch per market and shares a normalized book with every visible component that needs it.
It distinguishes a book still loading, a live book and a stale reading. An empty book is not used as a substitute for a read that has not arrived.
The coordinator keys by market id. A pool can be reused for another Window; a stale page must not accidentally display its successor's liquidity. Consumers share depth 10 and render the portion they need.
Endpoint rotation exists as a capability, but automatic runtime rotation is disabled in the current source. A second configured endpoint is not evidence of automatic failover.
## Game rooms [#game-rooms]
The long-running ops service hosts the WebSocket room. A browser first obtains a signed room token from the app. Web and ops share the same `ROOM_TOKEN_SECRET`, so the room can check the token without asking the app again.
The socket performs a protocol-version handshake, checks the match seat and, once registered, the browser key named by the arena. Before on-chain entry, the wallet association is the browser key's claim. Do not treat the room token alone as proof that the wallet owner signed in.
Chat, reactions, presence and “pick pending” are room messages. A pending pick does not contain the chosen side. Confirmed picks and results come from the arena's event projection and chain snapshots.
## Reconnecting [#reconnecting]
A reconnect asks the contract for current match state rather than replaying the browser's old assumptions. The database projection helps locate active matches; the server also tracks committed matches waiting for creation.
The ordinary queue is temporary. If the process restarts while you are only queued, search again. A committed deck has encrypted recovery material in a local journal before it is published.
## A useful separation [#a-useful-separation]
| You see | It tells you |
| ---------------------- | ------------------------------------------- |
| New price or live book | A recent market reading arrived. |
| Opponent presence | Their room connection is present. |
| Pick pending | They are attempting an action. |
| Fill receipt | The chain recorded the trade. |
| Settled card or claim | Contract settlement or payout was recorded. |
The app directly integrates the Markets SDK and these transports. No separate direct Reactor or Somnia Data Streams SDK call is present in the audited application source.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/markets/src/runtime/read-runtime.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/runtime/read-runtime.ts)
- [packages/markets/src/runtime/coordinator.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/runtime/coordinator.ts)
- [packages/markets/src/provider/boot.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/boot.ts)
- [services/ops/src/actors/game-room/handlers.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/game-room/handlers.ts)
- [services/ops/src/actors/duel-projector/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/duel-projector/index.ts)
- [web/src/features/games/room-token.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/room-token.server.ts)
---
# From an X mention to a trade
Prove your account, grant a spending limit, then inspect the receipt.
Canonical URL: https://docs.masayume.app/architecture/x
Application origin: https://masayume.app
Reviewed: 2026-09-07
Trade from X connects a supported mention to a bounded instruction for your Trading Balance. Signing into X identifies you. A separate wallet grant authorizes spending. You need both.
## The two permissions [#the-two-permissions]
**Link your account.** The site signs you in through X's OAuth 1.0a flow. It retains your account id and handle in a signed session, then asks your wallet to sign the link. Your X sign-in alone cannot connect someone else's wallet.
**Authorize the executor.** Your wallet grants the configured X executor a budget, expiry and caps in EventVault. That executor can act only within the contract permission. Payouts stay with your wallet's vault account.
The login flow does not retain your X access token to post as you. Public relay replies use the operator account's separately configured session.
## One supported instruction [#one-supported-instruction]
```text
@handle btc up 5 15m
```
Replace `@handle` with the account shown in the app. The parser expects one asset, one side, one positive stake and one Window length.
| Field | Accepted primary values |
| ------ | --------------------------------------- |
| Asset | `btc`, `eth` |
| Side | `up`, `down` |
| Stake | A positive amount, such as `5` or `$10` |
| Window | `1m`, `5m`, `15m`, `1h`, `4h` |
Common word aliases exist, but duplicate or conflicting fields are refused. Numeric extras such as `3x` do not create leverage. The executor chooses the soonest still-enterable Window matching the requested asset and length.
## How the relay handles it [#how-the-relay-handles-it]
The current relay reads mentions through `rettiwt-api`, using the operator account's session. It checks the linked author, parses the instruction, reads the current grant, gets a fresh quote and uses the shared vault transaction lane.
Each new mention id is claimed once in Postgres before execution. When posting is enabled, the future reply is queued in the same database transaction. An already-claimed mention is not executed again. The first-ever poll establishes a starting cursor and leaves older posts alone.
Later polls drain the mention pages after that cursor, remove duplicate ids and process them oldest first. A later-page failure or repeated page cursor keeps the saved cursor unchanged. Each processed mention's receipt is stored before the polling cursor moves past it.
The transport first resolves the authenticated account's stable id and checks its handle against configuration. The relay excludes that account's own replies and any saved delivery reply id before claiming a command. Other users' reply commands remain eligible; an authorized top-level command from the bot account remains eligible too. This prevents a receipt mentioning its sender from becoming another instruction.
## A reply describes the receipt [#a-reply-describes-the-receipt]
Execution and reply delivery run in separate loops. The reply loop reads completed receipts; it has no signer or trade submitter. It formats validated receipt facts into short text and, when enabled, a branded image. If image preparation or upload fails, it can send the same facts as text.
Requested stake and actual booked cost are different fields. **Order filled** describes a booked position, not a winning market result. **Status needs checking** preserves uncertainty, including a failure to read or store the result after a transaction was sent. The reply links to the transaction when a valid hash is available, or to the app otherwise.
The image is rendered separately for each receipt. It uses the sender handle saved when the mention was claimed, falling back to its saved numeric X account id. A later handle change does not relabel the old receipt. Status, side, Window, requested amount, measured spend and full validated transaction hash come from that receipt. The text keeps a full clickable explorer URL; the printed hash in a picture is not a substitute for that link.
Before making the X post, delivery saves the exact text and optional media id. An acknowledged reply id marks delivery as sent. A timeout or a failure to save that acknowledgement leaves delivery uncertain; it does not trigger an automatic repost or a second trade. Operators must inspect the original mention before considering a manual recovery.
Startup also suppresses pending or uncertain recursive reply deliveries. Database acquisition and the final pre-post check exclude known receipt ids again. Existing sent acknowledgements remain available for audit. Deployment and live checks remain distinct from source review. The release rehearsal on 7 September verified suppression before posting resumed, then observed one intentional refusal with no transaction or recursive reply. That dated test does not replace the current service checks.
`X_POSTING_ENABLED` controls replies independently of trade execution. `X_REPLY_IMAGES_ENABLED` controls the optional image. Existing historical receipts are not backfilled into the reply queue, and enabling replies does not replay instructions processed while posting was off. A missing reply does not establish that no trade happened; check the receipt page.
## Recovery after an interrupted execution [#recovery-after-an-interrupted-execution]
Before submitting an order, the relay persists the linked wallet, market, side, grant, executor, token decimals, chain block and expected executor nonce. Its transaction journal stores the intent before broadcast and the hash as soon as broadcast returns. A failed durable checkpoint stops submission.
Recovery reads chain evidence without signing or replaying the instruction. A known hash must match the executor, EventVault and exact execution event. If the hash was lost during broadcast, recovery searches bounded block pages and checks the recorded nonce and execution facts. Missing or conflicting evidence keeps the receipt uncertain. A submitted or uncertain broadcast with no hash holds later submissions by that X executor so another order cannot reuse its reserved nonce.
Older receipts without enough recovery context still need inspection. A bounded scan that finds nothing is not proof that no transaction happened. Recovery can establish an execution result independently of X reply delivery; it never automatically repeats an ambiguous public post.
## Read the separate service checks [#read-the-separate-service-checks]
The page reports **Mentions**, **Orders** and **Replies** separately. A successful mention poll does not prove an order filled or an image reached X. Old checks become **Status out of date**, and missing checks remain **Not verified**. The image acknowledgement time is shown only after X returned a reply id for a post containing media.
Known bot receipt replies stay in the audit store but are excluded from wallet instruction lists. Intentionally suppressed recursive deliveries do not count as actionable delivery failures; unrelated failed or uncertain deliveries still require inspection.
## Current operational limits [#current-operational-limits]
Mention catch-up is bounded to 50 pages of 20 per poll. A backlog exceeding that bound leaves the cursor unchanged and needs operator attention. Recovery scans are also bounded; unresolved evidence stays visible rather than being treated as a failed trade.
The current transport is still `rettiwt-api` 7.1.3 with the operator account session; this update does not migrate it to the official X API. Its media interface has no alt-text parameter, so all essential receipt facts stay in the adjacent reply text. These implementation limits are separate from the account link and wallet grant.
Unlinking removes the account route. Revoking the Executor grant is the on-chain way to stop its spending authority. Neither action withdraws your funds automatically.
Follow [Trade from X](/explore/trade-from-x) for the screen-by-screen setup.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/x/oauth.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/oauth.server.ts)
- [web/src/features/x/session.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/session.server.ts)
- [web/src/features/x/gate.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/gate.server.ts)
- [web/src/app/api/x/bind/route.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/api/x/bind/route.ts)
- [services/ops/src/actors/x-relay/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/index.ts)
- [services/ops/src/actors/x-relay/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execute.ts)
- [services/ops/src/actors/x-relay/rettiwt.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/rettiwt.ts)
- [services/ops/src/actors/x-relay/reply-format.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-format.ts)
- [services/ops/src/actors/x-relay/reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-delivery.ts)
- [services/ops/src/actors/x-relay/reply-card.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-card.ts)
- [packages/db/src/x-reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-reply-delivery.ts)
- [packages/core/src/x/parse.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/x/parse.ts)
- [services/ops/src/actors/x-relay/poll-cycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/poll-cycle.ts)
- [services/ops/src/actors/x-relay/transport.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/transport.ts)
- [services/ops/src/actors/x-relay/execution-journal.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execution-journal.ts)
- [services/ops/src/actors/x-relay/execution-recovery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execution-recovery.ts)
- [packages/markets/src/vault/recovery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/vault/recovery.ts)
- [packages/db/src/x.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x.ts)
- [packages/db/src/x-health.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-health.ts)
- [web/src/features/x/XRelayStatus.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XRelayStatus.tsx)
---
# App API reference
Every HTTP route in the audited app, grouped by purpose and authority.
Canonical URL: https://docs.masayume.app/builders/api
Application origin: https://masayume.app
Reviewed: 2026-09-07
These are the app's current HTTP routes, not a separately versioned public trading API. Call them on the **application origin**, not this documentation site. Most wallet trades and contract actions are submitted directly through the market package rather than an HTTP trade endpoint.
## Reading responses correctly [#reading-responses-correctly]
Amounts in base units travel as decimal strings. Preserve them as integers; do not turn them into floating-point currency values before applying the collateral's decimals. Timestamp fields ending `Ms` use milliseconds; `Sec` fields use seconds.
Many routes return `configured: false` when a dependency is absent. That is not an empty account. A quote or submitted receipt is not a confirmed fill. Check HTTP status and the route's result field rather than assuming any JSON response means success.
The inventory below covers all 39 route files, including the onboarding faucet added on 7 September 2026.
## Market information [#market-information]
| Method and path | Request | Result |
| ---------------------- | ------- | ----------------------------------------------------------------------- |
| `GET /api/status` | None | Fresh RPC/indexer/feed/store status, lag and model-configuration check. |
| `GET /api/leaderboard` | None | Venue-wide rankings derived from the fill/settlement record. |
| `GET /api/traction` | None | Usage measures derived from the venue scan. |
| `GET /api/news` | None | Up to eight recent RSS headlines from configured feeds. |
News sentiment tags are keyword heuristics, not model analysis or trading signals. Status's model row checks configuration; it does not establish that a billed model request would succeed.
## Sensei and strategies [#sensei-and-strategies]
| Method and path | Request | Result or authority |
| ------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `POST /api/sensei` | `messages`, nullable `snapshot`, `restless` | AI reply; no trade is placed. Requires server model credential. |
| `GET /api/strategies` | None | Registry catalogue joined with readable fills, heartbeats and decisions. |
| `GET /api/strategies/health` | Optional comma-separated `ids` query | Per-strategy heartbeat-derived state. |
| `POST /api/strategies/preview` | `persona`, `posture`, `cadences`, `stakeBase` | One real model read and gate result. Rate-limited; no trade or stored decision. |
| `POST /api/strategies/playbook` | `strategyId`, `creator`, `issuedAtMs`, `body`, `signature` | Saves plain-text playbook after creator signature and on-chain creator check. |
Sensei accepts up to 12 user/assistant messages, each up to 4,000 characters. Its snapshot has `priceUsd` and up to eight market entries with asset, cadence, time left, opening line and separate side quotes. It is caller-supplied context, not a server claim of independent price verification.
Agent preview Persona is capped at 600 characters. Posture is `guarded`, `balanced` or `active`; supported cadences are 300, 900, 3,600, 14,400 and 86,400 seconds. Its response separates `verdict` from `gate`, includes model/prompt hash, and may show that the preview ran outside the normal decision slot.
Strategy publication, grant creation and subscription are contract transactions. They are not hidden effects of these read APIs.
## Market Rooms and Takes [#market-rooms-and-takes]
| Method and path | Request | Result or authority |
| ---------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `GET /api/room/status` | None | Whether the social store is configured. |
| `POST /api/room/join` | `marketId`, `address`, `issuedAtMs`, `signature` | Wallet signature and bettor/position eligibility check; returns room token. |
| `GET /api/room` | `marketId`, `token` query | Up to 100 comments; requires matching live room token. |
| `POST /api/room` | `marketId`, `token`, `body` | Posts comment as token's author; body up to 280 characters. |
| `GET /api/room/bet` | `marketId`, `address` query | Whether the bettor registry has a record for that wallet/Window. |
| `POST /api/room/bet` | `marketId`, `address`, `txHash`, `route` | Checks successful receipt and wallet participation, then records the bettor. |
| `GET /api/takes` | Optional `limit` query | Public feed; default 30, maximum 100. |
| `POST /api/takes` | `marketId`, `side`, `caption`, `address`, `issuedAtMs`, `signature` | Signed public Take, with market facts and a server-derived eligibility badge. |
Room join signatures and Take signatures expire after five minutes. A room token lasts one hour. Market Rooms use API access control; the server can read the comments.
The bettor route accepts `wallet`, `vault`, `leverage` or `private`. Its receipt participation check is not a general-purpose proof that an arbitrary transaction established every supplied market fact. Use the application's intended receipt-reporting flow.
Normalize a Take caption before signing with the shared helper; it must match the submitted bytes and is capped at 240 characters. A Take is a public social record in the database, not itself an on-chain trade.
## X account routes [#x-account-routes]
| Method and path | Request | Result or authority |
| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
| `GET /api/x/start` | Optional relative `return` query | Starts OAuth 1.0a and redirects to X. |
| `GET /api/x/callback` | X supplies `oauth_token`, `oauth_verifier` | Verifies browser flow, obtains identity and sets signed session cookie. |
| `GET /api/x/status` | Optional `wallet` query | Sign-in identity, durable binding, configuration and executor address. |
| `POST /api/x/bind` | `wallet`, `issuedAtMs`, `signature` | Links signed-in X author to proven wallet. |
| `POST /api/x/unlink` | Same signed-wallet fields | Removes matching binding and clears session cookie. |
| `GET /api/x/receipts` | Required `wallet` query | Public wallet mention receipts, newest first, limit 30. |
The account id used by bind/unlink comes from the signed server cookie, never the body. A wallet already bound to an account must be unlinked by its bound wallet before that account can move elsewhere. Use the shared link-message builders; do not handwrite a similar-looking signature string.
The separate ops relay processes mentions. There is no HTTP endpoint here that replaces the required on-chain Executor grant.
## Test funds [#test-funds]
| Method and path | Request | Result or authority |
| ---------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/faucet` | Optional `wallet` address query | Public funding address, readiness, fresh balances, remaining rolling allocation and latest wallet claim. Does not broadcast a transfer. |
| `POST /api/faucet/challenge` | `{ wallet }` | Returns `{ id, message, expiresAtMs }` for a five-minute, origin/network/wallet-bound ownership signature. |
| `POST /api/faucet` | `{ id, signature }` | Verifies the stored message, enforces eligibility and durably reserves an STT transfer before broadcasting. Returns `{ claim }`. |
A claim exposes `id`, `amountWei`, `txHash`, `status` and `nextClaimAtMs`. Status is `prepared`, `confirmed`, `reverted` or `conflict`. Prepared means reserved/possibly submitted, not paid with certainty. Amounts are 18-decimal STT base-unit strings. The API never includes the funding key, raw signed transaction or connection identifier.
Retry a saved request with its original id and signature to reconcile the same transfer, even after the challenge expires. A new request must still be within five minutes and from the connection that obtained the challenge. Wallet ownership alone does not bypass cooldown, balance, global allocation or shared-connection caps. See [configuration](/builders/configuration#testnet-onboarding-faucet-on-web).
Invalid input uses HTTP 400, invalid ownership/origin 403, eligibility or pending-transfer holds 409, request/cooldown/allocation limits 429 and unavailable dependencies/refill 503. Read both status and `code`/`error`; an HTTP timeout may follow a persisted transfer. These routes do not mint tUSDC: the wallet signs that separate SDK transaction.
## Sponsorship [#sponsorship]
| Method and path | Request | Result or authority |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `GET /api/sponsor` | None | Sponsor address, balance, forwarder and function allowlist. |
| `POST /api/sponsor` | `{ request }` signed forward request | Policy checks and verified forwarding of an allowed EventVault call. |
| `GET /api/games/sponsor` | None | Duel gas sponsor configuration, balance and readiness. |
| `POST /api/games/sponsor` | `matchId`, `player`, `agent` | Tops up the arena-approved seat key after chain checks. |
Both write routes use the `x-masayume-device` header for rate gating. It is a rate-limit identifier, not proof of wallet ownership.
A forward request contains `from`, `to`, `value`, `gas`, `deadlineSec`, `data` and `signature`. The sponsor checks EventVault target, allowlisted function, zero native value, gas ceiling and deadline, then asks the forwarder to verify the signature. Capital intake is excluded.
Duel sponsorship sends STT to a named live seat key; it does not forward the player's pick through ERC2771. Funded-seat and request counters are process-local.
## Private desk [#private-desk]
| Method and path | Request | Result or authority |
| --------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `GET /api/private/status` | None | Desk readiness, named contract/key, pause state and stake limits. |
| `POST /api/private/open` | `owner`, `marketId`, `side`, `stakeBase`, `minQuantityRaw`, `issuedAtMs`, `signature` | Verifies owner instruction, then runs charge/fund/mint and returns signed ticket or refusal/unknown state. |
| `POST /api/private/cashout` | `claim`, `signature` | Verifies desk-signed claim and resumes settlement/sweep/credit. |
A claim contains `owner`, `slotId`, `creditKey`, `marketId`, `outcomeIdx`, `stakeBase` and `issuedAtMs`. The owner's address comes from signed claim bytes. Cash-out returns to private balance, not directly to a supplied destination wallet.
Private opens require a canonical signature. A new charge requires fresh authorization; resuming an already landed charge may reuse the older authorization so funds are not stranded. See [Private mode](/architecture/private) before integrating this trust model.
## Duel discovery, room identity and history [#duel-discovery-room-identity-and-history]
| Method and path | Request | Result or authority |
| ---------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| `GET /api/games/room-token` | None | Public arena, chain and room URL. |
| `POST /api/games/room-token` | First: `wallet`, `key`, `issuedAtMs`, `signature`; renew: `token` | Signed room credential, expiry, session end and URL. |
| `GET /api/games/occupancy` | None | Queue counts/pairing state through the room service; no player list. |
| `GET /api/games/history` | Required `address` query | Latest 50 projected duels for a wallet. |
| `GET /api/games/rank` | Optional `address` query | Top 50 ladder rows, optional personal row and season eligibility. |
| `GET /api/games/season` | None | Configured season/prize rules and separate on-chain escrow read. |
The first room signature belongs to the browser key. Its claimed wallet association is checked against the arena's registered seat key after entry; the room token alone is not proof the wallet owner signed it. Renewals stay inside the same session and arena binding.
The WebSocket room uses messages defined in `packages/core/src/games/protocol.ts`: versioned `hello`, `queue.join`, `queue.leave`, `seed.reveal`, `resync`, `pick.pending`, `chat` and `reaction`. It supplies snapshots, presence and chain-derived updates. Arena create/join/pick/claim remain contract actions.
## Arcade [#arcade]
| Method and path | Request | Result or authority |
| ------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /api/games/arcade/board` | `game`; optional `address` query | Current-engine top scores, personal best/rank and fresh seed. |
| `POST /api/games/arcade/score` | `game`, `token`, `seed`, `engineVersion`, `durationMs`, `score`, `calm`, `trace` | Replays inputs and accepts only reproduced score/duration. |
Game is `line-rider` or `candle-hop`. Score posting needs `x-masayume-device`, a valid room token and a configured store. The response includes rank, personal-best status and current board. Scores are off-chain and do not prove human play.
## Lucky [#lucky]
| Method and path | Request | Result or authority |
| ------------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `POST /api/games/lucky/commit` | `wallet`, `stakeBase` | Persists server seed and returns draw id, commitment, nonce and policy. |
| `POST /api/games/lucky/reveal` | `drawId`, `clientSeed` | Discloses deterministic draw plus candidate record and a current market opportunity; places nothing. |
| `POST /api/games/lucky/placed` | `drawId`, `status`, optional `txHash` | Verifies a confirmed fill against the wallet's tape or records a refusal/unknown result. |
| `GET /api/games/lucky/history` | Required `address` query | History with lazy reconciliation against actual fills and settlement. |
| `GET /api/games/lucky/board` | None | Verified Lucky streak records. |
Commit uses the device header for rate gating. The supplied wallet at commit is not a wallet-signature login. Placement confirmation relies on actual fill evidence, and user trade confirmation still happens separately through the ordinary ticket lane.
Placement status is `confirmed`, `nothingFilled`, `refused`, `reverted`, `unknown` or `declined`. A confirmed report without a hash is rejected. A hash not yet found on the tape remains unknown instead of becoming a fabricated fill.
## Integration discipline [#integration-discipline]
Use the shared protocol/schema and signature-message builders from the application source. These endpoints have no common bearer-key scheme, no published external API version and no uniform retry contract. Preserve the route-specific unknown state, and never automatically replay an action capable of spending funds merely because a request timed out.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/core/src/faucet/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/faucet/index.ts)
- [web/src/features/funding/faucet-service.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/faucet-service.server.ts)
- [web/src/app/api](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/api)
- [web/src/features/strategies/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/protocol.ts)
- [web/src/features/sensei/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/protocol.ts)
- [web/src/features/x/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/protocol.ts)
- [web/src/features/room/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/room/protocol.ts)
- [web/src/features/takes/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/takes/protocol.ts)
- [packages/core/src/private/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/private/protocol.ts)
- [packages/core/src/games/protocol.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/games/protocol.ts)
---
# Configuration reference
Which process needs each setting, and how missing configuration behaves.
Canonical URL: https://docs.masayume.app/builders/configuration
Application origin: https://masayume.app
Reviewed: 2026-09-07
Public browsing needs no environment file. Connected services need specific configuration in the process that uses it. The tables below list names and behavior; they contain no credentials.
## Web settings visible to the browser [#web-settings-visible-to-the-browser]
Next embeds `NEXT_PUBLIC_` values in the client build. Put only public configuration in these fields, and rebuild when changing a value used by the browser.
| Name | Purpose |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_APP_ORIGIN` | App origin used for app URLs; local default is `http://localhost:3000`. |
| `NEXT_PUBLIC_DOCS_URL` | External documentation origin used by app links and old `/docs` redirects; production uses `https://docs.masayume.app`. |
| `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` | Optional WalletConnect project configuration. |
| `NEXT_PUBLIC_CHAIN_ID` | Parsed chain setting; checked-in integration targets Shannon. Changing a number alone does not port contracts or signer clients to another chain. |
| `NEXT_PUBLIC_INDEXER_URL` | DreamDEX GraphQL indexer endpoint. |
| `NEXT_PUBLIC_RPC_HTTP_URLS` | Comma-separated HTTP RPC endpoints. |
| `NEXT_PUBLIC_RPC_WS_URLS` | Comma-separated WebSocket RPC endpoints. |
| `NEXT_PUBLIC_VENUE_ID` | Venue used by app discovery. |
| `NEXT_PUBLIC_PRICE_FEED_URL` | Optional feed endpoint override. |
| `NEXT_PUBLIC_PRICE_FEED_QUOTE` | Feed quote currency setting. |
| `NEXT_PUBLIC_X_HANDLE` | Public handle users mention. |
| `NEXT_PUBLIC_X_EXECUTOR_ADDRESS` | Public fallback for the X grant's executor address. |
HTTP and WebSocket endpoint lists do not imply automatic runtime failover. The source currently keeps automatic rotation off.
## Local contract overrides [#local-contract-overrides]
Production normally uses the generated deployment manifest. These app overrides exist for a deliberately matched local fork:
| Contract | Address override | Start-block override |
| ---------------- | ---------------------------------------- | ------------------------------------------- |
| EventVault | `NEXT_PUBLIC_EVENT_VAULT_ADDRESS` | `NEXT_PUBLIC_EVENT_VAULT_FROM_BLOCK` |
| Forwarder | `NEXT_PUBLIC_FORWARDER_ADDRESS` | — |
| ParlayReserve | `NEXT_PUBLIC_PARLAY_RESERVE_ADDRESS` | `NEXT_PUBLIC_PARLAY_RESERVE_FROM_BLOCK` |
| RangeReserve | `NEXT_PUBLIC_RANGE_RESERVE_ADDRESS` | `NEXT_PUBLIC_RANGE_RESERVE_FROM_BLOCK` |
| MarketMakerVault | `NEXT_PUBLIC_MARKET_MAKER_VAULT_ADDRESS` | `NEXT_PUBLIC_MARKET_MAKER_VAULT_FROM_BLOCK` |
| LeverageReserve | `NEXT_PUBLIC_LEVERAGE_RESERVE_ADDRESS` | `NEXT_PUBLIC_LEVERAGE_RESERVE_FROM_BLOCK` |
| PrivateDesk | `NEXT_PUBLIC_PRIVATE_DESK_ADDRESS` | `NEXT_PUBLIC_PRIVATE_DESK_FROM_BLOCK` |
The market package also accepts GameArena address/from-block in its programmatic configuration. The current `web/src/lib/env.ts` does not expose matching `NEXT_PUBLIC_GAME_ARENA_*` variables. Do not invent environment support from a TypeScript option name.
## Shared records [#shared-records]
`DATABASE_URL` is server-only. Configure it on web and the ops actors that need the same records. The driver uses a small connection pool and requires TLS for hosts other than local loopback.
Without it, public market browsing works, but X relay, stored social activity, durable agent memory, Lucky draws, arcade score posting and the duel settler worklist are unavailable or degraded.
## AI on web and ops [#ai-on-web-and-ops]
| Name | Purpose |
| ------------------------------ | ---------------------------------------------------------- |
| `AI_MODEL` | Model identifier supplied to the resolver. |
| `AI_BASE_URL` + `AI_API_KEY` | Together select a custom OpenAI-compatible endpoint. |
| `ANTHROPIC_API_KEY` | Direct credential when the selected provider is Anthropic. |
| `OPENAI_API_KEY` | Direct credential when the selected provider is OpenAI. |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Direct credential when the selected provider is Google. |
| `AI_GATEWAY_API_KEY` | Fallback route through the AI Gateway. |
Resolution order is custom endpoint, selected provider's direct key, Gateway, then unavailable. The checked-in default model is `anthropic/claude-opus-5`; this is a source default, not a claim that your account can access it.
Configure web for Sensei and Studio Dry read. Configure ops independently for AI runner execution. A credential on one host does not configure the other. Dry-run trading can still make model calls.
## Strategy runner [#strategy-runner]
| Name | Behavior |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUNNER_PRIVATE_KEY` | Key that must match each strategy's runner. |
| `STRATEGY_IDS` | Optional comma-separated ids. Empty discovers strategies naming the key and its historical attempts; inactive strategies are retained for settlement. |
| `STRATEGY_RUNNER_ADDRESS` | Web's public house-runner address. This is an address, not a private key. |
| `RUNNER_INTERVAL_MS` | Defaults to 30,000 ms; accepted minimum 5,000 ms. |
| `AGENT_MAX_CALLS_PER_HOUR` | Sliding-hour AI call budget across the runner's strategies; default 60. |
| `AGENT_TIMEOUT_MS` | Per-read timeout; default 20,000 ms. |
| `VENUE_ID` | Optional ops venue override. |
| `DRY_RUN` | Runner suppresses sends only when explicitly `1` or `true`. |
| `DATABASE_URL` | Required for new trades, durable decision/execution reservations, risk history and heartbeats. |
With no key, explicit strategy ids can still be inspected and reported when the required stores are available. With neither ids nor key, the runner idles. Missing AI credentials make AI strategies hold. Missing or stale risk data and unresolved execution attempts also hold new submissions. Keep the strategy runner and X executor on distinct keys, with one process writing each key.
## X: web and relay use different credentials [#x-web-and-relay-use-different-credentials]
| Process | Names | Purpose |
| ------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web | `X_API_KEY`, `X_API_KEY_SECRET` | OAuth 1.0a consumer credentials for sign-in. |
| Web | `X_SESSION_SECRET` | Signs account identity cookies; no safe public fallback. |
| Web | `X_REDIRECT_URI` | Optional callback override; otherwise app origin plus `/api/x/callback`. |
| Web | `X_EXECUTOR_ADDRESS` | Public address to name in Executor grants; takes precedence over public fallback. |
| Ops | `X_RETTIWT_API_KEY` | Operator account-session credential used by the current mention transport. |
| Ops | `X_HANDLE` | Account whose mentions are searched; must match the authenticated operator session. |
| Ops | `X_EXECUTOR_PRIVATE_KEY` | Key executing under wallet grants. |
| Ops | `X_POLL_MS` | Poll interval; default 20,000 ms, minimum 5,000 ms. |
| Ops | `X_POSTING_ENABLED` | `1` or `true` enables public replies. |
| Ops | `X_REPLY_IMAGES_ENABLED` | `0` or `false` disables reply images. Otherwise images are enabled for replies when posting is on; image preparation/upload failures can fall back to text. |
| Ops | `DATABASE_URL` | Required for account links, cursor, one-time mention claims, durable execution recovery, reply delivery and separate polling/execution/delivery health. |
The callback origin must match the browser origin that writes OAuth cookies. Starting on another origin redirects to the configured canonical origin.
The relay's session credential is sensitive account access. Do not publish it or put it in a client variable. Startup resolves the session's stable account id; a configured-handle mismatch prevents the relay from starting. Turning replies off does not turn trading off.
## Testnet onboarding faucet on web [#testnet-onboarding-faucet-on-web]
| Name | Purpose |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `STT_FAUCET_ENABLED` | Only the exact value `true` enables STT allocations. |
| `STT_FAUCET_PRIVATE_KEY` | Dedicated server-only Shannon funding key, separate from admin, runner and sponsor keys. |
| `STT_FAUCET_RPC_URL` | Optional HTTP endpoint override; sends require chain id 50312. |
| `DATABASE_URL` | Required shared durable challenge, quota and signed-transfer records. |
Fund the dedicated wallet with Shannon STT. The address and readable balance are returned by `GET /api/faucet`; the API never returns its private key or signed transaction bytes. Do not use the same key for unrelated transactions: a conflicting nonce stops allocations for review.
The fixed policy tops wallets below 1 STT up to 2 STT, once per rolling 24 hours, with a 40 STT rolling global allocation and 10 STT retained reserve. The fee envelope is checked separately before signing. Limits and pending transfers are coordinated with a PostgreSQL transaction lock across web instances. A missing database or unreadable required chain state prevents a new transfer.
Production POST routes currently trust [Vercel's overwritten `x-forwarded-for` header](https://vercel.com/docs/headers/request-headers) for an HMAC-derived connection identifier. Production outside Vercel fails closed until a trusted proxy adapter is implemented. Raw IPs are not stored. A shared connection can receive at most ten allocations per rolling 24 hours; signature challenges are also limited. These caps bound distribution but are not proof that each wallet belongs to a different person.
Only the STT leg uses this service. The tUSDC leg remains the user's transaction through the DreamDEX SDK faucet. This is independent of the older sponsorship routes below and grants no trading or deposit permission.
## Sponsor and private desk on web [#sponsor-and-private-desk-on-web]
| Name | Purpose |
| ------------------------------ | ----------------------------------------------------------------- |
| `SPONSOR_PRIVATE_KEY` | Pays STT for accepted vault relay calls and duel-key gas top-ups. |
| `SPONSOR_RPC_URL` | Optional sponsor HTTP endpoint override. |
| `SPONSOR_MAX_GAS` | Ceiling for a forwarded vault request. |
| `SPONSOR_PER_ADDRESS_PER_HOUR` | Request cap; default 30. |
| `SPONSOR_PER_DEVICE_PER_HOUR` | Device cap; default 60. |
| `SPONSOR_GAME_MAX_WEI` | Per-match duel gas top-up ceiling. |
| `PRIVATE_DESK_PRIVATE_KEY` | Key matching the contract's named desk. |
| `PRIVATE_DESK_RPC_URL` | Optional desk HTTP endpoint override. |
The sponsor declines unsupported targets, selectors, native value, gas or deadlines. It never supplies the player's deposit or pot. Sponsor counters and funded-seat tracking are process-local, not shared durable quotas.
PrivateDesk checks its named key, pause state, stake limits and gas readiness. Its open is three desk transactions, so the key must fund more than one send.
## Game room and recovery [#game-room-and-recovery]
| Name | Process and purpose |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `ROOM_TOKEN_SECRET` | Same server secret on web and room; ops requires at least 16 characters. |
| `GAME_ROOM_PUBLIC_URL` | Web-visible room WebSocket URL, returned by room-token API. |
| `GAME_ROOM_HOST` | Ops listen host; default loopback. |
| `GAME_ROOM_PORT` | Ops listen port; default 8787. |
| `GAME_ROOM_REGION` | Queue grouping; default `default`. |
| `GAME_DECK_KEY` | 32-byte hex key for AES-256-GCM deck material. |
| `GAME_DECK_JOURNAL` | Persistent journal path; default `.masayume/deck-journal.jsonl` relative to process working directory. |
| `GAME_DECK_HORIZON_SEC` | Deck eligibility horizon; default one hour. |
| `GAME_DECK_CREATE_LATENCY_SEC` | Time allowance for creation when testing remaining card life; default 45 seconds. |
| `GAME_CREATE_WINDOW_MS` | Wait for pending on-chain creation; default two minutes. |
| `GAME_PROJECTOR_POLL_MS` | Event projection poll interval; default 6 seconds. |
| `GAME_PROJECTOR_SPAN` | Bounded block span; default 800. |
| `GAME_PROJECTOR_SPANS` | Spans per catch-up cycle; default 25. |
| `GAME_PROJECTOR_FROM` | Explicit projector starting block override. |
| `GAME_SETTLER_PRIVATE_KEY` | Key paying for arena maintenance calls. |
| `GAME_SETTLER_REFRESH_MS` | Settler refresh; default 30 seconds. |
The web fallback room secret is random per process. It may support isolated development behavior, but it cannot authenticate tokens to a separate room process. Configure the shared secret for multiplayer.
## Maker and leverage keeper [#maker-and-leverage-keeper]
| Name | Purpose |
| ----------------------------- | --------------------------------------------------------------------- |
| `MAKER_PRIVATE_KEY` | Named maker key. |
| `MM_ASSETS`, `MM_INTERVALS` | Markets considered; default intervals are 300, 900 and 3,600 seconds. |
| `MM_HALF_SPREAD_RAW` | Desired half-spread in raw price units; default 15,000. |
| `MM_QUOTE_SIZE` | Whole contracts per side before contract/lot caps; default 5. |
| `MM_REFRESH_MS` | Maker refresh; default 45 seconds. |
| `MM_QUOTE_TTL_SEC` | Quote lifetime; default 180 seconds. |
| `MM_REQUOTE_TICKS` | Price move before requote; default 3 ticks. |
| `LEVERAGE_KEEPER_PRIVATE_KEY` | Key paying for knock-out and settlement calls. |
| `LK_REFRESH_MS` | Leverage keeper refresh; default 20 seconds. |
Maker, leverage keeper and duel settler default to dry-run. They send only when `DRY_RUN` is `0` or `false`. This differs from the strategy runner. Set it deliberately rather than relying on a shared default.
## Seasons and contract tools [#seasons-and-contract-tools]
| Name | Purpose |
| -------------------------- | ---------------------------------------------------- |
| `SEASON_ID` | Enables a configured season; absent means no season. |
| `SEASON_NAME` | Display name, otherwise the id. |
| `SEASON_ENDS_AT` | Required ISO instant when a season id is set. |
| `SEASON_PRIZE_SPLIT` | Rank bands in `start:end:amount` format. |
| `SEASON_MIN_STAKED_DUELS` | Prize eligibility floor; default 1. |
| `SEASON_ELIGIBILITY_NOTE` | Explanation shown beside eligibility. |
| `SEASON_ADMIN_PRIVATE_KEY` | Operator distribution tool's signing key. |
Share the same season rules between web and payout tools. The contract end time does not automatically authorize or trigger payout.
Contract scripts separately use settings such as `DEPLOYER_PRIVATE_KEY`, `SHANNON_FORK_URL`, `FORK_MARKET_ID`, `FORK_RESOLVED_MARKET_ID`, `FORK_ASSET` and `SETTLED_QUESTION_ID` for specific deployment/fork scenarios. Inspect the selected script: these are not web runtime variables and should not be copied wholesale into a web host.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/funding/faucet-config.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/faucet-config.server.ts)
- [packages/core/src/faucet/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/faucet/index.ts)
- [packages/db/src/faucet.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/faucet.ts)
- [web/src/lib/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/env.ts)
- [web/src/lib/docs-url.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/docs-url.ts)
- [packages/markets/src/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/env.ts)
- [packages/brain/src/model.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/brain/src/model.ts)
- [services/ops/src/actors/strategy-runner/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/env.ts)
- [services/ops/src/actors/x-relay/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/env.ts)
- [services/ops/src/actors/x-relay/rettiwt.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/rettiwt.ts)
- [services/ops/src/actors/x-relay/poll-cycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/poll-cycle.ts)
- [packages/db/src/x-health.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-health.ts)
- [web/src/features/x/config.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/config.server.ts)
- [web/src/features/session/sponsor.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/sponsor.server.ts)
- [web/src/features/games/sponsor.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/sponsor.server.ts)
- [web/src/features/private/desk.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/desk.server.ts)
- [services/ops/src/actors/game-room/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/game-room/env.ts)
- [services/ops/src/actors/matchmaker/seal.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/matchmaker/seal.ts)
- [services/ops/src/actors/matchmaker/deckmaster.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/matchmaker/deckmaster.ts)
- [services/ops/src/actors/market-maker/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/market-maker/env.ts)
- [services/ops/src/actors/leverage-keeper/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/leverage-keeper/env.ts)
- [packages/core/src/games/season.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/games/season.ts)
---
# Contracts and deployment records
The named contract for each feature, its authority and the checked-in testnet addresses.
Canonical URL: https://docs.masayume.app/builders/contracts
Application origin: https://masayume.app
Reviewed: 2026-09-07
Masayume's contracts wrap DreamDEX's market infrastructure. The application stores market ids as durable identity and resolves the current pool or settlement route when needed.
## Masayume contracts [#masayume-contracts]
The following addresses are a **checked-in Shannon deployment snapshot reviewed on 5 September 2026**, for chain 50312. They are not a fresh guarantee of funded reserves, active services or contract permissions.
| Contract | Role | Snapshot address |
| ---------------- | ------------------------------------------------- | -------------------------------------------- |
| EventVault | Trading Balance and bounded grants | `0x84Ec824D89ee78d5728545CE0B40EC968aa7CD7A` |
| ERC2771Forwarder | Relay signer-approved vault calls | `0x82bb75b8aE663abC73308Ce42ca00d701cFb50d3` |
| StrategyRegistry | Creator metadata, runner and subscription consent | `0xAd5f37B0f3d0f6030B9d9c0f4985AFb184A85FB4` |
| ParlayReserve | Funded multi-Window tickets | `0x50Ced768C80d499bA4FB956C7DF0c2beB078C151` |
| RangeReserve | Funded closing-price bands | `0x1F8dB9B0913cB09e5CfDe44Adfa7Ff22b0868386` |
| MarketMakerVault | Supplier shares and bounded maker inventory | `0xc904F38f38eF96E8741C7D9218a7899504B99e79` |
| LeverageReserve | Financed calls and knock-outs | `0x5484fF06F4B6a8108fABb2511385985D933a2D23` |
| PrivateDesk | Private balance, pool and slot operations | `0x4D27115c4eff6536bf0D009ACeBf339AA02128bB` |
| GameArena | Duel commitments, picks, pots and credits | `0x0d8FC9659d02070aD8fF7E9a27E5394B9F5a2EF2` |
| SeasonPrizePool | Admin-controlled season escrow and payout | `0x6B340DBE7AC3283B5f5c3aA5f6AaEd57378596fA` |
The same snapshot names test collateral `0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E`.
## Upstream market contracts [#upstream-market-contracts]
`packages/markets/src/addresses.pinned.json` pins the infrastructure used with Somnia Markets SDK 0.28.1. It includes BinaryMarketsModule, settlement, market creation, the collateral router and OracleHub.
| Upstream role | Snapshot address |
| ------------------- | -------------------------------------------- |
| BinaryMarketsModule | `0x3ecC694Cef705358864a646142ac17A90E29e388` |
| Binary settlement | `0xbF4a49e0Dfd092e5FBE8E5761064C49533e6Ed23` |
| OracleHub | `0xe40db387cC98601Dd11bd634fF2f3AD5686dE32b` |
Read the manifest used by the actual app build before a deployment or integration. Older contract README status labels are behind this snapshot.
## Authority to inspect [#authority-to-inspect]
EventVault grants enforce actor, expiry and spending caps. Specialist reserves expose admin parameters and pause controls; those controls do not all have the same effect. MarketMakerVault has a named maker. PrivateDesk has a named desk. SeasonPrizePool has an admin who controls distribution and remainder withdrawal.
Permissionless settlement means anyone can trigger a permitted state transition. It does not mean every feature is fully decentralized or has no operator trust. In particular, private owner crediting and season distributions have explicit operator authority.
## Local checks [#local-checks]
From the application root:
```sh
pnpm contracts:test
pnpm contracts:export
```
`contracts:test` runs the non-fork Foundry tests. The export command regenerates TypeScript ABIs and address data; it does not deploy a contract. Inspect its diff before using the output.
Fork suites need an RPC and suitable live or resolved Windows for the scenario. A passing mock test does not establish current Shannon liquidity or oracle readiness.
## Deployment sequence [#deployment-sequence]
Deploy the selected contract with its reviewed configuration, preserve the resulting chain deployment record, export matching ABIs/addresses, then build web and ops from that same revision. A new address by itself does not update an already deployed web bundle or worker.
Deployment and supplier funding move assets and spend STT. They are operator actions, not documentation validation commands. Verify the named role and its balance separately from bytecode presence.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/markets/src/addresses.masayume.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/addresses.masayume.json)
- [packages/markets/src/addresses.pinned.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/addresses.pinned.json)
- [contracts/export.mjs](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/export.mjs)
- [contracts/src/vault/EventVault.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/vault/EventVault.sol)
- [contracts/src/strategy/StrategyRegistry.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/strategy/StrategyRegistry.sol)
- [contracts/src/games/SeasonPrizePool.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/SeasonPrizePool.sol)
- [package.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/package.json)
---
# Maintain this documentation
Add a guide, refresh real captures and keep every source and route accounted for.
Canonical URL: https://docs.masayume.app/builders/docs-site
Application origin: https://masayume.app
Reviewed: 2026-09-07
This site has its own repository and serves pages from `/`. It can be developed and deployed independently of the trading application. The public application is [masayume.app](https://masayume.app); the docs domain is configured separately.
## Start the site [#start-the-site]
Use Node.js 22 or newer, install with the repository's pinned pnpm version, then run:
```sh
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev
```
Open `http://localhost:3333`. Set `NEXT_PUBLIC_DOCS_URL` to that origin locally and `NEXT_PUBLIC_APP_URL` to `https://masayume.app`. These are public origins, not credentials. The documentation server needs no wallet key, database or model provider.
## Add a useful guide [#add-a-useful-guide]
Start with what the reader wants to achieve. Explain what they need, the exact controls they use, what success looks like and what to do if the result is unfinished. Keep the first explanation simple; put contract details below it or link to the architecture page.
Create the page under `content/docs//.mdx`:
```mdx
---
title: Make your first call
description: Choose a Window, review the price and follow the result.
sources:
- web/src/app/markets/page.tsx
---
Open Markets and choose a Window.
Read [how the ticket works](/architecture/event-contracts).
```
Add the slug to that section's `meta.json`. The file's location determines the documentation URL. `index.mdx` is the section's root page.
Use ordinary Markdown links between docs pages. Use `AppLink` for application destinations, so a deployment can set the app origin once. Source paths are relative to the Masayume application repository; they are not paths in this documentation repository.
Read each cited source and the surrounding call path. A file existing is useful evidence for a link check, but does not prove a description is accurate. Screens that are empty, unavailable, behind a wallet connection or developer fixtures need to be described in their actual state.
## Add an annotated capture [#add-an-annotated-capture]
1. Open the real screen on `https://masayume.app` and reach the state the guide explains.
2. Capture the viewport without account-identifying details or private recovery material. A connected session does not authorize a trade or public post.
3. Keep the original file bytes: use `public/guides/.png` for a PNG or `public/guides/.jpg` for a JPEG.
4. Add its entry to `lib/guides.ts`: title, alt text, app path, honest state, dimensions and arrow coordinates. Add `extension: 'jpg'` for JPEG captures; PNG is the default.
5. Place the component where the screenshot helps the next step:
```mdx
```
The component adds numbered arrows and Masayume branding in a separate layer. Keep the underlying capture intact. The shared `guideImagePath(name)` helper uses the recorded extension for screenshots, original-image links and video posters. Correct a mislabeled extension by renaming the file and updating its registry entry; do not convert or regenerate its pixels. The content checker verifies PNG/JPEG signatures as well as file existence.
Check that each arrow lands on the intended control at the actual capture dimensions. Open and close the expanded view with both pointer and keyboard. Review the caption's capture date and state when replacing an image; old commentary should not silently describe a new capture.
## Add a walkthrough [#add-a-walkthrough]
Record the real interaction. A preview of a ticket should be labelled as a preview. An explanation of a trade should only call it completed when the recording actually shows the receipt or confirmed fill.
Store the video at `public/videos/.mp4` and synchronized captions at `public/videos/.vtt`. Add the title, description, poster and chapters to the `movies` manifest in `components/walkthrough.tsx`, then reference it:
```mdx
```
Write the chapter text as a useful transcript for someone who cannot play the video. Check that each chapter time matches the recording, its button seeks to the correct moment, captions appear and the poster exists. Keep temporary captures and browser logs outside public assets.
The three included public-app videos can be rebuilt with `node scripts/render-walkthroughs.mjs practice candle-hop ticket` when their original timestamped JPEG recordings are available under `evidence/raw-video`. That directory is ignored by Git. The script needs local `ffmpeg` and `ffprobe`, uses Next's installed Sharp image runtime for separate annotation layers, and retains the original frame files unchanged. Exported MP4s, captions and capture provenance stay in `public/videos`.
## Update an architecture map [#update-an-architecture-map]
Edit the named map in `lib/diagrams.json`. Give each box a plain-English role, a clear authority statement and the source paths that support it. Connect only relationships that exist in the code. An API storing a game record and a contract paying a winner are different responsibilities and should remain distinguishable.
Generate the branded downloads after editing:
```sh
node scripts/export-diagrams.mjs
```
`Architecture` renders the interactive map and links to `public/diagrams/.svg`. Set `exportPng: true` on a map when a raster image is also needed, as in the [DreamDEX integration map](/builders/dreamdex-sdk). The same export command generates both formats. Set a map's `reviewed` date only after checking its sources; existing maps retain their own dates.
Check box selection, small-screen scrolling, the text equivalent and the exported image. The checker can detect a missing box or file; it cannot decide whether an arrow tells the truth.
## Keep coverage current [#keep-coverage-current]
`evidence/source-coverage.json` records the reviewed application commit, the design-reference commit, every app page and every API method. Each app route points to a guide or has an explicit developer-only, redirect, unavailable or removed status. Developer-only describes a fixture's intended use; it is not an authentication claim.
When application behavior changes:
1. Read the change against the recorded commit.
2. Update the affected user steps, architecture and builder reference.
3. Add or revise the route/API coverage entries.
4. Refresh media when a control or state no longer matches.
5. Advance the source revision in the evidence record and `lib/site.ts` after reviewing the content.
The STRK20 site is a design reference. Its behavior is never a substitute for reading Masayume's own source. A source commit also does not prove which build is live at the public app domain.
## Run the checks [#run-the-checks]
The source checker expects the app in sibling directory `../sommina-events`. Supply a different location if needed:
```sh
node scripts/check-content.mjs --source /path/to/masayume
pnpm typecheck
pnpm build
```
It checks documentation links, ordinary heading fragments, navigation, application links, source paths at the pinned commit, route coverage, API methods and media files. Dynamic links and generated headings still need a browser check.
During capture work, `--allow-missing-media` keeps missing media visible as warnings. Run the strict checker before release. Neither mode changes content or removes an unfinished reference.
Finish by opening the affected pages at desktop and phone sizes in light and dark mode. Test search, screenshot expansion, diagrams and any video controls. Builds and source checks complement that browser review; they do not replace it.
## Publish independently [#publish-independently]
Connect this repository to a Next.js-capable host. Build from the repository root with `pnpm build`. Set `NEXT_PUBLIC_DOCS_URL` to the chosen docs origin and `NEXT_PUBLIC_APP_URL` to the public app origin before building.
After the docs domain is ready, set the application's own docs-origin variable to that domain and rebuild the app's outgoing links and old-bookmark redirects. Verify both directions on the deployed sites. The independent docs repository is [Blockchain-Oracle/masayume-docs](https://github.com/Blockchain-Oracle/masayume-docs); access is private. The public deployment at [docs.masayume.app](https://docs.masayume.app) was verified on 7 September 2026.
## Keep AI-readable exports useful [#keep-ai-readable-exports-useful]
The site serves [llms.txt](/llms.txt) as a short index and [llms-full.txt](/llms-full.txt) as the complete guide export. Each page also has a `/raw/` Markdown endpoint, used by **Copy Markdown**. For example, [the DreamDEX SDK guide](/raw/builders/dreamdex-sdk) contains the feature-to-code map without requiring a browser to render the page.
These exports are generated from the same guide collection as the site. The index starts with the SDK integration and architecture guides; individual and full exports include the canonical page URL, review date and the same pinned source notes shown in the browser. An application link inside an `AppLink` component uses the application origin; ordinary relative documentation links use the docs origin. GitHub source links still need repository access.
After a content change, verify that the new guide appears in the index and full export, that its source URLs name the reviewed commit, and that its Markdown endpoint responds as `text/plain`. The filenames are lowercase `llms.txt` and `llms-full.txt`.
---
# How Masayume uses DreamDEX
Follow the Somnia Markets SDK from a product feature to its exact calls, code and on-chain evidence.
Canonical URL: https://docs.masayume.app/builders/dreamdex-sdk
Application origin: https://masayume.app
Reviewed: 2026-09-07
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](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/package.json#L31).
## Start with the integration boundary [#start-with-the-integration-boundary]
[Download the architecture image (PNG)](/diagrams/dreamdex-sdk.png) · [Download the vector image (SVG)](/diagrams/dreamdex-sdk.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](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/runtime/read-runtime.ts#L64), [the shared read interface](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/index.ts), [signing sessions](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/sessions/submitter-session.ts#L74) and [order routing](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/submitter/order-lane.ts). The [system map](/architecture/overview) shows the wider app and service boundaries.
## Which SDK calls power which features? [#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.
| Product need | SDK capability used | Where it connects |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Find live and past Windows | `listLiveBinaryMarkets`, `listPastBinaryMarkets`, `getBinaryMarket` | [Market discovery](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/markets.ts#L21) groups markets into the lanes shown in the app and scanned by operators. |
| Read current executable liquidity | `getBinaryOrderBook`, `getBinaryBookParams` | [Book reads](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/books.ts#L11) supply depth, tick size, lot size and minimum quantity. |
| Turn a stake into a bounded quote | `quoteBinaryStakeOverBook`, `quoteBinaryOrderOverBook` | [Quote calculation](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/quotes.ts#L26) calculates quantity and cost; `freshQuoteStake` rereads the chain book before execution. |
| Keep the ticket and charts current | `watchMarket`, `subscribeLive`, `getLiveBinaryOrderBookByMarket`; `SomniaMarketsProvider`, `useWatchMarket`, `useLiveBinaryOrderBookByMarket`, `useLiveStatus`, `useWatchPrice`, `useLivePrice` | [Book coordination](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/runtime/coordinator.ts#L100), [ticket hooks](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/react/useStakeQuote.ts#L23) and [price hooks](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/react/useAssetPrice.ts) connect live SDK state to React. |
| Build price context for charts and agents | `getOpeningPrices`, `fetchPrice`, `fetchPriceHistory` | [Price adapter](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/prices.ts#L12) provides the opening print, spot/EMA and price path. |
| Verify the Window and its fees | `getMarketOnchain`, `getMarketFees`, `getMarketResolution` | [Chain state](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/onchain.ts#L8), [fees](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/fees.ts#L11) and [resolution](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/resolution.ts#L7) support entry checks and outcome display. |
| Show wallet funds and positions | `getErc20Balance`, `getNativeBalance`, `getPortfolio`, `getVaultBalance`, `getVaultPayoutFallbacks`, `getOpenPositionsWithPnL`, `getBalances` | [Balance sheet](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/balances.ts#L45) and [positions](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/positions.ts#L7) distinguish wallet funds, venue escrow and outcome-token holdings. Our Trading Balance also has its own EventVault reads. |
| Reconstruct trading history | `getUserFills`, `getRouterActions`, `getBinaryMarket`, `getBalances` | [Wallet history](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/history.ts#L135) paginates records and associates fills with their actual Window. |
| Build venue activity and reconcile an uncertain direct order | `getFills`, `getUserFills`, `getOwnOpenOrdersOnchain`, `getViemClient` | [Venue scans](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/provider/scan.ts) feed activity statistics. [Direct-order recovery](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/submitter/reconcile.ts) checks the receipt, fills and open orders. Vault executions have a separate exact-event recovery path. |
| Submit a direct wallet order | `trader.placeOrder`, `ORDER_TYPE.MARKET`, `autoApprove` | [Order send](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/submitter/steps/send.ts#L23) sends an immediate-or-cancel order with a protective limit. This is the direct wallet route. |
| Obtain test collateral or redeem outcomes | `trader.faucet`, `trader.redeem` | [Transaction routing](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/submitter/tx-lane.ts#L52) uses explicit outcome IDs and checks transaction status. Masayume-contract settlements take their own routes. |
| Keep identity correct when a pool is reused | `marketKey`, `outcomeId`, `decodeOutcomeId`, `binaryModuleReadAbi`, `binarySettlementAbi` | [Identity adapter](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/identity.ts#L36) separates the durable `marketId`, pool-generation outcome IDs and settlement key. |
**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](/start/wallet) connects the two prompts, and [configuration](/builders/configuration#testnet-onboarding-faucet-on-web) 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](/builders/contracts) lists the upstream and Masayume-owned addresses separately.
## Trace one call from the app to DreamDEX [#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](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/vault/order.ts#L112) into [VenueGateway](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/contracts/src/vault/VenueGateway.sol) for that contract-to-contract connection.
## How agents and X reuse the integration [#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:
```ts
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](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/packages/markets/src/strategies/agent-context.ts#L35), [subscriber execution](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/services/ops/src/actors/strategy-runner/execute.ts#L33), [strategy settlement](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/services/ops/src/actors/strategy-runner/lifecycle.ts#L55) and [X execution](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/services/ops/src/actors/x-relay/execute.ts#L56). The [agent architecture](/architecture/agents) and [X architecture](/architecture/x) explain their database and recovery responsibilities.
## How the specialist products connect [#how-the-specialist-products-connect]
These are Masayume contracts and rules using DreamDEX infrastructure. They are not additional features supplied by the TypeScript SDK.
| Product | Connection to DreamDEX | Read more |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| Parlay | Its reserve reads the underlying Windows' resolved outcomes and applies the multi-leg payout rules. | [Parlay and event contracts](/architecture/event-contracts) |
| Range and Moonshot | RangeReserve reads the Window's numeric OracleHub answer and compares it with the chosen band. Moonshot uses the Range path; it does not place a directional CLOB order. | [Range settlement](/architecture/range), [Moonshot](/games/moonshot) |
| Boost | LeverageReserve finances actual outcome-token purchases and manages close, knock-out and settlement. | [Leverage](/architecture/leverage) |
| Earn | MarketMakerVault holds capital and inventory; the maker service manages bounded venue quotes. | [Market making](/architecture/earn) |
| Private mode | PrivateDesk funds separate slots holding venue positions; the desk's owner/claim association is an additional trust boundary. | [Private architecture](/architecture/private) |
| Duel | GameArena buys and redeems picks through the venue and records match accounting. Room messages are separate from chain results. | [Game architecture](/architecture/games) |
| Practice and arcade | Local simulation or server-verified scores; these are not proof that an SDK order or on-chain payout occurred. | [Practice](/games/practice), [Candle Hop](/games/candle-hop) |
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 [#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.
| Scenario | Actual result | Evidence |
| --------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X command | One BTC UP fill, 0.908520 tUSDC actual spend; matching sender/hash image delivered. | [Transaction](https://shannon-explorer.somnia.network/tx/0x072a0259bd75c22697d960da29c513ff9a0d3b0f24ba5eefbe626810093fa26b), [image reply](https://x.com/masayume_app/status/2096704198461084030) |
| AI strategy | A real model decision produced an ETH UP fill; it lost and settled for zero payout. | [Fill](https://shannon-explorer.somnia.network/tx/0xe175d59f302f3e55864dcaa05ccffa662c36461d942738e21157b37cb4d67d17), [settlement](https://shannon-explorer.somnia.network/tx/0x197388596631f01ce571894163e47aa4e268e41f8073718e56e57b56131679f8) |
| Corrected Momentum strategy | ETH DOWN settled for 1.661 tUSDC; a new BTC Window fill followed. | [Settlement](https://shannon-explorer.somnia.network/tx/0x88a8aefd9c3d6d310ac14710d893c9d72391446b864ce6bea8004de185492600), [subsequent fill](https://shannon-explorer.somnia.network/tx/0x0ea666592df851998655286a378714380ad7032289d7bd27c3a66d0984070b61) |
| Moonshot | A winning numeric-price ticket paid 2.000132 tUSDC through RangeReserve. | [Claim](https://shannon-explorer.somnia.network/tx/0x5e99e6496c2a4ece6ba33226c8e5dacd5ddef0f8b3247b462d5f3484ace9ee7f) |
The [acceptance ledger](https://github.com/Blockchain-Oracle/masayume/blob/a0e5d95c73e83396c5d610f4638e5d155cc8cc9f/docs/implementation/acceptance-2026-09-06.md) 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](https://masayume.app/demo) can be read independently.
## Read this with an AI tool [#read-this-with-an-ai-tool]
Use [llms.txt](/llms.txt) for the documentation index, [this guide as Markdown](/raw/builders/dreamdex-sdk), or [llms-full.txt](/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](https://docs.dreamdex.io/developers/event-contracts) and [its llms.txt](https://docs.dreamdex.io/llms.txt). The call-site map above is verified against Masayume's installed SDK version and source, independently of changes to upstream documentation.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [packages/markets/src/faucet/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/faucet/index.ts)
- [web/src/features/markets/faucet/useFaucet.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/faucet/useFaucet.ts)
- [packages/markets/package.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/package.json)
- [packages/markets/src/runtime/read-runtime.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/runtime/read-runtime.ts)
- [packages/markets/src/provider/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/index.ts)
- [packages/markets/src/provider/markets.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/markets.ts)
- [packages/markets/src/provider/books.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/books.ts)
- [packages/markets/src/provider/quotes.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/quotes.ts)
- [packages/markets/src/provider/prices.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/prices.ts)
- [packages/markets/src/provider/onchain.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/onchain.ts)
- [packages/markets/src/provider/fees.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/fees.ts)
- [packages/markets/src/provider/resolution.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/resolution.ts)
- [packages/markets/src/provider/balances.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/balances.ts)
- [packages/markets/src/provider/positions.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/positions.ts)
- [packages/markets/src/provider/history.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/history.ts)
- [packages/markets/src/provider/scan.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/provider/scan.ts)
- [packages/markets/src/submitter/reconcile.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/reconcile.ts)
- [packages/markets/src/submitter/steps/funding.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/steps/funding.ts)
- [packages/markets/src/collateral.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/collateral.ts)
- [packages/markets/src/runtime/coordinator.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/runtime/coordinator.ts)
- [packages/markets/src/react/provider.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/react/provider.tsx)
- [packages/markets/src/react/useStakeQuote.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/react/useStakeQuote.ts)
- [packages/markets/src/react/useAssetPrice.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/react/useAssetPrice.ts)
- [packages/markets/src/sessions/submitter-session.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/sessions/submitter-session.ts)
- [packages/markets/src/submitter/order-lane.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/order-lane.ts)
- [packages/markets/src/submitter/steps/send.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/steps/send.ts)
- [packages/markets/src/submitter/tx-lane.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/submitter/tx-lane.ts)
- [packages/markets/src/identity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/identity.ts)
- [packages/markets/src/vault/order.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/vault/order.ts)
- [packages/markets/src/strategies/agent-context.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/agent-context.ts)
- [services/ops/src/actors/strategy-runner/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/execute.ts)
- [services/ops/src/actors/strategy-runner/lifecycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/lifecycle.ts)
- [services/ops/src/actors/x-relay/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execute.ts)
- [contracts/src/vault/VenueGateway.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/vault/VenueGateway.sol)
- [contracts/src/range/RangeReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/range/RangeReserve.sol)
- [contracts/src/parlay/ParlayReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/parlay/ParlayReserve.sol)
- [contracts/src/games/ArenaGateway.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/games/ArenaGateway.sol)
- [contracts/src/leverage/LeverageReserve.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/leverage/LeverageReserve.sol)
- [contracts/src/maker/MarketMakerVault.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/maker/MarketMakerVault.sol)
- [contracts/src/private/PrivateDesk.sol](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/contracts/src/private/PrivateDesk.sol)
- [docs/implementation/acceptance-2026-09-06.md](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/docs/implementation/acceptance-2026-09-06.md)
---
# Run the app locally
Start the public app, then add only the services your feature needs.
Canonical URL: https://docs.masayume.app/builders/local-setup
Application origin: https://masayume.app
Reviewed: 2026-09-07
The public app boots against Somnia Shannon using checked-in defaults. You can start it without a database, model credential or operator wallet.
## Requirements [#requirements]
* Node.js 22 or later, as required by the application manifest.
* pnpm 11.24.0, the package manager pinned by this checkout.
* The Masayume application repository. This documentation site is a separate repository.
* Foundry only if you are working on the Solidity contracts.
## Start the application [#start-the-application]
From the application repository root:
```sh
pnpm install
pnpm dev
```
Open the local address printed by Next. Public market discovery uses the configured testnet indexer, RPC/WebSocket endpoints and price feed, so a working local server still depends on those remote services answering.
Use Status on the deployment you are inspecting to distinguish an unavailable dependency from an empty result.
## Workspace map [#workspace-map]
| Directory | Role |
| ------------------ | ------------------------------------------------------ |
| `web` | Next app, UI and server routes |
| `packages/core` | Domain rules, maths, game engines and parsers |
| `packages/markets` | Somnia Markets SDK and contract boundary |
| `packages/brain` | Shared AI provider resolver and structured agent reads |
| `packages/db` | Postgres schema and record access |
| `services/ops` | Long-running workers and game room |
| `contracts` | Solidity contracts and Foundry scripts |
| `scripts` | Architecture checks and protocol tools |
## Add a capability [#add-a-capability]
| You want | Add |
| ------------------------------------ | ------------------------------------------------------------------------- |
| Sensei or Studio Dry read | A supported AI model credential on web |
| Comments, Takes or durable histories | `DATABASE_URL` |
| House agent execution | A separately configured strategy runner |
| Multiplayer duel rooms | Shared room secret, room URL, running ops and deck recovery configuration |
| Trade from X | Web OAuth configuration plus a separately configured mention relay |
| Private mode | A server desk key matching the deployed PrivateDesk role |
See [Configuration](/builders/configuration) before adding values. Server private keys must never use a `NEXT_PUBLIC_` name.
## Check a change [#check-a-change]
```sh
pnpm typecheck
pnpm invariants
pnpm test
pnpm --filter web build
```
The invariant checker includes architecture boundaries such as keeping the Somnia SDK behind the market package. Contract checks run separately:
```sh
pnpm contracts:test
```
The application pins Next 16.3.4 in `web/package.json`. Read the relevant installed guides under `web/node_modules/next/dist/docs/` before editing framework-specific code, and check the actual manifest if the dependency has changed. Local AI instructions and research notes are ignored build aids; a fresh checkout does not need them to install or run.
## Database setup [#database-setup]
The database package uses `postgres` and plain schema SQL. It creates missing tables on first use under a transaction/advisory lock. There is no separate Drizzle command to run. This mechanism handles creation; future changes to existing rows or columns require a deliberate migration plan.
Do not start the whole ops service merely to browse the app. Configured actors can sign transactions. Use [Services](/builders/services) and select the process you need.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [package.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/package.json)
- [pnpm-workspace.yaml](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/pnpm-workspace.yaml)
- [web/package.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/package.json)
- [web/src/lib/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/env.ts)
- [packages/markets/src/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/env.ts)
- [packages/db/src/migrate.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/migrate.ts)
---
# Host your own agent
Run the same strategy loop with your own execution key and explicit mode.
Canonical URL: https://docs.masayume.app/builders/self-host-agent
Application origin: https://masayume.app
Reviewed: 2026-09-07
Self-hosting runs the existing strategy actor under your key. It does not give that key custody of subscribers' balances. Each subscriber still supplies an EventVault grant with limits.
Start with the [Launch an agent](/agents/launch) guide if you have not published a strategy.
## 1. Choose the runner identity [#1-choose-the-runner-identity]
Use a dedicated execution wallet. Publish its public address in the Studio's **Run your own bot** option. The runner's private key must resolve to that address. Publishing your personal wallet address does not create a separate bot key for you.
The key needs STT to pay transaction fees. Subscribers fund their own strategy budgets; the runner does not need to hold their test collateral.
## 2. Configure the process [#2-configure-the-process]
| Name | Purpose |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `RUNNER_PRIVATE_KEY` | Execution key matching the published runner address |
| `STRATEGY_IDS` | Optional comma-separated registry ids to run |
| `DRY_RUN` | Set explicitly to `true` for a rehearsal, `false` for enabled execution |
| `RUNNER_INTERVAL_MS` | Scan interval; defaults to 30 seconds |
| `DATABASE_URL` | Required for new trades: durable decisions, execution reservations, risk history and heartbeats |
| `VENUE_ID` | Optional venue override |
An AI strategy also needs `AI_MODEL` and a supported provider credential. See [AI configuration](/builders/configuration#ai-on-web-and-ops). A Momentum strategy uses the deterministic price rule and does not need a model to make its decisions.
Store secrets in your process manager or hosting secret settings. The runner entry point does not load a dotenv file itself. Having a file beside it does not prove the process received those variables.
## 3. Run a rehearsal [#3-run-a-rehearsal]
With the required values already loaded into your environment:
```sh
DRY_RUN=true pnpm --filter @masayume/ops start:runner
```
This starts the strategy actor alone. It does not start the maker, X relay or game actors. Dry-run suppresses trade execution, but AI reads may still call a paid model provider.
With no `STRATEGY_IDS`, a configured runner discovers registry strategies naming its own key and strategies with its earlier recorded attempts. Inactive strategies remain discoverable for position settlement; only active strategies with live subscribers can open new positions. With explicit ids, it still verifies each strategy's runner address before opening trades.
## 4. Read the evidence [#4-read-the-evidence]
Expected logs identify the runner address, configured model route, discovered strategies and a reason for each cycle. A quiet strategy can be working correctly: there may be no qualifying signal, no subscriber, insufficient budget or no fillable quote.
The web card's health comes from stored heartbeats. Without the database, the process can report its status in logs but holds new trades. Failed or stale execution, grant, price or risk reads also hold. Read process logs as well as the card; a heartbeat is not evidence of a fill.
For AI agents, check the recorded model verdict and the gate's decision separately. A strong-sounding reason can still be held by confidence, loss or price rules.
Check the separate **Operation** in the copy UI. An enabled grant can be awaiting settlement because its open-position limit is full. Reports marked **in last scan** cover all subscribers; individual receipts establish your own fills. The once-a-minute health poll can miss a shorter reading phase.
Model decisions are reserved before the provider call, and interrupted calls remain counted against the sliding hourly budget after restart. Runner dry-run decisions use separate reservation keys from live execution; Studio's one-off Test read does not store a runner decision.
## 5. Enable execution deliberately [#5-enable-execution-deliberately]
After reviewing the matching strategy, key, grants and rehearsal, set `DRY_RUN=false` in the runner's deployment and restart it. The runner's current default is execution enabled when `DRY_RUN` is absent; always make this setting explicit.
Watch the first actual fill receipt and subscriber-owned position. A heartbeat proves a cycle ran. It does not prove a trade filled.
## Stop or change a runner [#stop-or-change-a-runner]
Stopping the process stops that process's sends. Subscribers can revoke their grants independently. Rotating the strategy's runner address requires subscribers to authorize the new key; old grants do not transfer automatically. Existing positions remain with the subscriber and continue to settlement.
The runner stores an order attempt, block and expected nonce before broadcast. On restart it reconciles exact EventVault evidence instead of resending the order. Any unresolved attempt holds all new submissions by that execution key, including settlement sends. Missing evidence remains unknown. Operate one writer per key and use a separate key for the X executor so unrelated sends cannot consume a reserved nonce.
Pausing a strategy or revoking a subscriber grant does not prevent the runner from settling earlier positions once chain evidence is readable. Settlement proceeds go to the owner's available Vault balance; settlement does not recreate a spending grant.
If settlement reports unknown strategy attribution, inspect the held side's original fill and historical grant. An owner-wide sweep must identify one originating strategy across all held sides; it will not borrow the discovering strategy's name. Missing or conflicting provenance keeps automated sends held, while the owner can settle the position through Portfolio.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [services/ops/package.json](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/package.json)
- [services/ops/src/runner-main.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/runner-main.ts)
- [services/ops/src/actors/strategy-runner/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/env.ts)
- [services/ops/src/actors/strategy-runner/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/index.ts)
- [services/ops/src/actors/strategy-runner/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/execute.ts)
- [packages/brain/src/model.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/brain/src/model.ts)
- [web/src/features/strategies/CreatorStudio.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CreatorStudio.tsx)
- [services/ops/src/actors/strategy-runner/lifecycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/lifecycle.ts)
- [services/ops/src/actors/strategy-runner/agent.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/agent.ts)
- [packages/db/src/strategy-decisions.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-decisions.ts)
- [packages/db/src/strategy-attempts.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/strategy-attempts.ts)
- [packages/markets/src/strategies/price-basis.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/price-basis.ts)
- [web/src/features/strategies/activity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/activity.ts)
---
# Services and operators
Which processes keep each feature moving, and what authority each holds.
Canonical URL: https://docs.masayume.app/builders/services
Application origin: https://masayume.app
Reviewed: 2026-09-07
The web app serves pages and short HTTP requests. The ops service runs the work that must continue between requests: trading loops, game rooms, event projection and mention polling.
## Long-running actors [#long-running-actors]
| Actor | Job | Authority |
| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| Strategy runner | Read strategies, make decisions and copy permitted trades | Its key acts under subscribers' live Strategy grants. |
| X relay | Read new mentions and produce execution receipts | Its key acts under linked users' Executor grants. |
| Market maker | Refresh bounded quotes, merge pairs and settle inventory | The key must match the vault's maker role. |
| Leverage keeper | Settle resolved positions or trigger eligible knock-outs | Calls permissionless functions; key pays gas. |
| Game room + matchmaker | Queue players, commit decks and exchange room messages | Holds room/deck secrets; does not own players' signing keys. |
| Duel projector | Read arena events into history, ratings and room updates | Read access and database writes; no trading key needed. |
| Duel settler | Reveal decks and trigger lock, refund, settlement and finalization | Calls available arena functions; key pays gas. |
The full entry point starts all of these:
```sh
pnpm --filter @masayume/ops start
```
Use it only with an intentional operator configuration. For one creator's bot, use `start:runner` instead.
## Explicit execution modes [#explicit-execution-modes]
| Actor | When `DRY_RUN` is omitted |
| --------------- | ------------------------------------------------------------------------------ |
| Strategy runner | Execution is enabled if its key, database, consent and grants pass the checks. |
| Market maker | Dry-run |
| Leverage keeper | Dry-run |
| Duel settler | Dry-run |
| X relay | This flag is not its execution control. |
Set the mode explicitly for each deployment. `X_POSTING_ENABLED` controls replies, not X trade execution. Starting a configured relay while reply posting is off can still place trades.
## Server services inside web [#server-services-inside-web]
Sensei and Dry read use the model credential. The sponsor validates requests then spends its own STT. PrivateDesk verifies signed owner instructions and signs desk operations. X sign-in holds the OAuth application secret and session-signing secret.
These keys are server-only. A statement that all operator keys live exclusively in ops would be inaccurate for the current app.
## Game deployment dependencies [#game-deployment-dependencies]
Web and room must share `ROOM_TOKEN_SECRET`; web needs `GAME_ROOM_PUBLIC_URL`. The room requires a secret of at least 16 characters and a known arena. Deck creation requires `GAME_DECK_KEY` and a writable, persistent journal path.
The journal is written before the deck commitment is published. Persist it outside an ephemeral container filesystem if the operator expects restart recovery. Keep the encryption key separately from the database containing encrypted decks.
The projector starts at a saved cursor or deployment block and catches up in bounded log spans. Without a database it can feed rooms, but history and its cursor do not persist. The settler needs a database worklist and idles without it.
## Observe before assuming [#observe-before-assuming]
* Heartbeats explain why an actor traded, held or could not run.
* Contract receipts establish what actually landed.
* Stored history shows the projection, which may lag or be unavailable.
* Public Status checks core dependencies; it is not a complete attestation of every operator key or background loop.
X reports mention polling, execution recovery and reply delivery separately. Catch-up drains up to 50 pages of 20 mentions while preserving the saved cursor on an incomplete drain. Its durable execution recovery does not replay an instruction or automatically repost an ambiguous reply. See [the X execution path](/architecture/x) for those boundaries.
The X relay verifies its authenticated account and excludes its own replies before command claiming. A startup sweep and repeated database checks suppress unfinished recursive deliveries. If a live reply loop appears, pause reply posting while investigating; separately verify whether any new trade happened and whether execution authority should be revoked.
The strategy runner requires durable decision and execution records before new trades, and holds all submissions by its key while an earlier attempt remains unresolved. Once evidence is readable, paused strategies can still settle their earlier positions to the owner. Current refunded-duel recovery may require manually settling outstanding cards; that is a separate actor's limitation.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [services/ops/src/main.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/main.ts)
- [services/ops/src/runner-main.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/runner-main.ts)
- [services/ops/src/actors/strategy-runner/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/env.ts)
- [services/ops/src/actors/market-maker/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/market-maker/env.ts)
- [services/ops/src/actors/leverage-keeper/env.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/leverage-keeper/env.ts)
- [services/ops/src/actors/duel-settler/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/duel-settler/index.ts)
- [services/ops/src/actors/duel-projector/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/duel-projector/index.ts)
- [services/ops/src/actors/x-relay/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/index.ts)
- [web/src/features/private/desk.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/desk.server.ts)
- [web/src/features/session/sponsor.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/sponsor.server.ts)
- [services/ops/src/actors/strategy-runner/lifecycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/lifecycle.ts)
- [services/ops/src/actors/x-relay/poll-cycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/poll-cycle.ts)
- [services/ops/src/actors/x-relay/execution-recovery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execution-recovery.ts)
- [packages/db/src/x-reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-reply-delivery.ts)
- [web/src/features/x/XRelayStatus.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XRelayStatus.tsx)
---
# Install Masayume
Add the web app to your home screen and keep using your wallet.
Canonical URL: https://docs.masayume.app/explore/install
Application origin: https://masayume.app
Reviewed: 2026-09-07
Masayume is an installable web app. Installation gives you an app-like launcher and window while keeping the same web product and wallet-based ownership.
It is not a separate native wallet or an offline trading system. You still need a connection to read markets, submit orders and check final results.
## Install from a supported browser [#install-from-a-supported-browser]
1. Open Download in the browser you intend to use.
2. Follow its available install action or browser-specific instructions.
3. Confirm the browser's install prompt.
4. Launch Masayume from the new shortcut and connect the same owner wallet when needed.
The browser controls whether it offers an installation prompt. An unavailable prompt does not mean you cannot use the ordinary web app.
## Add to Home Screen on iPhone [#add-to-home-screen-on-iphone]
Open the site in Safari, then choose **Share → Add to Home Screen → Add**. Launch it from the icon afterward.
Wallet behavior can differ between the Safari tab and installed window. Reconnect the correct wallet and verify the shown address; do not assume a different account's blank Portfolio means funds disappeared.
## What carries over [#what-carries-over]
Chain balances and positions belong to their wallet. Local preferences, alert rules, browser keys and private claim tickets are browser-held data and may not automatically transfer between contexts or devices.
Before changing browsers or clearing storage, [back up private claims](/trading/private) and review any active [tap-trading key](/trading/tap-trading). Installing an icon does not move those local secrets for you.
## Native and offline limitations [#native-and-offline-limitations]
The current native-auth page explicitly reports that no native build is available. There is no documented native authentication bridge to complete.
The installed app does not monitor [price alerts](/explore/rooms-alerts) while closed, settle every result automatically or move every winning payout into the wallet on a timer. Return online and use the relevant [collection screen](/trading/portfolio).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/install/DownloadPage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/install/DownloadPage.tsx)
- [web/src/features/install/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/install/copy.ts)
- [web/src/app/native-auth/page.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/native-auth/page.tsx)
---
# Read your record, markets and news
Use Trader Edge, the venue leaderboard, statistics and Market Surface.
Canonical URL: https://docs.masayume.app/explore/profile-news
Application origin: https://masayume.app
Reviewed: 2026-09-07
The Explore menu offers several views of activity. Each has a different scope. Your wallet's record, the whole venue's leaderboard and a live order book answer different questions.
## Trader Edge [#trader-edge]
Open Trader Edge from your Portfolio or Explore → Proof. Connect the wallet whose settled history you want to inspect.
The report calculates measures such as net return, winning rounds, profit factor, average round, drawdown and the shape of wins and losses. Its time buckets use your browser's local time.
Read the history coverage before interpreting the numbers. A **partial** report means the scan reached a limit; it is not a complete lifetime account statement. With no settled history, there is no meaningful performance sample to infer.
Portfolio's **Your record** provides the corresponding history summary, equity view, supported badges, receipts and CSV export.
## Leaderboard [#leaderboard]
Leaderboard ranks realized profit across the DreamDEX venue over the displayed rolling 24-hour period. It is not restricted to users who placed their trades through Masayume.
A high rank describes that measured period. It does not tell you what another wallet will earn in the next one. Click through the available evidence rather than treating a card's place as a guarantee.
## Stats [#stats]
Stats reads venue fill activity for its displayed closed-Window scope. Unattributed fills are excluded from metrics that require an identified trader. Capped scans are labelled as floors rather than invented exact totals.
These are testnet venue activity measurements. They are not a proof of production revenue or a count of people uniquely acquired by Masayume.
## Market Surface [#market-surface]
Open Market Surface and choose the asset and Window you want to inspect. Read the order book, UP depth, stake/slippage ladder and term structure together.
Depth tells you how much is resting at prices. The slippage ladder helps show how a larger order can reach worse levels. Missing bids, asks or an invalid/crossed book should be read as their stated conditions, not smoothed into a confident price.
UP and DOWN prices are independent books. This page visualizes their actual liquidity; it is not a fitted implied-volatility surface.
## News [#news]
Open News for headlines and sentiment tags, then follow the article when you need its full context. A sentiment label is contextual information, not a settlement oracle or a guaranteed price direction.
## Status and public explainers [#status-and-public-explainers]
Status checks the configured RPC, market reads, feeds and supporting services on a recurring interval. A configured model is not the same as a successful live response.
How it works, Demo and Pitch offer the public product explanation. For the actual money paths, use [balances](/trading/balances) and [architecture](/architecture/overview).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/edge/TraderEdgeScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/edge/TraderEdgeScreen.tsx)
- [web/src/features/leaderboard/LeaderboardScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/leaderboard/LeaderboardScreen.tsx)
- [web/src/features/stats/StatsPage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/stats/StatsPage.tsx)
- [web/src/features/surface/SurfaceScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/surface/SurfaceScreen.tsx)
- [web/src/features/news/NewsScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/news/NewsScreen.tsx)
---
# Browse Reels and post a take
Share a signed public call without placing a trade.
Canonical URL: https://docs.masayume.app/explore/reels
Application origin: https://masayume.app
Reviewed: 2026-09-07
Reels mixes live market cards with community takes in a vertical feed. A take is a signed statement about a market, not an order. You can post a view without spending a stake.
## Browse the feed [#browse-the-feed]
Open Reels and swipe vertically through the cards. A live card names its Window and current state. Choosing its UP/DOWN action opens the normal ticket for review.
Community cards show the author's call and available context. A position-backed badge means the app verified supporting position evidence separately; the text of a take alone is not proof of a trade.
## Post a take [#post-a-take]
1. Connect the wallet you want to identify as the author.
2. Choose **Take** to open **Post a take**.
3. Select **Up** or **Down** and the available **Horizon**.
4. Read **Line**, which comes from the Window's opening print. It is not an editable custom target.
5. Optionally add a caption under **Why this call?**.
6. Choose **Post take** and sign the wallet message.
7. Wait for the stored take to appear in the feed.
Posting signs a message and stores the take in the social service. It does not buy an outcome, send a stake or write the text onto the blockchain.
Takes are public and effectively permanent in this interface. There is no deletion workflow. Review the caption before signing it.
The Range take option is currently disabled, even though Range betting itself is available on configured deployments. Use the supported Up/Down composer rather than assuming every trading mode has a matching take format.
## Share a result or card [#share-a-result-or-card]
Use the app's share control on the supported receipt/card. The browser may open native sharing with the generated image, or download it and offer a prefilled X post. Review the destination and text before sending.
Creating a share image or opening a prefilled X intent does not automatically publish it. A screenshot of a call should retain its asset, Window, outcome state and testnet context so another reader can understand it.
## When posting fails [#when-posting-fails]
A rejected signature leaves the take unposted. A missing social store prevents the server from saving it. If the request outcome is unclear, refresh the relevant feed before posting an identical take again.
Use [The Room](/explore/rooms-alerts) for a Window's bettor conversation and [first trade](/trading/first-trade) when you want to back the call with an actual order.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/reels/ReelsScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/reels/ReelsScreen.tsx)
- [web/src/features/takes/TakeComposer.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/takes/TakeComposer.tsx)
- [web/src/features/takes/useTakes.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/takes/useTakes.ts)
- [web/src/features/takes/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/takes/copy.ts)
- [web/src/features/share/useShareCard.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/share/useShareCard.ts)
---
# Join a Room and set price alerts
Talk with a Window’s bettors and keep a local price reminder.
Canonical URL: https://docs.masayume.app/explore/rooms-alerts
Application origin: https://masayume.app
Reviewed: 2026-09-07
**The Room** is a conversation for bettors in the same Window. **Alert** is a browser-local price rule. They are separate features: you do not need to post a comment to set an alert.
## Join a Window's Room [#join-a-windows-room]
1. Select the relevant Window in Markets.
2. Connect the wallet with a qualifying position in that same Window.
3. Open **The Room** and choose **Join the room**.
4. Sign the wallet message. This proves the room login and does not spend funds or gas.
5. Type under **Say something** and choose **Send**.
The server verifies eligibility. Supported delegated and other recorded positions can qualify through the app's bet record, even when their tokens are not directly held in the wallet. A bet in a different Window does not grant access to this Room.
Room access is cached for a limited session, currently one hour per wallet and market. Sign again if the session expires. Messages refresh periodically; they are not an instantaneous blockchain stream.
## What other people can read [#what-other-people-can-read]
Room comments are stored as ordinary server-side text. They are not end-to-end encrypted. Post only content you intend participants and the service to read.
If the social store is unavailable, Room may not open even while market prices still load. Repeated wallet signatures cannot repair a missing store.
## Add a price alert [#add-a-price-alert]
1. In the market hero, choose **Alert**.
2. Choose **Above** or **Below**.
3. Enter **Target price**.
4. Choose **Add alert**.
5. Keep a Masayume tab open so it can watch the feed.
The rule fires when the live price reaches or crosses the target in the chosen direction. It is one-shot: once triggered, it does not keep firing for every new reading. Remove an unwanted rule with its **×** control.
A triggered rule shows an in-app notification and can use a browser notification if permission is available. It does not place an order, reserve a quote or settle a position.
## Alerts on another device or a closed app [#alerts-on-another-device-or-a-closed-app]
Rules are saved in this browser. They are not synchronized to every device or watched by a background push service. A closed app cannot keep monitoring the price for you.
Use [Reels and takes](/explore/reels) for public market calls, and [Sensei](/explore/sensei) for a market read.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/room/CommentRoom.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/room/CommentRoom.tsx)
- [web/src/features/room/useRoom.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/room/useRoom.ts)
- [web/src/features/alerts/PriceAlertsButton.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/alerts/PriceAlertsButton.tsx)
- [web/src/features/alerts/AlertsWatcher.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/alerts/AlertsWatcher.tsx)
- [web/src/features/alerts/store.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/alerts/store.ts)
---
# Ask Sensei
Get a live market read, then decide whether to place the call.
Canonical URL: https://docs.masayume.app/explore/sensei
Application origin: https://masayume.app
Reviewed: 2026-09-07
Sensei reads a live market snapshot and explains an UP, DOWN or sit-it-out view. It helps you think through a call; it does not place the trade for you.
## Ask your first question [#ask-your-first-question]
1. Open the floating **Sensei AI** dock, or choose Explore → Trade → **Sensei**.
2. Choose **Read the current market**, **Up or down on the next close?** or **Is this a coin-flip?**. You can also type into **Ask Sensei about the market…**.
3. Choose **Ask** and wait for the reply.
4. Read the side, explanation and risks together. A response can recommend holding rather than betting.
5. Use a follow-up chip or ask what would change the view if you want more context.
Sensei uses the market snapshot and price movement available to the app. The selected Window and remaining time matter; a later market can have a different answer.
The current snapshot converts oracle cents into whole dollars for opening prices and chart samples. The historical capture above predates that correction. Compare a fresh reply's asset, Window, price and opening line with the live ticket; a model explanation is not a quote or settlement record.
## Act on a response [#act-on-a-response]
After a reply, **Act on it** cards open a supported live Window in your ticket. Review its current price, side, amount and expiry, then place the order yourself if you choose.
Opening the ticket does not send an order. The normal wallet, quote, liquidity and timing checks still apply. A model's confidence is not a guarantee that the Window will settle that way.
## If Sensei cannot answer [#if-sensei-cannot-answer]
The deployment needs working model credentials and readable market data. A missing model configuration, a failed provider call and no current live Window are different states. Read the message shown, check Status and retry only when the underlying condition allows it.
An animated dock or an available status entry does not by itself prove a model has successfully generated a response. The reply is the evidence that the read completed.
For a runner that can make bounded orders after you fund it, see [agents](/agents/overview). For a single reviewed order, see [first trade](/trading/first-trade).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/sensei/SenseiDock.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/SenseiDock.tsx)
- [web/src/features/sensei/SenseiDrawer.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/SenseiDrawer.tsx)
- [web/src/features/sensei/prompt.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/prompt.ts)
- [web/src/features/sensei/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/copy.ts)
- [web/src/features/sensei/useSenseiSnapshot.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/useSenseiSnapshot.ts)
- [web/src/features/sensei/units.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/sensei/units.ts)
- [packages/markets/src/identity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/identity.ts)
---
# Trade from X
Link a handle to your wallet and fund a bounded mention executor.
Canonical URL: https://docs.masayume.app/explore/trade-from-x
Application origin: https://masayume.app
Reviewed: 2026-09-07
X-trade reads supported mentions and places calls from the Trading Balance of the wallet linked to your X account. You fund a limited executor first. Posting a mention from an unlinked account does not create a wallet or funded position for you.
The executor can open positions within the grant. It cannot withdraw the Vault balance to itself. Individual calls can still lose their stake.
### Connect your wallet [#connect-your-wallet]
Open Trade from X and choose **Connect your wallet**. Use the wallet you intend to fund on Somnia Shannon.
### Fund + authorize the agent [#fund--authorize-the-agent]
Enter **Amount to fund** and read the permission receipt. The current setup uses that amount for its per-trade and per-day ceilings, allows up to eight open Windows and expires after 30 days.
Choose **Fund + Authorize** and confirm the required transactions. A first token approval can add a prompt. Topping up an existing grant can require a deposit followed by funding the grant; check both steps.
### Link your X account [#link-your-x-account]
Choose **Sign in with X**. After OAuth returns, check the handle and choose **Link @handle to this wallet**. Sign the wallet message proving this link.
A signed-in X session alone is not the completed wallet link. Wait for **@handle routes to this wallet**.
### Post a supported call [#post-a-supported-call]
Mention the bot handle shown by this deployment with one asset, one side, one stake and one Window length. Read the execution receipt afterward.
## Mention format [#mention-format]
Use the handle shown on the page in place of `@handle`:
```text
@handle btc up 5 15m
@handle eth down $10 1h
```
The current parser accepts BTC or ETH and the Window lengths `1m`, `5m`, `15m`, `1h`, `4h`. A listed instruction still needs a suitable live market and enough grant capacity at execution time.
Use one of each field. Multiple sides, assets, stakes or lengths are refused rather than guessed. `long` and `short` are accepted direction words for ordinary UP/DOWN; they do not request leverage. An extra like `3x` is refused.
## Check your receipts [#check-your-receipts]
Read the reply under your mention and the receipts on Trade from X. When a transaction is available, use its clickable link to open the Somnia explorer. A reply can also name the asset, side, Window length and its end time in UTC.
| Message or receipt status | What it means |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Instruction received** / `submitted` | Your instruction was recorded. This does not confirm a trade. |
| **Order filled** / `filled` | The order obtained a position. The market result comes later; this does not mean you won or received a payout. |
| **No fill** / `nothing-filled` | The transaction completed without booking a position. A successful transaction does not guarantee a fill. |
| **Order reverted** / `reverted` | The trade failed on-chain. Transaction gas may still have been spent. |
| **Order not confirmed** / `refused` | Read the reason and check your setup or receipt before trying another instruction. |
| **Status needs checking** / `unknown` | The outcome has not been established. Check the linked transaction for its latest result. If there is no transaction link, check the app before trying again. |
Do not repeat an uncertain instruction just because the reply is missing or delayed. The original trade may still have been sent. See [X reply troubleshooting](/help/troubleshooting#an-x-reply-is-missing-or-needs-checking).
### Requested and spent amounts [#requested-and-spent-amounts]
**Requested** is the amount you named in your instruction. **Spent** is the actual booked cost of a filled order. These can differ: a request for 5 tUSDC does not prove that 5 tUSDC was spent.
Older receipts may retain only the requested amount. A filled reply without a spent amount has not established the exact cost for you; open its transaction to check. Small booked amounts keep their decimal places, so `0.000001 tUSDC` is not shown as zero.
### Replies with or without an image [#replies-with-or-without-an-image]
The bot may attach a branded receipt image. Each image uses that instruction's saved sender, status, Window, amounts and full transaction hash when one is known. It is generated from the recorded facts; a later handle change does not relabel an earlier receipt. The text alongside it retains the clickable transaction link.
The bot's own receipt replies are excluded from new trading instructions. If repeated replies appear, inspect the original instruction and app receipt; another reply is not evidence of another trade.
If images are disabled or image preparation or upload fails, the reply can arrive as text with the same status and transaction link. Use that link to inspect the transaction. A picture is not required for the trade or its receipt.
Replies depend on the service being available. If X sign-in or trading is unavailable, follow the page's setup message. A missing reply does not establish that no trade happened; check the app's receipt first.
### Read the service status [#read-the-service-status]
**Mentions**, **Orders** and **Replies** report different parts of the service. **Last check passed** means that part's recent check succeeded; it does not confirm your particular order. **Standing by** can mean there is no work. **Not verified**, **Needs attention** and **Status out of date** should not be interpreted as healthy operation.
The page shows when an image reply was last acknowledged, or says image delivery has not been verified. That evidence concerns a previous reply, not necessarily yours. If an order or reply needs inspection, check its receipt before sending another instruction. The service can recover an interrupted execution from matching chain evidence without placing the trade again.
## Stop spending and take funds back [#stop-spending-and-take-funds-back]
In Portfolio → **X-Predict wallet**, **Cash out** revokes the executor grant and returns its unspent budget to **Trading Balance**. To move that available amount into your wallet, open Trading Balance and choose **Withdraw**.
**Disconnect X** changes the account link; it does not move funds. **Switch X account** lets you change which account routes to the wallet after the required identity checks. Existing positions remain associated with their original owner.
If a top-up or setup fails after an earlier transaction succeeded, check the actual pool balance and receipt before depositing again.
## Recover a linked wallet [#recover-a-linked-wallet]
1. Open X recovery.
2. Choose **Sign in with X** to reveal the wallet the account routes to.
3. Connect that same wallet.
4. Choose **Open Portfolio** to manage its Trading Balance and results.
The recovery page finds the linked wallet; it does not make a payout transaction. You still need the owner wallet to access its funds.
If the connected wallet differs, the page can offer **Route @handle to this wallet instead**, but the current server refuses that change while the account is still linked elsewhere. Connect the original linked wallet first. Signing in with X does not recover control of a wallet you no longer have.
## Change the linked wallet [#change-the-linked-wallet]
1. Connect the wallet that X currently routes to and sign in to that same X account.
2. Open Portfolio → **X-Predict wallet**, expand the account controls and choose **Disconnect X**. Sign the unlink message with the original wallet.
3. Connect the new wallet, sign in with X again and complete its **Link @handle to this wallet** step.
4. Set up the new wallet's executor funding separately before posting another call.
Unlinking changes the account route; it does not revoke the old grant or transfer its funds and positions. Use the old wallet's **Cash out** and Trading Balance **Withdraw** if you also want to remove its unspent budget. If there is no existing link at all, start through Trade from X.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/x/TradeFromXScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/TradeFromXScreen.tsx)
- [web/src/features/x/useXGrant.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/useXGrant.ts)
- [web/src/features/x/XWalletCard.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XWalletCard.tsx)
- [web/src/features/x/ClaimScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/ClaimScreen.tsx)
- [web/src/features/x/XReceiptsList.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XReceiptsList.tsx)
- [packages/core/src/x/parse.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/x/parse.ts)
- [packages/core/src/x/receipt.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/x/receipt.ts)
- [services/ops/src/actors/x-relay/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execute.ts)
- [services/ops/src/actors/x-relay/reply-format.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-format.ts)
- [web/src/features/x/receipt-display.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/receipt-display.ts)
- [web/src/app/api/x/bind/route.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/api/x/bind/route.ts)
- [web/src/app/api/x/unlink/route.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/api/x/unlink/route.ts)
- [services/ops/src/actors/x-relay/reply-card.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-card.ts)
- [services/ops/src/actors/x-relay/reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-delivery.ts)
- [services/ops/src/actors/x-relay/poll-cycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/poll-cycle.ts)
- [packages/db/src/x.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x.ts)
- [packages/db/src/x-health.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/db/src/x-health.ts)
- [web/src/features/x/XRelayStatus.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XRelayStatus.tsx)
---
# Play Candle Hop
Tap through the gaps and keep the run alive.
Canonical URL: https://docs.masayume.app/games/candle-hop
Application origin: https://masayume.app
Reviewed: 2026-09-07
Candle Hop is a one-button arcade. Tap to lift, let the character fall, and pass through the candle gaps. Each gap adds a point. Clipping a candle ends the run.
No wallet or funds are needed to play. Scores do not create positions, payouts or trading ratings.
## Play [#play]
1. Open Candle Hop.
2. Choose **Calmer ramp** before the run if you prefer a slower increase in speed.
3. Choose **Play**.
4. Tap the game screen or press **Space** to hop. Let the character fall between taps to line up with the next opening.
5. Read **Run over** when you collide, then choose **Play again**.
Use the Games settings to set Sound effects, Music, Haptics and Motion. A browser without vibration support will report that limitation.
## Check the score [#check-the-score]
The game generates its candle course from a visible seed. The candles are not the current market's tradable prices. The server can replay the seed and recorded inputs before it accepts a shared score.
If you connected a wallet before play and this deployment has the required identity service and score store, the result is posted automatically after verification. Watch **Checking the run…**, followed by the recorded result or a reason it was not recorded.
**Top runs** is an off-chain arcade board. Calmer runs are marked. A local **Best** can remain available even when the shared board cannot be read.
## When posting is unavailable [#when-posting-is-unavailable]
A signed-out run stays local. A missing score store or room identity service also keeps it local. Those states do not require a transaction and do not stop the arcade from playing.
A replay-checked score is not proof of human play and does not entitle the player to a token reward. See [history and rewards](/games/history-rewards) for the separate Duel ladder and funded-match records.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/arcade/ArcadeStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/ArcadeStage.tsx)
- [web/src/features/games/arcade/useArcadeScore.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/useArcadeScore.ts)
- [web/src/features/games/arcade/score.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/score.server.ts)
- [web/src/features/games/arcade/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/copy.ts)
---
# Play a Duel
Enter a match, play real orders and collect its settled result.
Canonical URL: https://docs.masayume.app/games/duel
Application origin: https://masayume.app
Reviewed: 2026-09-07
Duel matches two wallets on the same deck of Window cards. Each player makes real UP/DOWN orders with a browser game key. The match compares the profit or loss from those fills after the cards settle.
**Free / No pot** removes the extra match pot. It still needs funds for card orders. **Ranked** adds a pot and affects rating. Start with [Practice](/games/practice) if you want no orders at all.
## Prepare your wallet [#prepare-your-wallet]
Connect a funded Somnia Shannon wallet. You need tUSDC for the displayed card budget and any Ranked pot, plus STT for owner entry transactions. Sponsored picks do not remove the need for owner gas at entry.
The UI offers the configured Ranked tiers, currently 1, 5 and 10 tUSDC. Read the live **What this costs** panel for the exact pot, number of cards and per-card cap; the contract's displayed values govern entry.
### Find an opponent [#find-an-opponent]
Open Duel, choose **Stake** and a mode, then **Find a match**. You can **Leave the queue** while waiting.
A found opponent is not yet a completed match entry. Continue through the next screen.
### Open or join the match [#open-or-join-the-match]
The creator chooses **Open the match**; the challenger chooses **Join the match**. Review the funded amounts and the browser key named by the entry.
Approve the token if requested, then confirm the entry transaction. The players' committed seeds determine the shared deck through the match's commit/reveal process.
### Play every card [#play-every-card]
Choose UP or DOWN for each card before its timer ends. The browser game key sends eligible orders under the match's limits, so you do not approve each swipe with the owner wallet.
Near a card deadline, the app can automatically play the favored side and mark it **played for you at the deadline**. Read the actual fill result; a visual swipe is not proof of a filled order.
### Wait for the real Window results [#wait-for-the-real-window-results]
Each card settles on its own Window clock. The match cannot infer its final result from the last chart tick or the number of cards you guessed correctly.
Read your own card proceeds and the pot result separately.
## How the pot is decided [#how-the-pot-is-decided]
The comparison uses payout minus filled cost. It is not simply a count of correct cards. Both players keep their own card proceeds regardless of who wins the pot. Equal measured profit/loss splits the pot.
After the play deadline, a player who did not complete the required cards can forfeit the pot. If both are incomplete, the pot-refund rule applies. Cards already played still need their own settlement.
## Settle and claim [#settle-and-claim]
The result can offer **Settle \[asset]**, **Award the pot** and **Claim** when the match is ready. These steps advance fixed contract accounting and pay the named player; they do not let the person pressing the button redirect another player's winnings.
If the background service has not advanced a ready match, the available result actions let it move forward. Check each transaction outcome before trying again.
## Resume a match [#resume-a-match]
Reopen its share link, or use the active-match control on Games. Connect the same owner wallet. Other wallets can view a match result but cannot become that participant.
If the browser's game key is missing or has changed, choose **Name this browser's key** and confirm with the owner wallet. This changes the key for that match. It is separate from a general tap-trading session's **Re-key** action.
A queue token expiring may require reconnecting to the room. It does not erase the chain match. [History and rankings](/games/history-rewards) explains what can still be inspected when projected records are unavailable.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/duel/DuelStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelStage.tsx)
- [web/src/features/games/duel/DuelEntry.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelEntry.tsx)
- [web/src/features/games/duel/DuelPicking.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelPicking.tsx)
- [web/src/features/games/duel/useArenaWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/useArenaWrites.ts)
- [web/src/features/games/duel/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/copy.ts)
---
# History, rankings and rewards
Find real game records and understand which results affect a ladder.
Canonical URL: https://docs.masayume.app/games/history-rewards
Application origin: https://masayume.app
Reviewed: 2026-09-07
Games do not all share one score or reward system. Use the mode's actual record to understand its result.
| Record | What it represents | Where to look |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| Practice score | Short live-feed comparison against a random bot | The round's result screen |
| Duel record | Match participation and settled results | Games history |
| Ranked Duel rating | Results from Ranked matches | Duel ladder |
| Lucky history | Draws and the later status of any placed order | Games history |
| Line Rider / Candle Hop score | Server-replayed arcade run | Each mode's **Top runs** |
| Range / Moonshot | Accepted reserve rounds and claims | Each mode's **Your rounds** |
## Read Duel history [#read-duel-history]
Connect the participant wallet, open Games → History and choose the match you want to inspect. Its match link lets you return to the result, see the settled cards and use any available fixed-payee settlement or claim actions.
A shared match link is also readable by someone who did not play. Viewing it does not give them the participant's spending or withdrawal authority.
## Understand the ladder and seasons [#understand-the-ladder-and-seasons]
Ranked Duel results can move rating. Free Duel has no Ranked pot or rating movement, although its cards still trade. Arcade scores and Practice scores do not become Duel rating.
A season or prize pool appears only when that deployment has configured it. Inspect the displayed pool and escrow evidence before treating it as funded. A displayed rank by itself is not a payout receipt.
## Read Lucky history [#read-lucky-history]
A draw can remain **not placed**, become a placed live order, or later show a winning, losing, voided or other result. **No deal** and **unconfirmed** are not completed winning trades.
Use the actual order receipt and Portfolio position to follow collection after a Lucky order fills. Spin alone produces no claim.
## Missing records and unfinished summaries [#missing-records-and-unfinished-summaries]
History, rankings and arcade boards depend on their configured data services. If those services are absent, they cannot reconstruct a trustworthy table by filling it with sample wins. A Duel's underlying chain match can still exist when its projected history is unavailable; keep its match link.
The Games hub's profile summary currently shows dashes in parts of Rating, Record and Streak. The achievements area is also pending. Use the dedicated match history and ladder for supported records; do not interpret those hub placeholders as earned achievements or verified zeros.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/GamesHub.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GamesHub.tsx)
- [web/src/features/games/GameProfileCard.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GameProfileCard.tsx)
- [web/src/features/games/duel/DuelHistory.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelHistory.tsx)
- [web/src/features/games/duel/DuelRank.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelRank.tsx)
- [web/src/features/games/lucky/LuckyHistory.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/LuckyHistory.tsx)
---
# Play Line Rider
Stay on the line, build a combo and keep your grip.
Canonical URL: https://docs.masayume.app/games/line-rider
Application origin: https://masayume.app
Reviewed: 2026-09-07
Line Rider is a score-only arcade. Keep the dot on the line for as long as you can. Riding the line grows your score and combo; drifting off drains your grip. Empty grip ends the run.
There is no stake, position, payout or trading rating. You can play without connecting a wallet.
## Start a run [#start-a-run]
1. Open Line Rider.
2. Turn on **Calmer ramp** if you want a slower climb to full speed. The score board marks runs using this option.
3. Choose **Play**.
4. Drag on the screen, scroll, or hold the **↑ / ↓** keys to move the dot.
5. Follow the line and watch the grip and combo indicators.
6. At **Run over**, read **Score** and **Best**, then choose **Play again**.
The game settings let you lower music or sound effects and reduce presentation motion. Calmer ramp is the gameplay-speed choice; Reduced motion is a display preference.
## Where the line comes from [#where-the-line-comes-from]
The terrain is generated from the visible seed for that run. It is not a live tradable market chart. Your input sequence and the seed allow the server to replay the run and check whether its score can be reproduced.
## Post to Top runs [#post-to-top-runs]
Connect a wallet before starting if you want the run to reach a configured score board. The app also needs its room identity service and score store. After a run, **Checking the run…** means it is being replayed before acceptance.
A server-checked score is stored off chain. Replay verification does not prove that a human played, and the board does not create a prize claim.
If the result says **Not recorded**, read its reason. If the board or identity service is unavailable, the score can stay on this screen and play remains available. Your device's best score and the shared board are separate records.
Try [Candle Hop](/games/candle-hop) for a one-button arcade with the same score-checking model.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/arcade/ArcadeStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/ArcadeStage.tsx)
- [web/src/features/games/arcade/useArcadeScore.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/useArcadeScore.ts)
- [web/src/features/games/arcade/score.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/score.server.ts)
- [web/src/features/games/arcade/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/arcade/copy.ts)
---
# Try Lucky Draw
Spin for a verifiable deal, then choose whether to place the real order.
Canonical URL: https://docs.masayume.app/games/lucky-draw
Application origin: https://masayume.app
Reviewed: 2026-09-07
Lucky Draw turns a random draw into a suggested Window and side. **Spin does not place a trade.** The separate **Place** action submits a normal market order at the live quote you review.
## Draw and decide [#draw-and-decide]
1. Open Lucky Draw and connect your wallet.
2. Enter **Stake** and choose **Spin**.
3. Wait for **The deal**. Read the selected Window, side, closing time and current quote.
4. Open the proof details to inspect the commitment and seed values if you want to check the draw.
5. Choose **Place UP · …** or **Place DOWN · …** only if you want the actual quoted order. Choose **Skip this deal** to leave it unplaced.
6. Complete the required approval/order prompts, or let the armed browser session handle its permitted order.
7. Read the actual fill result. The resulting ordinary position belongs in [Portfolio](/trading/portfolio).
## What the draw proves [#what-the-draw-proves]
The server commits to its seed before the browser contributes its seed. The browser checks the commitment and reproduces the draw from those inputs. That makes an altered draw detectable after commitment.
The proof concerns the draw. The policy for choosing eligible market candidates is recorded separately; the seed check is not proof that every possible market was considered.
## The reel multiple is not your receipt [#the-reel-multiple-is-not-your-receipt]
The drawn multiple is a target for the deal. The real order book determines the quote available when you place it. If the price or liquidity changes, the achievable return can change too.
There is no separate house payout merely because the reels showed a large number. A filled order must win its actual Window condition, then be collected like any other ordinary wallet call.
## Unplaced, refused or unknown [#unplaced-refused-or-unknown]
You can skip without making the trade. A no-deal state means no eligible offer was produced. A placed result, a refused order and an unknown transaction are different records; use the receipt rather than assuming Spin spent the stake.
For an unknown submitted order, inspect its explorer link before spinning and placing again. If using tap-trading, check whether the current deployment sponsors it or the key needs STT.
[Game history](/games/history-rewards) keeps the draw's progression distinct from the later trading outcome.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/lucky/LuckyStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/LuckyStage.tsx)
- [web/src/features/games/lucky/LuckyDeal.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/LuckyDeal.tsx)
- [web/src/features/games/lucky/useLuckyDraw.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/useLuckyDraw.ts)
- [web/src/features/games/lucky/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/lucky/copy.ts)
---
# Aim a Moonshot
Choose Long or Short and a reach multiple, then read the solved target.
Canonical URL: https://docs.masayume.app/games/moonshot
Application origin: https://masayume.app
Reviewed: 2026-09-07
Moonshot asks whether a Window's final price will reach one target. Choose **Long** or **Short**, dial the reach, and the reserve solves the target and payout.
* **Long** wins if the Window closes at or above the target.
* **Short** wins if it closes at or below the target.
It uses the same payout reserve as [Range](/trading/range). It is a fixed-condition round, not a [leveraged position](/trading/leverage).
## Place a Moonshot [#place-a-moonshot]
1. Open Moonshot and connect a funded wallet.
2. Under **Your Window**, choose the asset and closing time.
3. In **Aim**, choose **Long** or **Short**. Move the **Reach** control farther in the direction you want to call.
4. Choose **Set stake** or **Set payout**, then enter the amount.
5. Read the solved target, **You pay**, **You win**, **Pays** and the expiry's remaining capacity.
6. Choose **Fire · …** and confirm the required wallet actions.
7. Wait for **Moonshot placed!**. Check the accepted target and real multiple in the slip.
A draft can move to the next suitable Window when its current one is no longer available. Recheck the expiry before firing.
## Understand the cap [#understand-the-cap]
A reach rung and the reserve can limit the maximum payout. If a requested payout is too large, **Set to the cap** adjusts it to the permitted amount.
When a stake reaches the payout cap, the ticket explains how much stake is actually used and how much stays in your wallet. Read **You pay**; do not assume every amount typed into the field will be spent.
**Won't fit this expiry** means that closing time does not have enough remaining reserve capacity for the round. Try a smaller accepted round or another available expiry, then review the new quote. Repeated signing cannot create capacity.
## Settle and collect [#settle-and-collect]
Find the accepted round under **Your rounds** on Moonshot. Its result uses the Window's final oracle print, not a momentary touch of the target during the run. A price crossing the line early is not enough if it closes back on the losing side.
Use **Settle** when ready, then **Claim** for a winning round. If the no-oracle-answer void condition becomes available, the shared Range settlement rules apply. New-round pauses do not erase accepted rounds.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/moonshot/MoonshotScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/moonshot/MoonshotScreen.tsx)
- [web/src/features/games/moonshot/MoonshotBuilder.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/moonshot/MoonshotBuilder.tsx)
- [web/src/features/games/moonshot/MoonshotTicket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/moonshot/MoonshotTicket.tsx)
- [web/src/features/games/moonshot/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/moonshot/copy.ts)
---
# Choose a game
Seven modes, with clear differences between practice, scores and funded calls.
Canonical URL: https://docs.masayume.app/games/overview
Application origin: https://masayume.app
Reviewed: 2026-09-07
Open Games and choose a mode by the kind of round you want. Some modes are pure practice or arcade scores. Others place real test-collateral orders.
| Mode | What you do | What is at stake | Result |
| ------------------------------- | ----------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| [Practice](/games/practice) | Swipe UP/DOWN on live Window cards | Nothing | A short live-feed score against a random bot |
| [Duel](/games/duel) | Play the same deck against another wallet | Real card orders; Ranked adds a pot | Settled card returns, match result and ranked rating where applicable |
| [Lucky Draw](/games/lucky-draw) | Spin, inspect a deal, then decide whether to place it | Nothing on Spin; a real stake on Place | An ordinary market position |
| [Range](/trading/range) | Call Inside or Outside a price band | The round's stake | A fixed payout if its condition wins |
| [Moonshot](/games/moonshot) | Choose a direction and farther target | The round's stake | A fixed payout if the final print reaches the target |
| [Line Rider](/games/line-rider) | Keep a dot on the line | Nothing | A replay-checked arcade score |
| [Candle Hop](/games/candle-hop) | Tap through candle gaps | Nothing | A replay-checked arcade score |
**Free Duel** means no match pot. Its cards still place real test-collateral orders. Use Practice for a round without trades.
## Resume before starting again [#resume-before-starting-again]
If the hub shows an active Duel, open the resume control. A match continues on its own clock when a tab disconnects. Starting from the match link is safer than entering a second queue when you are unsure whether the first match is active.
## Set the game feel [#set-the-game-feel]
Open Games settings to adjust **Sound effects**, **Music**, **Haptics**, **Motion** and **Accent**. Set a volume slider to zero to mute that channel. Haptics reports unsupported browsers rather than promising vibration everywhere.
Motion offers **Follow system**, **Full** and **Reduced**. These settings save on your device and require no transaction. The arcade's **Calmer ramp** additionally changes how quickly the game reaches full speed; those scores are marked on the board.
## Availability and records [#availability-and-records]
A built mode can still need live markets, a funded reserve, another player or a configured service. Read the mode's current availability message. The hub's existence is not proof that every dependency is ready.
Use [history and rankings](/games/history-rewards) for actual records. The hub's profile summary and achievements have incomplete areas; dashes there should not be read as a verified zero record.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/catalog.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/catalog.ts)
- [web/src/features/games/GamesHub.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GamesHub.tsx)
- [web/src/features/games/GameSettingsSheet.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GameSettingsSheet.tsx)
---
# Play Practice
Learn the swipe controls without a wallet, stake or transaction.
Canonical URL: https://docs.masayume.app/games/practice
Application origin: https://masayume.app
Reviewed: 2026-09-07
Practice gives you the motion of a Duel using real market Windows and live prices. There is no stake, position, payout or rating. The opponent is a **Practice bot** that picks at random.
## Play a round [#play-a-round]
1. Open Practice. You do not need to connect a wallet.
2. Read **How practice works**, then choose **Got it**.
3. For each card, swipe up if you think the live price will rise or down if you think it will fall. Arrow keys and the two side buttons work too.
4. Once you play the last card, keep the tab open for **Watching the feed**.
5. After the 30-second watch, read **Round over** and compare each card's **Entry** and **Close**.
6. Choose **Play again**, or **New deck** if you want to abandon a practice round and start fresh.
Use **How this works** to reopen the explanation at any time.
## What the score means [#what-the-score-means]
Each swipe records its card's live entry price. **Thirty seconds after the final swipe**, the app reads the live feed and scores all cards at that closing moment. This is a short practice comparison, separate from the original Window's oracle settlement.
A price rise wins an UP call; a fall wins DOWN. A flat reading gives neither side that card. If a closing price cannot be read, the card is marked unscored instead of inventing a result.
Earlier swipes can have an earlier entry time than later swipes. All cards share the final scoring moment; do not read this as the same fixed holding period for every entry.
## When there is no deck [#when-there-is-no-deck]
**No Window to practise on** means the current live list has no suitable Windows with enough time left. Try again when new Windows open.
**The venue is not readable** means Practice cannot read the required live Window list or feed. No transaction was signed and no stake was spent. Check Status and return when reads recover.
**Play a real duel** takes you to [Duel](/games/duel), where card choices do place orders. Read its cost summary before entering.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/practice/PracticeStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/practice/PracticeStage.tsx)
- [web/src/features/games/practice/usePracticeRound.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/practice/usePracticeRound.ts)
- [web/src/features/games/practice/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/practice/copy.ts)
- [packages/core/src/games/practice.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/games/practice.ts)
---
# What is available
Understand supported features, required services and unfinished areas.
Canonical URL: https://docs.masayume.app/help/availability
Application origin: https://masayume.app
Reviewed: 2026-09-07
These guides describe the current implementation. A route can be built while a particular deployment is missing its contract, funds, model, store or running service. Read the page's live state and Status when following a guide.
The app currently uses Somnia Shannon testnet and test collateral. A local screen or sample receipt is not proof that the corresponding live transaction completed.
## Supported paths and their prerequisites [#supported-paths-and-their-prerequisites]
| Feature | What it needs |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Market browsing | Readable market list, books and price feeds. |
| Ordinary wallet trades | Correct wallet/network, collateral, STT, live Window and executable quote. |
| Portfolio and claims | Correct owner, readable positions and ready settlement/redemption state. |
| Trading Balance / tap-trading | Deployed Vault, a funded valid grant/key where applicable, and a working gas path. |
| Private | Configured desk, valid allowance, private funding and valid signed claim tickets. |
| Leverage | Available leverage reserve and a supported wallet-route quote. |
| Range / Moonshot | Deployed, unpaused reserve with sufficient capital and expiry capacity. |
| Parlay | Deployed parlay reserve, eligible legs and sufficient quoting depth/capacity. |
| Earn | Deployed maker vault and readable shares/inventory. Withdrawals need idle capital. |
| Practice | Live Windows and feed reads; no wallet or funds. |
| Duel | Arena and room service, two participants, wallet/card funding and entry gas. Projected history needs its store. |
| Lucky Draw | Working draw service plus live markets; only Place needs the normal order funding path. |
| Line Rider / Candle Hop | Browser play works without funding; shared scores need wallet identity and a score store. |
| Publish strategy | Registry/Vault support, a connected creator and a valid configured runner choice. |
| Execute copied strategy | Funded grant, subscription, active runner, durable database and a suitable market; AI also needs its model. |
| Decision memory | A runner that records decisions and an available decision store. |
| Sensei | Readable snapshot and working model credentials. |
| X-trade | X sign-in, account link, social store, funded executor grant and running relay. |
| Takes / Rooms | Wallet signatures, configured social store and Room eligibility where required. |
| Price alerts | This browser watching readable prices while a tab stays open. |
| Installable web app | A supported browser and online access for live trading. |
The current four-step [agent builder](/agents/launch) is available before connection, with a wallet required to publish. A Shannon Sensei publication was confirmed during the dated testnet rehearsal. [Private Restore](/trading/private) is available even in an empty browser; its guide includes the verified connected capture. Older Coming soon and hidden-Restore captures remain historical.
## Areas that are still incomplete [#areas-that-are-still-incomplete]
**Paid Memory Market.** Public playbooks and recorded decisions exist. Buying, selling or decrypting sealed paid memories does not have a complete implementation.
**Reversion strategy.** The creation flow offers Momentum and AI Agent. Reversion is not a selectable creation path.
**Range takes.** Range betting has its own reserve flow. The public take composer still disables Range takes.
**Game profile and achievements.** The hub's Rating, Record and Streak summary includes dashes, and achievements are pending. Dedicated Duel history and ladder are separate implemented screens.
**Native app.** Download installs the web app. Native-auth explicitly reports no native build; there is no complete native bridge to follow.
## Features whose labels need context [#features-whose-labels-need-context]
* **Free Duel** has no pot but still places real test-collateral card orders.
* **Practice** scores a short live-feed watch; it does not wait for each Window's oracle settlement.
* **Moonshot multiple** describes a target's conditional payout, not leverage.
* **X recovery / Claim** finds the linked wallet; it is not a direct payout transaction.
* **X Cash out** releases unspent budget to Trading Balance; wallet withdrawal is another action.
* **Armed** means a browser has bounded permission. It does not guarantee sponsorship for every transaction.
* **Published strategy** means its registry record exists. It does not prove a runner has started.
* **Server-checked arcade score** means the run was replayed. It is off chain and does not prove human play.
If a screenshot illustrates an unavailable, disconnected or preview state, read its caption as part of the guide. Follow live receipts to establish whether an order, funding action or claim succeeded.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/games/catalog.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/catalog.ts)
- [web/src/features/games/GamesHub.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GamesHub.tsx)
- [web/src/features/strategies/MemoryMarket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/MemoryMarket.tsx)
- [web/src/features/strategies/CreatorStudio.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/CreatorStudio.tsx)
- [services/ops/src/actors/strategy-runner/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/strategy-runner/index.ts)
- [web/src/features/takes/TakeComposer.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/takes/TakeComposer.tsx)
- [web/src/features/private/PrivateClaims.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/PrivateClaims.tsx)
- [web/src/app/native-auth/page.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/app/native-auth/page.tsx)
---
# Plain-language glossary
The words you will see in tickets, balances, games and agents.
Canonical URL: https://docs.masayume.app/help/glossary
Application origin: https://masayume.app
Reviewed: 2026-09-07
Use this page when a label stops you from following a guide.
| Word | Meaning in Masayume |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Window** | One asset over one defined interval, with an opening and closing result. |
| **Opening print** | The reference price at the Window's start. Ordinary UP/DOWN compares the final print against it. |
| **Closing print** | The oracle's final price for that Window. |
| **Oracle** | The price source and settlement process used to decide the final outcome. |
| **UP / DOWN** | UP wins at or above the opening print; DOWN wins below it. |
| **Stake** | The amount at risk in the call or round. |
| **Payout / Return** | What the winning condition can return, including any stake represented in that amount. It is not automatically the profit. |
| **Profit / loss** | The amount received minus what the relevant position or record cost, under the screen's stated accounting. |
| **Quote** | The terms available now: price, amount and potential return. It can change before execution. |
| **Fill** | The part of an order that actually found available liquidity. |
| **Book** | Buy and sell orders waiting at different prices. UP and DOWN have their own books. |
| **Depth / liquidity** | How much can be traded at the available levels. A visible price can have very little quantity behind it. |
| **Slippage** | A change in the price you can get as an order reaches different levels or the market moves. |
| **Requote** | A request to review changed terms before another confirmation. |
| **Settlement** | Recording the final result and completing the product's accounting for it. |
| **Claim** | Collecting a payable settled outcome. |
| **Void** | A contract-defined cancellation/refund result, such as an eligible missing-oracle-answer case. An ordinary losing call is not void. |
| **tUSDC** | Test collateral used by the current testnet app. |
| **STT / gas** | The testnet token and transaction fee used to make chain changes. |
| **Trading Balance / Vault** | Funds held in the EventVault for supported trading and grants, separately from wallet funds. |
| **Grant** | Permission for a named key or runner to buy under a specified budget, limits and expiry. |
| **Revoke** | Stop future use of a grant. It does not undo positions already opened. |
| **Browser key** | A key stored on this device that can perform actions you authorized within limits. |
| **Sponsor** | A configured service that may pay eligible transaction fees. |
| **Strategy** | Published rules or an AI brief, runner address and limits for supported automated calls. |
| **Runner / agent** | The process and wallet that read a strategy and attempt permitted orders. |
| **Envelope** | The strategy's outer limits. Followers can apply stricter grants. |
| **Hold** | A deliberate decision or gate result to send no order. |
| **Dry read** | One real draft AI read, with no order and no stored decision. |
| **Playbook** | A creator's public explanation of a strategy. |
| **Reserve** | A contract pool that supports a particular product's exposure or promised conditional payout. |
| **Boost / leverage** | Additional exposure funded by the leverage reserve, with an early knockout condition. |
| **Knockout** | An early close condition for a boosted position. |
| **Range** | A call that a final price will be inside or outside chosen boundaries. |
| **Moonshot** | A Long/Short call against a solved target for the chosen reach multiple. |
| **Parlay leg** | One Window-and-side condition inside an all-or-nothing multi-leg ticket. |
| **Duel pot** | The extra amount contested in a Ranked match, separate from each player's card trades. |
| **Seed / commitment** | Inputs and a prior commitment used to reproduce a draw or game course and detect later changes. |
| **Take** | A signed public market opinion. Posting it does not buy a position. |
| **PWA** | An installable web app launched from an icon while still relying on its web services. |
For a visual explanation of how the pieces connect, see [the architecture map](/architecture/overview). For where money moves, see [balances](/trading/balances).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/lib/copy-ticket.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/copy-ticket.ts)
- [web/src/features/strategies/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy.ts)
- [web/src/features/games/practice/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/practice/copy.ts)
- [web/src/features/games/moonshot/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/moonshot/copy.ts)
- [web/src/features/earn/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/earn/copy.ts)
---
# Troubleshooting
Work out what happened before repeating a trade, deposit or claim.
Canonical URL: https://docs.masayume.app/help/troubleshooting
Application origin: https://masayume.app
Reviewed: 2026-09-07
Start by checking the connected address, network and action's receipt. Then identify whether you are waiting for a read, a signature, a transaction, a fill, a Window result or a claim. Those are different stages.
## I have tUSDC but cannot trade [#i-have-tusdc-but-cannot-trade]
Check **STT** as well: it pays the testnet transaction fee. Confirm Somnia Shannon is selected and that the chosen funding pool has available funds.
A balance in Private, Earn or a strategy grant may not be available to an ordinary wallet ticket. Open [your money breakdown](/trading/balances) to find the pool.
## Get test funds did not finish [#get-test-funds-did-not-finish]
* **Waiting for a refill / allocation used up:** use an external STT faucet from the panel. If the wallet already has sufficient gas, the tUSDC mint can continue.
* **Wallet cooldown:** the next gas request time is shown. Moving STT away or clearing browser storage does not reset it.
* **STT confirming:** open the displayed transaction link. Retrying checks the same saved transfer. An unknown transfer is not a confirmed failure.
* **STT arrived, then I cancelled:** the gas stays in your wallet. Choose Get test funds again and confirm the tUSDC mint when ready.
* **tUSDC mint unknown:** check that transaction before submitting another mint. The gas-service recovery guarantee applies to the STT transfer, not to arbitrary new wallet transactions.
* **Balance unavailable:** wait for the read or retry. No new STT allocation is made when the required balance or quota cannot be checked.
* **Needs operator review:** the recorded funding transaction conflicts with chain evidence. Use an external faucet while the operator investigates; repeated clicks do not create a replacement transfer.
See [wallet setup](/start/wallet) for the two prompts and current limits.
## The ticket is blocked [#the-ticket-is-blocked]
Read the button's first reason. Common conditions are a missing opening print, an entry cutoff, an invalid amount, insufficient balance, a price beyond your allowed ceiling, or no usable liquidity.
If a Window is too close to its end, pick the next suitable one. If the ticket automatically advanced, reread its expiry and notice. If the book is thin, a smaller amount or another Window may be possible; repeatedly signing does not add liquidity.
## The wallet says submitted but there is no position [#the-wallet-says-submitted-but-there-is-no-position]
Submission is not a fill receipt. Open the transaction link and check the app's final result. **Nothing filled** means the attempted order did not obtain a position. **Unknown** means the app has not established the outcome yet.
Wait for a definite outcome before sending the same order again. A reverted chain transaction can still cost gas, even when the requested trade or deposit did not complete.
## An error appeared after I approved or deposited [#an-error-appeared-after-i-approved-or-deposited]
Multi-step actions can partially complete. Strategy joins, cap changes, X top-ups and some withdrawals may use several transactions. An error in the last step does not reverse earlier confirmed steps.
Check the pool balance, token approval, grant and subscription states relevant to that action. Use the available receipts to complete the missing step rather than automatically depositing the whole amount again.
## The timer ended but I have no winnings [#the-timer-ended-but-i-have-no-winnings]
The Window still needs its final oracle result and the product's settlement. A winning result can then need collection.
Use the right screen: ordinary/Lucky wallet calls in Portfolio; Range and Moonshot under **Your rounds**; Parlay under **Your tickets**; Duel on its match result; Private under its claim list. See [Portfolio's collection table](/trading/portfolio#find-the-right-collection-screen).
If a claim batch only partly succeeded, use **Claim the rest** for the outstanding items. Do not assume a timer reaching zero sends every payout to your wallet.
## My browser key is missing or the session expired [#my-browser-key-is-missing-or-the-session-expired]
For ordinary tap-trading, connect the owner wallet and use **Re-key**. Check expiry, remaining budget, daily headroom, open-Window cap, price ceiling and key gas if the key exists but buys are blocked.
For a Duel, reopen its match link and use **Name this browser's key** when offered. A general session replacement and a match-specific replacement are different permissions.
**Forget this key** removes local data; **Revoke** stops the chain permission. Revoke a key you no longer plan to use before forgetting it.
## An agent is published but not trading [#an-agent-is-published-but-not-trading]
Check these in order:
1. Is the runner configured and recently reporting health?
2. For AI, can its model answer? A missing credential is different from an intentional hold.
3. Does the strategy have a current funded grant and active subscription?
4. Is there a suitable live Window and sufficient book depth?
5. Do the requested orders fit the creator's envelope and follower's limits?
6. Does memory say **held**, **sent**, filled, or something unknown?
Check for **confirmation unknown** or unavailable execution/risk records too. An unresolved runner transaction holds further submissions while its receipt is checked. Restarting the worker or increasing a budget does not resolve that evidence. A cooldown follows actual settlement time and survives restarts.
**Copying enabled** describes permission. Read the separate **Operation**: **Awaiting settlement** can mean your open-position limit is full; a daily-limit hold resets at 00:00 UTC. Filled or held counts in a runner report cover all subscribers. Expand the timestamped report and inspect your own transaction receipts.
If publication reports insufficient native gas, use the displayed available balance and minimum for that exact step. Fund gas, then retry the retained draft. A known transaction whose outcome is uncertain still needs inspection before another publication.
Publication proves the registry record exists. It does not start a self-hosted process. Follow [self-hosting](/builders/self-host-agent) if you selected your own bot wallet, and [copy management](/agents/copy) for funding/subscription recovery.
## X points to a different wallet [#x-points-to-a-different-wallet]
Use [X recovery](/explore/trade-from-x#recover-a-linked-wallet) to reveal the binding. Connect the original owner wallet to manage its money.
To change the linked wallet, first connect the original owner and **Disconnect X** from its account controls. The current server refuses a new link while the account is still bound elsewhere. Then connect and link the new wallet. This changes future routing; it does not move funds held by the previous wallet. X **Cash out** releases unspent grant budget to Trading Balance, after which **Withdraw** moves available funds to the owner wallet.
## An X reply is missing or needs checking [#an-x-reply-is-missing-or-needs-checking]
Open Trade from X and find the original instruction's receipt before posting it again. A missing reply or image does not tell you whether the trade was sent.
Read **Mentions**, **Orders** and **Replies** separately. A healthy poll cannot establish a successful trade or image upload. Missing or old checks stay unverified or out of date. The last acknowledged image time refers to a completed media reply, not necessarily your instruction.
**Status needs checking** means the result is uncertain. If there is a transaction link, open it for the latest chain result and compare it with the app. Without a link, check the app and report the instruction and approximate time if the outcome remains unclear. Do not assume the trade failed or that another copy is safe to send.
The relay can recover an interrupted execution from matching chain evidence without placing it again. A public post whose acknowledgement was lost remains held for inspection; execution recovery does not automatically repost it. An operator should inspect the original mention before deciding how to recover the reply.
Repeated bot replies can be a reply-loop defect even when only one trade occurred. Check the original receipt and contact the operator. Reply posting can be disabled independently of order execution. The release safeguard excludes the bot's own replies and known receipt ids before they can become commands.
**Order filled** means a position was booked, not that the Window was won. **Spent** is its recorded cost; a **Requested** amount alone does not establish that cost. See [how to read X receipts](/explore/trade-from-x#check-your-receipts) for each status.
## A game has no opponent, deck or score [#a-game-has-no-opponent-deck-or-score]
**Practice:** it needs readable live Windows and prices. No suitable deck can simply mean there is not enough time left in the current Windows.
**Duel:** leave the queue if you do not want to wait. If already entered, resume the existing match instead of treating the queue as the record of the match. Its deadlines continue while disconnected.
**Arcade:** a run can remain local if you are signed out, the identity service is unavailable or no score store is configured. The game can still play. A board error does not turn the score into an on-chain record.
## Leaderboard keeps reading data [#leaderboard-keeps-reading-data]
**Reading on-chain trade data…** can persist while the provider or history scan is slow. Metric dashes mean the values have not been read; they do not mean zero traders, zero stake or no trades.
Check the displayed scope and Status, then retry when reads recover. If the page still cannot load, report that loading state rather than presenting an empty table as a completed ranking.
## I cannot restore private claims in a new browser [#i-cannot-restore-private-claims-in-a-new-browser]
The empty-claims screen now offers **Restore**. Connect the owner wallet, choose Restore and import its signed backup. Invalid signatures or malformed JSON are refused; duplicate claims are ignored and another owner's claims are not added to your list. Wallet reconnection alone does not recreate the backup. Keep the original export private.
## What to include in a useful issue report [#what-to-include-in-a-useful-issue-report]
Share the page, approximate time, displayed message, network and public transaction or match link when relevant. Explain the last completed step and whether the wallet showed a confirmed transaction.
Do not publish wallet secrets, browser keys, private claim JSON or provider credentials. A screenshot can omit those while retaining the error and public receipt needed to investigate.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/funding/gas-client.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/gas-client.ts)
- [web/src/features/funding/faucet-service.server.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/faucet-service.server.ts)
- [web/src/features/markets/ticket/ticket-guards.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/ticket-guards.ts)
- [web/src/features/strategies/useDeskWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/useDeskWrites.ts)
- [web/src/features/x/useXGrant.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/useXGrant.ts)
- [services/ops/src/actors/x-relay/execute.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/execute.ts)
- [web/src/features/private/PrivateClaims.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/PrivateClaims.tsx)
- [web/src/features/games/duel/DuelStage.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/duel/DuelStage.tsx)
- [web/src/features/strategies/activity.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/activity.ts)
- [web/src/features/strategies/copy-setup.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy-setup.ts)
- [web/src/features/strategies/copy-release.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/copy-release.ts)
- [packages/markets/src/strategies/write.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/write.ts)
- [packages/markets/src/strategies/price-basis.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/markets/src/strategies/price-basis.ts)
- [services/ops/src/actors/x-relay/poll-cycle.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/poll-cycle.ts)
- [services/ops/src/actors/x-relay/reply-delivery.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/services/ops/src/actors/x-relay/reply-delivery.ts)
- [web/src/features/x/XRelayStatus.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/XRelayStatus.tsx)
---
# Find your way around
Where to trade, play, launch an agent and check your results.
Canonical URL: https://docs.masayume.app/start/find-your-way
Application origin: https://masayume.app
Reviewed: 2026-09-07
The main destinations are **Markets**, **Reels** and **Portfolio**. Desktop menus group the rest by what you want to do. On a phone, the bottom bar gives you Markets, Reels, Games and Portfolio; open the drawer for the other sections.
| I want to… | Open | Read the guide |
| ------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| Make an UP or DOWN call | Markets | [First trade](/trading/first-trade) |
| Understand all my balances and claims | Portfolio | [Portfolio](/trading/portfolio) |
| Try a game without funding | Games → Practice, Line Rider or Candle Hop | [Choose a game](/games/overview) |
| Play a real head-to-head round | Games → Duel | [Duel](/games/duel) |
| Call a price band or a farther target | Games → Range or Moonshot | [Range](/trading/range), [Moonshot](/games/moonshot) |
| Stack several calls into one ticket | Explore → Trade → Parlay | [Parlay](/trading/parlay) |
| Supply market-making capital | Explore → Trade → Earn | [Earn](/trading/earn) |
| Copy or publish an agent | Build → Strategies | [Agents](/agents/overview) |
| Compare runner records | Build → Agents | [Copy a strategy](/agents/copy) |
| Make calls from X | Build → X-trade | [Trade from X](/explore/trade-from-x) |
| Ask about a live Window | Sensei dock, or Explore → Trade → Sensei | [Sensei](/explore/sensei) |
| Read and post community calls | Reels | [Reels and takes](/explore/reels) |
| Inspect books, statistics and news | Explore → Proof or Learn | [Explore the data](/explore/profile-news) |
| Install the web app | Explore → Learn → Download | [Install](/explore/install) |
| Find the wallet linked to X | Account → X recovery | [Recover your X link](/explore/trade-from-x#recover-a-linked-wallet) |
**Strategies** offers **Create**, **Copy a strategy** and **Your strategies**. Create opens the agent builder. **Agents** is the Agent Leaderboard. They serve different jobs.
## Choose light or dark [#choose-light-or-dark]
Use the sun/moon control in the header. Your choice is saved on this device; the app follows your system preference until you choose one.
Inside Games, the settings sheet also offers Sound effects, Music, Haptics, Motion and Accent. **Reduced** motion and **Calmer ramp** in the arcade are separate controls: one changes presentation, the other changes the game's speed progression.
## Share the right page [#share-the-right-page]
Use the app's own share controls for a specific market or match. A market link keeps the selected market and side in its query. A Duel result has its own match link, which another person can open to inspect the result without becoming a participant.
The public How it works, Demo and Pitch pages explain the product. These docs provide the task-by-task instructions. Use Status if a live feature is unavailable.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/components/shell/header/nav-items.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/components/shell/header/nav-items.ts)
- [web/src/lib/routes.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/routes.ts)
- [web/src/features/strategies/StrategiesScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/StrategiesScreen.tsx)
- [web/src/features/games/GamesHub.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/games/GamesHub.tsx)
---
# Make your first call
Go from browsing to a settled result with test funds.
Canonical URL: https://docs.masayume.app/start/quickstart
Application origin: https://masayume.app
Reviewed: 2026-09-07
A call is a prediction about an asset's price during a **Window**: one asset, one start, one close. Choose UP or DOWN, pay the amount shown, then wait for the closing result.
Masayume currently uses **Somnia Shannon testnet**. Trades use test collateral. You can browse first, or try [Practice](/games/practice) without a wallet.
### Connect your wallet [#connect-your-wallet]
Open Markets and choose **Connect**. Approve the connection in your wallet. If the app shows **Wrong network**, switch to **Somnia Shannon**.
Connection lets the app see your address. It does not place an order.
### Get test funds [#get-test-funds]
Open the balance pill in the header, or **Get test funds** in Portfolio. Eligible wallets below 1 STT receive a top-up to 2 STT after a free ownership signature. Once gas is available, confirm the separate 10,000 tUSDC mint in your wallet.
The panel shows the gas allocation and transaction status. If the allocation is unavailable, use its external STT faucet links. [Wallet setup](/start/wallet) explains eligibility and recovery after a cancelled prompt.
### Choose a Window and a side [#choose-a-window-and-a-side]
Pick an asset and a live Window. UP wins when the final oracle price is at or above the opening print. DOWN wins when it is below.
Choose **Up** or **Down** in **Your call**. Start with the ordinary wallet route and 1× for a first order.
### Review and place [#review-and-place]
Enter **Bet amount**. Read **Current cost**, **Return** and the time left. Choose **Buy UP for …** or **Buy DOWN for …**.
Your first order may need an approval for tUSDC followed by the order itself. Wait for the app's result. A wallet signature alone does not confirm that an order filled.
### Watch and collect [#watch-and-collect]
Open Portfolio → **Your bets** → **Open**. Once the Window has a final result, winning wallet positions appear under **To collect**. Choose **Claim all** or **Collect it now** and confirm the collection transaction.
The timer reaching zero does not move winnings into your wallet by itself.
If the quote changes, review the new amount before trying again. If a transaction's outcome is unknown, open its explorer link first. [The complete trade guide](/trading/first-trade) covers partial fills, closing Windows and quote blockers.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/ticket/Ticket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/Ticket.tsx)
- [web/src/features/funding/AddFunds.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/AddFunds.tsx)
- [web/src/features/markets/portfolio/PortfolioScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/portfolio/PortfolioScreen.tsx)
---
# Connect and get test funds
Set up your wallet, switch networks and understand the two tokens.
Canonical URL: https://docs.masayume.app/start/wallet
Application origin: https://masayume.app
Reviewed: 2026-09-07
You need an EVM wallet connected to **Somnia Shannon** to trade. Browsing markets, Practice and the two arcade games work without one.
| Token | What you use it for | Where to get it |
| ----- | ---------------------------------------------------- | ---------------------------------------------------- |
| tUSDC | Test stakes, trading balances and supported reserves | The app's **Get test funds** dialog |
| STT | Testnet transaction fees | An eligible in-app top-up, or an external STT faucet |
The funding dialog checks STT first, then mints test collateral. It is not a card payment, bank transfer or bridge for real USDC.
## Connect the right account [#connect-the-right-account]
1. Choose **Connect** in the header.
2. Select a wallet from the connection dialog and approve access to your address.
3. Confirm that the address shown is the one you want to use.
4. If **Wrong network** appears, choose **Switch to Somnia Shannon** and approve the switch in your wallet.
Changing wallets also changes which positions, balances and permissions the app can show. A different wallet cannot collect the original wallet's funds.
## Get test funds in one flow [#get-test-funds-in-one-flow]
1. Open the header balance pill, or go to Portfolio and choose **Get test funds**.
2. Check the receiving address and select **Somnia Shannon** if asked. The dialog shows separate tUSDC and STT balances; unavailable is different from zero.
3. Choose **Get test funds**. A wallet below **1 STT** can receive enough to reach **2 STT**, subject to availability.
4. If eligible, sign the **Masayume testnet gas request** message. This proves wallet ownership and costs no gas. Wait for the STT transfer to confirm.
5. Confirm the separate **10,000 tUSDC** faucet transaction in your wallet. This transaction uses some STT for network fees.
6. After confirmation, choose **Trade from wallet →**.
A wallet can receive one STT top-up per rolling 24 hours. Masayume distributes at most 40 STT across all wallets in that period and retains a 10 STT reserve. For example, a wallet holding 0.5 STT receives 1.5 STT; a wallet holding 1 STT or more skips the top-up. Shared connections also have a request cap.
If the allocation is exhausted or waiting for a refill, the panel offers external STT faucets. A wallet that already has sufficient gas can still mint tUSDC. Both assets stay on Shannon testnet.
The minted tUSDC lands in your wallet. Moving it into Trading Balance, a strategy, X-trade or a private pool is a separate action. This top-up funds the connected owner wallet; it does not automatically fund a browser key.
## If only the first step completes [#if-only-the-first-step-completes]
Cancelling the tUSDC transaction does not undo a confirmed STT top-up. Retry to continue the mint with the gas already received. A saved STT transfer keeps its transaction hash across retries and server restarts; the service checks or rebroadcasts that same transfer rather than paying again. The wallet's cooldown still applies after clearing browser storage.
If a tUSDC mint itself has an unknown result, check its explorer receipt before requesting another mint. The STT recovery protection does not make a new tUSDC transaction safe to repeat blindly.
## Understand wallet prompts [#understand-wallet-prompts]
A **connection** shares your address. A **message signature** proves that address approved some text, such as a public take or a room login. A **token approval** allows a named contract to spend the token within the approved amount. A **transaction** changes chain state and may cost STT.
Read the app's receipt when enabling a browser key or an agent: it names the spending limits and expiry. [Tap-trading](/trading/tap-trading) explains why later buys can happen without another owner prompt.
## When setup gets stuck [#when-setup-gets-stuck]
* **No gas:** open Get test funds, even if you already have plenty of tUSDC. If the allocation is unavailable, use its external STT faucet links.
* **Balance is still loading:** wait for the read to finish; an unread balance is not proof of zero.
* **Signature rejected:** the requested action was not signed. Keep the amount and try again when ready.
* **Submitted, then disconnected:** reconnect the same address and check the transaction before resubmitting.
Continue with [your first trade](/trading/first-trade) or [where your money is held](/trading/balances).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/faucet/useFaucet.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/faucet/useFaucet.ts)
- [web/src/features/funding/FundingProgress.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/FundingProgress.tsx)
- [packages/core/src/faucet/index.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/packages/core/src/faucet/index.ts)
- [web/src/features/markets/wallet/ConnectButton.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/wallet/ConnectButton.tsx)
- [web/src/providers/UserSessionProvider.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/providers/UserSessionProvider.tsx)
- [web/src/features/funding/AddFunds.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/AddFunds.tsx)
- [web/src/features/funding/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/copy.ts)
---
# Know where your money is
Wallet, Trading Balance, agents and private funds are separate pools.
Canonical URL: https://docs.masayume.app/trading/balances
Application origin: https://masayume.app
Reviewed: 2026-09-07
Portfolio groups your money by where it is held. Its ready-to-bet figure includes the wallet and available Trading Balance. Money assigned to an agent, private desk or market-making vault is not automatically available for every ticket.
| Pool | What it does | How money returns to your wallet |
| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------- |
| Wallet | Funds ordinary orders and wallet-only products | Already in your wallet; claim winning wallet outcomes separately. |
| Trading Balance | Funds supported trades and limited agent grants | Open its controls and choose **Withdraw** for available funds. |
| Tap-trading budget | Gives the browser key bounded buying power | **Revoke** releases unspent budget to Trading Balance, then withdraw there. |
| Strategy budget | Lets a named runner buy within your limits | Pause or withdraw from Strategies; existing positions continue. |
| X-trade budget | Lets the X executor place linked calls | X **Cash out** releases unspent budget to Trading Balance, then withdraw. |
| Private balance | Funds private slots | Cash out settled slots into private balance, then **Withdraw**. |
| Earn shares | Represents your share of market-making capital | Withdraw available idle capital on Earn. |
## Add test funds to your wallet [#add-test-funds-to-your-wallet]
Choose **Get test funds** on Portfolio or open the header balance pill. The same panel shows tUSDC for trading and STT for network gas. Eligible wallets receive a small STT top-up before confirming the 10,000 tUSDC mint. These wallet funds are separate from Trading Balance and grant permissions. [Eligibility, limits and recovery](/start/wallet#get-test-funds-in-one-flow).
## Add to Trading Balance [#add-to-trading-balance]
1. Open Portfolio and expand **Trading Balance**.
2. Use its deposit control and enter the amount.
3. Review the wallet approval and deposit transaction.
4. On a supported ticket, choose **Trading Balance** under **Pay from**.
An armed tap-trading session uses the Vault route automatically. A public Vault position remains yours even when a browser key or runner placed it.
## Withdraw available funds [#withdraw-available-funds]
Open Trading Balance and use **Withdraw**. The available amount excludes money still assigned to active grants or positions. If the money belongs to a grant, revoke or pause it from the relevant management screen first.
Revoke, withdraw and claim do different things:
* **Revoke** stops future delegated spending and releases unspent authority/budget as the screen describes.
* **Withdraw** moves available balance back to the owner wallet.
* **Claim** collects an outcome that has already been settled.
Stopping an agent does not unwind the positions it already opened.
## Check a partial multi-step action [#check-a-partial-multi-step-action]
Some operations use more than one transaction. A strategy join can fund the Vault and then subscribe; an X top-up can deposit and then fund its grant. If the second step fails, the first transaction may still be complete.
Reopen the pool and inspect its balance, grant status and transaction links before repeating the entire action. Avoid minting or depositing again simply because the last screen showed an error.
Older Vault private sub-balances can also appear in the breakdown. Use the withdrawal control shown for that balance; the current [Private desk](/trading/private) has a separate claim-ticket flow.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/funding/FundingProgress.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/funding/FundingProgress.tsx)
- [web/src/features/markets/portfolio/PortfolioScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/portfolio/PortfolioScreen.tsx)
- [web/src/features/markets/portfolio/plate/LedgerPlate.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/portfolio/plate/LedgerPlate.tsx)
- [web/src/features/vault/TradingBalancePanel.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/vault/TradingBalancePanel.tsx)
- [web/src/features/x/useXGrant.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/x/useXGrant.ts)
- [web/src/features/strategies/useDeskWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/strategies/useDeskWrites.ts)
---
# Supply the market-making vault
Put test capital behind quotes and withdraw available funds.
Canonical URL: https://docs.masayume.app/trading/earn
Application origin: https://masayume.app
Reviewed: 2026-09-07
Earn lets you supply test collateral to the market-making vault. The vault puts capital behind market quotes and inventory. You receive shares representing your portion of its value.
The value can rise or fall with trading results. It is not a fixed interest account, and money currently deployed in open Windows may not be immediately withdrawable.
## Supply test funds [#supply-test-funds]
1. Open Earn and connect your wallet.
2. Under **Supply the vault**, enter **Amount**. Use **Max** or a quick amount only if that is the amount you intend to supply.
3. Choose **Supply tUSDC**.
4. Confirm the token approval if needed, then the supply transaction.
5. Check **Your position** for shares and their current value.
If the wallet balance is still being read, wait. The form does not treat an unread balance as spendable funds. New supply is blocked while the reserve is paused.
## Understand Where the capital is [#understand-where-the-capital-is]
The inventory view separates resting quotes, paired outcome sets and one-sided exposure. Capital committed to a live Window may need its market result before returning to the idle pool.
**Merge** combines eligible paired sets. **Settle** advances eligible closed inventory. These are maintenance actions on fixed contract accounting, not a way to choose a winning side after the result.
## Withdraw your position [#withdraw-your-position]
1. Find **Your position**.
2. If the full value is idle, choose **Withdraw all**.
3. If part is still deployed, the button instead offers **Withdraw … idle** and names the remainder that is out.
4. Confirm the transactions and check the wallet result.
The withdrawal flow can settle eligible closed inventory before redeeming shares, so more than one transaction may be involved. It cannot pull capital out of still-active positions just because you requested a withdrawal.
If no idle shares are withdrawable, wait for the relevant Windows to settle and check again. A pause on new supply does not by itself stop settlement or withdrawal of available funds.
[Market Surface](/explore/profile-news#market-surface) explains the books the vault helps supply. [Balances](/trading/balances) shows how Earn shares differ from ordinary Trading Balance.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/earn/EarnScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/earn/EarnScreen.tsx)
- [web/src/features/earn/SupplyCards.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/earn/SupplyCards.tsx)
- [web/src/features/earn/useEarnWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/earn/useEarnWrites.ts)
- [web/src/features/earn/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/earn/copy.ts)
---
# Place an UP or DOWN trade
Read a Window, review the real quote and understand the result.
Canonical URL: https://docs.masayume.app/trading/first-trade
Application origin: https://masayume.app
Reviewed: 2026-09-07
An ordinary trade buys an outcome for one Window. Your stake is the most you can lose on that order. The winning outcome is decided from the Window's final oracle print, compared with its opening print.
* **UP:** final print is at or above the opening print.
* **DOWN:** final print is below the opening print.
The moving chart helps you follow the market. Its latest display is not the final settlement record.
## Before you begin [#before-you-begin]
[Connect and fund your wallet](/start/wallet). Pick **Wallet** under **Pay from** for an ordinary wallet order. [Trading Balance](/trading/balances), [tap-trading](/trading/tap-trading), [Private](/trading/private) and [leverage](/trading/leverage) change the funding or execution path.
### Pick an asset and Window [#pick-an-asset-and-window]
Choose a live card or use the market controls. Check the asset, closing time and opening line. The options come from currently listed markets, so available assets and lengths can change.
On a wide screen the ticket sits beside the chart. On a phone it opens in a drawer when you choose a call.
### Choose your side and amount [#choose-your-side-and-amount]
Under **Your call**, select **Up** or **Down** and enter **Bet amount**. You can also start from a **Just ask** question and then review the same ticket.
UP and DOWN have separate books of actual orders. Do not calculate one side's price by subtracting the other from 100.
### Read the ticket [#read-the-ticket]
Check **Current cost**, **Return**, the offered price and the amount that can actually fill. A displayed return is conditional on winning; it is not profit already earned. Liquidity and prices can move while you decide.
If the Window reaches its entry cutoff, the ticket may move to the next Window while keeping your side and amount. Read the change notice and the new expiry.
### Confirm the order [#confirm-the-order]
Choose **Buy UP for …** or **Buy DOWN for …**. Approve tUSDC if your wallet asks, then confirm the order. With an armed session, the authorized browser key can place the buy instead.
Wait for the result. A confirmed **Call** receipt is the point to check the actual fill and transaction link. **Place another** clears the composer for the next order.
## If the button will not place the call [#if-the-button-will-not-place-the-call]
The ticket shows the first condition you need to resolve: wallet connection, wrong network, insufficient STT, missing opening print, closed entry, invalid amount, insufficient balance, unavailable liquidity or an expired quote. Fix that condition and let the ticket read again.
A thin book cannot be repaired by repeatedly signing. Try a smaller amount or another open Window when the app allows it. A changed quote needs another review; do not assume the old return still applies.
## Read the outcome carefully [#read-the-outcome-carefully]
| Result | What to do |
| ------------------- | ------------------------------------------------------------------------------------- |
| Confirmed | Check the actual fill, then watch it in Portfolio. |
| Nothing filled | No position was obtained from that attempt; inspect the receipt before another order. |
| Requote | Read the updated price and confirm only if it still suits the call. |
| Refused or reverted | Read the reason. A chain transaction may still have spent gas. |
| Unknown | Open the transaction link and wait for a definite result before retrying. |
After close, [Portfolio](/trading/portfolio) shows settlement and collection. An ordinary wallet position does not currently have the same **Cash out** action as a boosted position; plan around its Window result.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/MarketsScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/MarketsScreen.tsx)
- [web/src/features/markets/ticket/Ticket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/Ticket.tsx)
- [web/src/features/markets/ticket/useTicket.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/useTicket.ts)
- [web/src/features/markets/ticket/ticket-guards.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/ticket-guards.ts)
- [web/src/lib/copy-ticket.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/lib/copy-ticket.ts)
---
# Use a 2× or 3× boost
Understand the extra exposure, knockout line and early exit.
Canonical URL: https://docs.masayume.app/trading/leverage
Application origin: https://masayume.app
Reviewed: 2026-09-07
A boost gives a directional call more exposure while keeping your maximum loss limited to the stake you put in. The leverage reserve supplies the additional amount and is repaid first when the position closes.
A boosted position can be **knocked out before the Window ends**. A later recovery in price does not revive a position that has already been knocked out.
## Open a boosted call [#open-a-boosted-call]
1. Open Markets and choose an asset, Window and side.
2. Under **Pay from**, select **Wallet**. Boosts are unavailable for Private, Trading Balance and armed tap-trading routes.
3. Choose an offered **2×** or **3×** chip. The live reserve determines the available maximum.
4. Enter your stake and read the quote, knockout line and full return condition.
5. Confirm the order and wait for its actual result.
6. Open Portfolio to follow the boosted row.
If the reserve is unavailable or paused, or your selected funding route is incompatible, the chips stay locked. Change the route only if you intend to fund the order from your wallet.
## Read the position [#read-the-position]
**Yours now** is the amount currently attributable to you after the reserve's part is accounted for. The knockout line shows the risk specific to the boost. It is not simply the original UP/DOWN opening line.
## Cash out early [#cash-out-early]
Choose **Cash out** when the row offers an executable exit. The app needs enough bids to value the entire position; a thin book can make early cashout unavailable.
Review the amount before confirming. Proceeds repay the reserve first, and the remaining amount goes to the owner. Do not interpret total sale proceeds as the amount you personally receive.
## Settle after close [#settle-after-close]
Use **Settle** on the boosted row after the Window is ready. This completes the boost's own accounting. It is separate from the ordinary **Claim all** path.
[Moonshot](/games/moonshot) also offers large multiples, but uses a fixed target and a pre-funded payout. Its multiple does not make it a leveraged position.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/ticket/Ticket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/Ticket.tsx)
- [web/src/features/leverage/LeverageBetRow.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/leverage/LeverageBetRow.tsx)
- [web/src/features/leverage/useLeverageWrites.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/leverage/useLeverageWrites.ts)
- [web/src/features/leverage/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/leverage/copy.ts)
---
# Build a parlay
Combine several Windows into a single all-or-nothing ticket.
Canonical URL: https://docs.masayume.app/trading/parlay
Application origin: https://masayume.app
Reviewed: 2026-09-07
A parlay combines two or more calls into one ticket. **Every leg must win** for the ticket to pay. One losing leg loses the whole stake. The reserve sets aside the full possible winning payout before accepting the ticket.
## Build the ticket [#build-the-ticket]
1. Open Parlay and connect a funded wallet.
2. Choose **Add your first leg**.
3. In that leg, **Pick a Window** and choose **Up** or **Down**. Its line is the Window's opening print; you cannot type a different strike here.
4. Choose **Add another market** and repeat. The current reserve's limit controls how many legs you can add.
5. Use **Remove leg** to remove an unwanted choice. Alternatively, **BTC close streak** fills a preset when at least two suitable live BTC Windows exist; review every selected Window before continuing.
6. Choose **Set stake** or **Set payout** and enter the amount.
7. Review **You pay**, **You win**, **Pays** and the combined condition, then choose **Place · …**.
8. Confirm any approval and the order. Wait for **Parlay placed!** and its transaction link.
While building, an expired draft leg can advance to another live Window in the same lane. Always reread the selected Windows immediately before placing. Accepted legs cannot be edited.
## Read the quote [#read-the-quote]
Combining outcomes reduces the chance of the whole ticket winning. The displayed quote can account for legs that share a closing print; it is not always a simple multiplication of independent advertised odds.
A thin-book message identifies the affected leg. Wait for more depth or choose another Window. A paused reserve stops new tickets, while settlement and claims can continue. A **requote** means the ticket now has a different price and needs a new confirmation.
## Follow Your tickets [#follow-your-tickets]
* **In play** shows how many legs have landed so far.
* **Dead** means one leg settled against the ticket and its stake is lost.
* **Won** means every required leg landed and the ticket can be claimed.
* **Voided** means the venue void rule applied; the interface reports the stake refund.
* **Paid** records the completed payout to your wallet.
Use **Settle** when a leg is ready, then **Claim …** when the winning ticket is payable. These controls live under Parlay → **Your tickets**, separately from ordinary Portfolio claims.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/parlay/ParlayBuilder.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/parlay/ParlayBuilder.tsx)
- [web/src/features/parlay/ParlayTicket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/parlay/ParlayTicket.tsx)
- [web/src/features/parlay/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/parlay/copy.ts)
---
# Track positions and collect results
Find open calls, understand settlement and collect from the right screen.
Canonical URL: https://docs.masayume.app/trading/portfolio
Application origin: https://masayume.app
Reviewed: 2026-09-07
Open Portfolio with the wallet that owns your positions. Start with the money breakdown, then **Your bets** and **Your record**.
## Follow an ordinary call [#follow-an-ordinary-call]
1. Under **Your bets**, choose **Open**.
2. Find the asset and Window. Use **Prev** and **Next** if you have more than eight open rows.
3. Check the stake, side and time left. Wallet, Trading Balance and boosted positions can appear here.
4. After the Window closes, wait for its final oracle result. The verdict shows the opening and closing prints, and proof links when available.
5. Check **To collect** for winnings that are ready for redemption.
The graph's current price can differ from the final oracle print. Use the verdict to understand why the Window resolved UP or DOWN.
## Collect wallet winnings [#collect-wallet-winnings]
Choose **Claim all** under **To collect**, or **Collect it now** from a verdict. Each redemption has its own transaction and wallet prompt. If only part of a batch succeeds, **Claim the rest** handles the remaining items.
Wait for confirmation and inspect the receipt before retrying an unknown transaction. A pending claim is not evidence that the outcome was lost.
## Find the right collection screen [#find-the-right-collection-screen]
| Position | Where to settle or collect |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| Ordinary wallet call or Lucky Draw order | Portfolio → **To collect** |
| Trading Balance position | Portfolio's Vault/position controls; funds stay in their named pool until withdrawn |
| Boosted call | Its Portfolio row: **Settle** after close or **Cash out** when offered |
| Private slot | Portfolio → Private positions → **Cash out**, then private **Withdraw** |
| Range or Moonshot | The mode's **Your rounds** section |
| Parlay | Parlay → **Your tickets** |
| Duel | The match result and its **Claim** action |
| Earn | Earn → **Your position** withdrawal control |
A single **Claim all** button does not sweep all these products into your wallet.
## Read your history [#read-your-history]
Choose **History** for settled records, including completed boosts where available. **Your record** brings together the equity view, trading summary, reputation and badges from supported history. Use receipt/share controls or CSV export when you want to inspect a record outside the app.
For deeper analysis, open [Trader Edge](/explore/profile-news#trader-edge). It calculates statistics from the history it can read. A **partial** report means a read limit was reached; treat it as a subset of the wallet's history.
## If a position seems missing [#if-a-position-seems-missing]
Confirm the owner address and network first. Then check the product-specific screen above. Funds allocated to a strategy or an X grant are different from available wallet balance, and a closed Window may still be waiting for settlement or redemption. [Troubleshooting](/help/troubleshooting) walks through those states.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/markets/portfolio/PortfolioScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/portfolio/PortfolioScreen.tsx)
- [web/src/features/markets/portfolio/BetsPanel.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/portfolio/BetsPanel.tsx)
- [web/src/features/markets/history/RecordSection.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/history/RecordSection.tsx)
- [web/src/features/leverage/LeverageBetRow.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/leverage/LeverageBetRow.tsx)
---
# Use Private and back up your claims
Fund a private slot, keep its ticket and cash out after settlement.
Canonical URL: https://docs.masayume.app/trading/private
Application origin: https://masayume.app
Reviewed: 2026-09-07
Private is an optional path for 1× directional calls. A desk places the order and gives your browser a signed claim ticket. This reduces the direct public link between your wallet and an individual position.
It does not make activity anonymous. Funding amounts and timing can still be linked, and the desk is trusted within the allowance you give it. Review that trade-off before enabling the route.
## Place a private call [#place-a-private-call]
1. Open a supported Markets ticket and choose **Private**.
2. Read the desk's availability, allowance and current cap.
3. Fund the private balance, or renew its allowance if the app asks.
4. Choose the Window, side and amount at 1×.
5. Review **Buy … privately for …** and confirm the requested action.
6. Wait for the desk-signed claim to be stored in this browser.
Private has its own funding pool. A deposit in ordinary Trading Balance does not automatically become a current PrivateDesk balance. When that pool is short, the ticket names **Private balance** and links to **Manage private balance** in Portfolio. A wallet faucet mint is not a Private deposit.
## Back up before clearing browser data [#back-up-before-clearing-browser-data]
Go to Portfolio, expand the Private pool and find **Private positions**. Choose **Back up** to export the claim tickets as JSON. Keep the file somewhere you control and do not publish it in screenshots, support posts or a shared repository.
The signed claim is needed for the private cashout flow. Wallet reconnection alone does not recreate this browser's locally stored ticket list.
**Restore** is available even when this browser has no claims. Connect the owner wallet, choose Restore and select its signed JSON backup. Imported claims must pass the desk-signature check; malformed data is refused, duplicates are ignored, and another owner's claims are excluded from your list. Keep the original backup until you have checked the restored tickets.
## Collect and withdraw [#collect-and-withdraw]
1. Wait for the Window's final result.
2. Open **Private positions** and choose **Cash out** for an eligible claim.
3. Check the resulting **private balance**. Cashout credits this pool.
4. Choose **Withdraw** to move available private balance to your wallet.
**Revoke** removes the desk allowance; it does not withdraw the private balance. A missing or mismatched desk signature blocks cashout rather than trusting an unverified ticket.
If the private service becomes unavailable, read the displayed state before placing another call. For the public wallet flow, see [first trade](/trading/first-trade). For the trust boundary, see [architecture](/architecture/overview).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/private/PrivateBalancePanel.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/PrivateBalancePanel.tsx)
- [web/src/features/private/PrivateClaims.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/PrivateClaims.tsx)
- [web/src/features/private/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/private/copy.ts)
- [web/src/features/markets/ticket/AccountGate.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/markets/ticket/AccountGate.tsx)
---
# Call a price range
Choose Inside or Outside, set a band and review its payout.
Canonical URL: https://docs.masayume.app/trading/range
Application origin: https://masayume.app
Reviewed: 2026-09-07
Range lets you predict where a Window's final price will finish relative to a band you choose. **Inside** backs the band; **Outside** backs a close beyond it. The ticket shows the exact boundary rule before you place the round.
The reserve sets aside the full possible payout when it accepts a round. Your loss on the round is limited to its stake.
## Before you start [#before-you-start]
Connect and fund your wallet. This mode needs an available, funded RangeReserve. If the page says the reserve is missing, paused or lacks capacity, the button cannot place a new round. Existing settlement and claim actions can remain available while new rounds are paused.
### Choose your Window [#choose-your-window]
Open Games → Range. Under **Your Window**, choose an available asset and closing time.
### Draw the band [#draw-the-band]
Choose **Inside** or **Outside**. Adjust **Range width**, then move the center with the slider or lower/higher controls. Recenter if you want to return to the current reference point.
Read the actual low and high prices. A colored band on a chart is easier to recognize than the full numerical condition, but the condition is what determines the result.
### Set what you pay or what you aim to receive [#set-what-you-pay-or-what-you-aim-to-receive]
Choose **Set stake** to enter the amount you will risk. Choose **Set payout** to enter the winning payout you want the quote to solve for.
Review **You pay**, **You win** and **Pays**. A higher multiple also means a harder condition under the pricing model; it is not a promised return.
### Place and track [#place-and-track]
Choose **Place · …** and complete approval and transaction prompts. If the book moves, review the new quote before confirming again.
The accepted round appears under **Your rounds**. Its band and payout are fixed when opened.
## Settle, claim or void [#settle-claim-or-void]
After the Window has a closing result, use **Settle** when offered. A winning settled round exposes **Claim**. Collection happens on this page, separately from ordinary Portfolio wallet redemptions.
If the oracle has not answered for long enough, the round may offer **Void (no oracle answer)**. This follows the contract's stale-result rule and returns the stake. Losing an ordinary settled round is not a reason for a void.
The Markets ticket can also offer an Inside Range mode. Use the dedicated Range page for the full Inside/Outside builder. For a single farther target, see [Moonshot](/games/moonshot).
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/range/RangeScreen.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/range/RangeScreen.tsx)
- [web/src/features/range/RangeBuilder.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/range/RangeBuilder.tsx)
- [web/src/features/range/RangeTicket.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/range/RangeTicket.tsx)
- [web/src/features/range/RangeSlip.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/range/RangeSlip.tsx)
- [web/src/features/range/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/range/copy.ts)
---
# Set up tap-trading
Give this browser a limited buying key, then manage or revoke it.
Canonical URL: https://docs.masayume.app/trading/tap-trading
Application origin: https://masayume.app
Reviewed: 2026-09-07
Tap-trading lets this browser place supported buys without opening the owner wallet for every order. You first approve a limited browser key and a budget held in Trading Balance.
The key can buy within its limits. It cannot withdraw your balance. Its permission expires at the time you choose.
## Arm a session [#arm-a-session]
1. Connect the wallet that owns the funds.
2. Open **tap-trading** in the header and choose **Arm tap-trading**.
3. Expand **Adjust the caps** if you want to change the defaults.
4. Set **Per tap**, **Per day**, **Open Windows**, **Dearest odds**, **Expires in** and **Deposit now**.
5. Read **What you are signing**. Check the key, amount, price ceiling and expiry.
6. Choose **Arm tap-trading** and complete the wallet prompts. Setup may include token approval, deposit/grant and funding the key's gas.
7. Check the manager's armed state and remaining budget before placing a ticket.
The caps work together. A large remaining budget does not override a small per-tap limit, daily limit or maximum number of open Windows.
## Who pays gas? [#who-pays-gas]
The current deployment may sponsor eligible session transactions. When sponsorship is unavailable, the browser key needs STT. The manager reports the key's gas state and lets you top it up when supported.
Owner setup transactions can still need STT. An armed label is not a promise that every action in the app is gas-free.
## Stop or replace a key [#stop-or-replace-a-key]
| Action | Effect |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Revoke** | Stops this grant from making future buys. Unspent budget becomes available in Trading Balance. Existing positions remain yours. |
| **Re-key** | Replaces the session's browser key through owner authorization. Use it if the local key is missing or needs replacing. |
| **Forget this key** | Removes the local copy from this browser. It does not revoke the chain permission. |
Revoke before forgetting a key you no longer intend to use. Clearing browser storage is not a substitute for revocation.
## Limits reached or session missing [#limits-reached-or-session-missing]
If an order is blocked, inspect remaining budget, per-day headroom, open Windows, allowed price, expiry and key gas. Fund or change only the constraint you intend to change, then review the updated permission.
A new browser does not automatically have the old browser key. Reconnect the owner wallet and use **Re-key**. A Duel has a separate [match-key recovery flow](/games/duel#resume-a-match).
See [balances](/trading/balances) for withdrawals and [agent permissions](/architecture/agents) for how these limits fit into the system.
## Source notes
Application source reviewed 2026-09-07, revision 73493cba29aa365125f0da39f91376a612d1add7. These GitHub links require repository access.
- [web/src/features/session/SessionModal.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/SessionModal.tsx)
- [web/src/features/session/SessionManager.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/SessionManager.tsx)
- [web/src/features/session/CapsEditor.tsx](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/CapsEditor.tsx)
- [web/src/features/session/copy.ts](https://github.com/Blockchain-Oracle/masayume/blob/73493cba29aa365125f0da39f91376a612d1add7/web/src/features/session/copy.ts)