@yosuku/mcp

Yosuku's BTC prediction market as agent tools — for Claude Code, Codex, and any MCP client.

Give an LLM live, read access to DeepBook Predict on Sui: which BTC markets are open right now, the exact Pyth spot they settle on, whether a market has settled, and recent price history. No key, no signing, no custody surface — every tool is a public on-chain read.

This targets the current 6-24 venue (predict pkg 0xdb3ef5a5…). It replaces the older @yosuku/deepbook-predict-mcp, which was built for a retired venue.

Install

Claude Code

claude mcp add yosuku -- npx -y @yosuku/mcp

.mcp.json (Claude Code / Cursor / Claude Desktop)

{
  "mcpServers": {
    "yosuku": { "command": "npx", "args": ["-y", "@yosuku/mcp"] }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.yosuku]
command = "npx"
args = ["-y", "@yosuku/mcp"]

Read tools (no key)

| Tool | What it does | |---|---| | list_markets | Live BTC markets: id, expiry, cadence (1m/5m/1h), minutes left, strike grid, max leverage. Start here. | | get_spot | Current BTC spot from the exact Pyth feed these markets settle on. | | market_state | Read one market by id; after expiry it carries the settlement price. | | price_history | Recent Pyth observations, newest first (~1/sec), for momentum/context. | | vault_status | A user's deposited balance and the limits they set on-chain (agent, max margin, max leverage). |

Safe trading (the part every other prediction-market MCP gets wrong)

Most trading MCPs put a private key that controls the whole wallet inside the server and enforce limits in a config file. A bug, a prompt injection, or a leaked key drains the wallet.

Yosuku is different by construction. The agent key can only call one function, agent_mint_for, on a delegated vault, and the Move contract asserts on every trade:

• the caller is the user's subscribed agent,
• leverage ≤ the user's cap, cost ≤ the user's per-trade margin,
• the user's ledger covers it,

and there is no funds-out path for the agent (withdrawals pay the user only). A leaked agent key can, at worst, place in-cap bets. It can never move a cent off the vault. The limits are enforced by the chain, not by an .env.

| Tool | Signs? | What it does | |---|---|---| | vault_open_position | yes (agent) | Open a position for a subscribed user, within their on-chain caps. simulateOnly validates + shows the cap outcome without executing. Returns a plain-English reason when the contract refuses. |

Enable it by setting the agent key:

"env": {
  "PREDICT_AGENT_KEY": "suiprivkey1...",
  "YOSUKU_VAULT_ID": "0x…",
  "YOSUKU_VAULT_WRAPPER": "0x…"
}

With no key, vault_open_position refuses to trade and the server runs read-only. Opting in (deposit + set caps) and withdrawing are always user-signed in the user's own wallet — the MCP can't do them.

Memory (MemWal / Walrus)

So an agent keeps its trade lessons across sessions. Memories are SEAL-encrypted blobs on Walrus, keyed to a Sui account, retrieved by semantic recall through MemWal's hosted relayer.

| Tool | What it does | |---|---| | memory_remember | Persist one trade lesson to durable memory; waits until written. | | memory_recall | Recall past memories by meaning (semantic top-K). | | memory_health | Relayer + Walrus liveness, and whether memory is configured. |

Enable it by pointing at a MemWal creds file:

"env": { "MEMWAL_CREDS": "/Users/you/.yosuku/memory.json" }

With MEMWAL_CREDS unset, the memory tools are simply disabled and nothing else is affected. MemWal is an early hosted service, expect occasional maintenance windows.

Testnet only today. MIT.