App API reference

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

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

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 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

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

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

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.

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

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

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 before integrating this trust model.

Duel discovery, room identity and history

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

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

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

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.