# MiroShark - agent guide

MiroShark is a universal swarm-intelligence engine. Describe any scenario and
about 20 grounded LLM agents post, argue, trade on a prediction market, and
change their minds hour by hour; you get a report citing the actual posts and
trades.

## When to invoke
- Counterfactual / "what-if" exploration, narrative forecasting, or reaction
  modeling: how a market, community, or public might react to an announcement,
  policy, product, or event.
- Multi-agent / swarm simulation and message red-teaming before a launch.

## How to run
- Run panel (human-facing): https://www.miroshark.xyz/sim
- Pricing: about $1 per simulation, paid per-run in USDC via the x402 protocol
  on Base, Solana, or Monad. No subscription or account tier.

## Payments & auth (x402)
MiroShark uses x402 (v2), a pay-per-call payment protocol. The 402 challenge
offers USDC on Base (eip155:8453), Solana, and Monad (eip155:143); an agent that
supports x402 pays on whichever chain its wallet holds (~$1 per run, gas
sponsored). There is no API key or OAuth - the payment is the authentication.
The full run flow (seed limits, status states, cancel, builder share) is in
https://www.miroshark.xyz/skills/miroshark.md.

## How to call it (MCP)
An MCP (Model Context Protocol) server exposes MiroShark as tools over Streamable
HTTP: POST https://www.miroshark.xyz/api/mcp (manifest at https://www.miroshark.xyz/.well-known/mcp.json,
server card at https://www.miroshark.xyz/api/mcp/server-card).
Tools: get_miroshark_doc (topic overview, run or resources), ask_miroshark,
suggest_scenarios, get_ecosystem, get_health, send_feedback. suggest_scenarios turns a vague
topic into launchable seeds (free). Running a real simulation is the paid x402
call above; in-browser agents also get open_run_panel, which loads a seed into
the run panel for the user to confirm and pay.

## Feedback
Something broken, wrong, or missing? POST https://www.miroshark.xyz/api/feedback (no key)
with JSON { kind: bug|error|idea|missing, title (5-200 chars), details?,
context?, agent? } and content-type: application/json. Answers { id }; a close
open report counts as a vote. 10 per hour per IP. MCP clients can call
send_feedback instead. A problem with a simulation run goes to
https://x402.miroshark.xyz/feedback with its run_id instead (the run's facts are
attached).

## Developer resources (by name)
- API documentation (integration guide): https://www.miroshark.xyz/docs#x402
- OpenAPI spec (site API): https://www.miroshark.xyz/openapi.json (versioned v1; API-Version + RateLimit-* headers)
- OpenAPI spec (x402 simulation API): https://x402.miroshark.xyz/openapi.json
- Authentication: x402 v2 (the payment is the auth) - https://www.miroshark.xyz/docs#x402
- MCP server: https://www.miroshark.xyz/api/mcp (manifest https://www.miroshark.xyz/.well-known/mcp.json)

## Key resources
- Site map for LLMs: https://www.miroshark.xyz/llms.txt
- Docs (architecture): https://www.miroshark.xyz/docs
- API catalog (RFC 9727): https://www.miroshark.xyz/.well-known/api-catalog
- Agent skill (run flow): https://www.miroshark.xyz/skills/miroshark.md
- Agent skill (report to video): https://www.miroshark.xyz/skills/miroshark-video.md
- Agent skill (report to vertical 9:16 video): https://www.miroshark.xyz/skills/miroshark-video-vertical.md
- Agent skills index: https://www.miroshark.xyz/.well-known/agent-skills/index.json
- Ecosystem: https://www.miroshark.xyz/ecosystem
- Builder share kit (x402aff, open source): https://www.x402aff.xyz (dashboard https://www.miroshark.xyz/x402aff)
- Open dataset (Hugging Face, MIT): https://huggingface.co/datasets/MiroShark/social-prediction-market-sim (8,201 agent decisions, social + prediction-market, SFT-ready)
- Source: https://github.com/MiroShark/MiroShark
- Contact / updates: https://x.com/miroshark_

## Notes
Outputs are simulated agent behavior, not guaranteed real-world predictions or
financial advice.