MiroShark's docs are unusually agent-forward — llms.txt, agents.md, two OpenAPI specs, an MCP manifest, and a served /skill.md — but the flagship integration page at /docs is a July snapshot that now contradicts the live API, the newer skill.md, and even the OpenAPI contract on chain support, seed validation limits, response fields, and endpoint availability.
1. /docs says "Two chains, one endpoint" — the live 402 challenge, skill.md, and OpenAPI all list three (critical)
Problem: The integration guide states "The same POST /run accepts USDC on either Base or Solana. The 402 challenge advertises both as separate accepts[] entries," and its decoded PAYMENT-REQUIRED reference shows exactly two accepts[] entries with the caption "Two entries - Base (EVM) and Solana - both $1 USDC." The live 402 challenge from POST https://x402.miroshark.xyz/run returns three entries — Base, Solana, and Monad (eip155:143, USDC 0x754704Bc..., payTo 0x0000CE08...). skill.md says "Base or Solana or Monad," the OpenAPI x-guidance says "Base (eip155:8453), Solana (solana mainnet), or Monad (eip155:143)," and the blog announced the Monad expansion in September 2026.
Consequence: This is the wire-format reference developers are told to hand-roll payments against. A client that validates the challenge against the documented two-entry shape (or hardcodes "pick one of two") breaks or mis-parses when the third entry arrives; a Monad-funded wallet reading /docs concludes it cannot pay at all. In an irreversible-payment protocol with "no chargebacks - ever," stale payment docs are the most expensive kind of stale.
The fix: Update the "Two chains" section and the section-19 wire reference to the live three-entry challenge (or generate that block from the live 402 response at build time so it can never drift again).
2. Three different minimum seed lengths across /docs, the OpenAPI schema, and the OpenAPI's own guidance (critical)
Problem: /docs documents {"prompt": "<scenario or question, 4–4000 chars>"} and {"article": "<raw document text, 4–200000 chars>"}. The OpenAPI request schema sets and . skill.md agrees with the schema ("string, 6-4000 chars" / "string, 400-200000 chars"). Worse, the OpenAPI file contradicts itself: its says while its schema in the same document says minLength 6. For , the /docs floor (4 chars) is off from the real floor (400 chars) by two orders of magnitude.
{"prompt": "<scenario or question, 4-4000 chars>"}
article
Consequence: The x402 API validates the seed before settlement, so a 5-char prompt or 300-char article built per /docs is rejected with 400 invalid_input. Agents are explicitly steered to x-guidance for function-calling — and it carries the wrong number too, so even the "machine contract" disagrees with itself. Contradictions like this fail silently for LLM integrators: they pick one value and never see the other.
The fix: Make the OpenAPI schema the single source of truth (6/400), fix x-guidance inside the same file, and correct the two ranges on /docs.
3. The /docs response and status reference omits cancel_token, /cancel, and three documented run states (significant)
Problem: The /docs 202 example shows run_id, wait_url, status_url, payer, payment_chain — no cancel_token. skill.md shows the live 202 includes "cancel_token": "q3V9...kZ0" and warns "Keep cancel_token private: it is the only way to cancel the run… it is shown only in this response." /docs never mentions POST /cancel/{run_id} (which is in the OpenAPI paths), and its status enum — "queued | running | completed | failed | budget_exceeded | cancelled" — omits the interrupted, resuming, and rejected states skill.md documents. /docs also says a failed run means "Contact the operator with your run_id for a manual review," while skill.md says the status payload now carries a structured data.refund object {eligible, contact, mailto, note}.
Consequence: A developer integrating from /docs alone discards the only credential that can cancel a paid, in-flight run (it's shown once, and the server stores only a hash), can't stop a wrong $1 run, and may hard-fail on interrupted/resuming statuses their state machine doesn't know — statuses that skill.md says just mean "keep polling."
The fix: Add cancel_token to the 202 example with the keep-it-private warning, document /cancel/{run_id} and the full nine-state status enum on /docs, and mention data.refund.
4. /docs shows an /api/ecosystem.json response shape that the live endpoint doesn't return (significant)
Problem: /docs documents the response as { "success": true, "data": { "schema_version": "1", "count": 14, "ecosystem": [ { "name": …, "category": …, "x_handle": …, "repo": … } ] } }. The live endpoint returns a different envelope and different keys: {"source":"https://github.com/MiroShark/MiroShark/blob/main/ECOSYSTEM.md","count":12,"projects":[{"name":"AntFleet","logo":…,"alt":…,"links":[…]}]} — no success wrapper, no schema_version, projects instead of ecosystem, and per-entry fields (logo, alt, links) that don't match the documented category/x_handle/repo.
Consequence: This is pitched as the machine-readable registry "integrators and registries crawl." Any crawler coded against the documented shape gets undefined for every field it reads. Since the docs even brag about a "drift-guard test" keeping catalog surfaces in lockstep, the shipped example being wrong undermines trust in every other JSON example on the page.
The fix: Replace the example with the actual live response (or point the docs example at whichever deployment actually serves the documented shape, and label the difference between the marketing-site endpoint and the self-hosted engine's endpoint).
5. Endpoints on /docs have no host — and on both public hosts they 404 or demand an API key the docs say doesn't exist (significant)
Problem: The docs page describes dozens of GET surfaces with bare paths and no base URL — "GET /api/surfaces.json is a self-describing catalog of all 37 published surfaces on a deployment," "/api/stats aggregates consensus distribution… across every public completed sim." Probed live: https://www.miroshark.xyz/api/surfaces.json and /api/stats return 404 {"code":"not_found"}; https://x402.miroshark.xyz/api/surfaces.json and /api/stats return 401 {"error":"invalid or missing X-API-Key"} — on a platform whose docs, llms.txt, and agents.md repeatedly state "There is no API key or OAuth - the payment is the auth." Nothing on the page says these paths only exist on a self-hosted engine instance (localhost:3000).
Consequence: An integrator reading "an integrator answers 'what can this host do?' with one call" tries the call on the only hosts they know and gets a 404 or an authentication scheme documented nowhere. The undisclosed X-API-Key gate directly contradicts the platform's headline auth story.
The fix: State the base URL for every endpoint on /docs — explicitly separating self-hosted engine surfaces (localhost:3000/…) from the hosted x402 API — and document the X-API-Key-gated admin surfaces or hide them from public error responses.
6. llms.txt and agents.md still describe payment as "on Base" only (significant)
Location:https://www.miroshark.xyz/llms.txt ("Payment is pay-per-run through the x402 protocol on Base"; "About $1 per simulation, paid per-run via the x402 protocol on Base") and https://www.miroshark.xyz/agents.md ("MiroShark uses x402 (v2), a pay-per-call payment protocol, on Base")
Problem: Both machine-readable agent surfaces state Base-only payment, with no mention of Solana or Monad. The live 402 challenge, skill.md, the OpenAPI spec, and the September-updated blog all say three chains.
Consequence: These files exist precisely so agents don't have to render the site. An agent with a Solana- or Monad-funded wallet that reads llms.txt/agents.md — the intended entry points — concludes it can't pay and moves on. The most autonomous consumers get the most outdated payment facts.
The fix: Update the payment lines in llms.txt, index.md, and agents.md to "on Base, Solana, or Monad" (and consider generating these files from the same source as the 402 challenge).
7. Builder-code attribution: /docs documents only the client extension; skill.md documents an X-Builder-Code header (minor)
Problem: /docs shows exactly one mechanism: client.registerExtension(new BuilderCodeClientExtension("bc_yourcode")) on the x402 client. skill.md says "Name a Base Builder Code on the request (an X-Builder-Code header) to earn your builder share." Neither surface mentions the other's mechanism or says whether both work, or which wins when they disagree.
Consequence: A builder integrating for the 10% revenue share picks one page and doesn't know the other path exists; if their client library doesn't support extensions they may believe attribution is impossible, when a plain header would do. Money-adjacent ambiguity generates support tickets.
The fix: Document both attribution paths in both places, and state precedence when a header and a payment-embedded code conflict.
8. Site /docs says "six slots"; the repo CONFIGURATION.md it defers to says "Four independent slots" (minor)
Problem: The site docs headline "MiroShark splits work across six independent model slots" (LLM / Smart / Wonderwall / NER / Embedding / Reranker), and in the same section say "One key, five slots… pasted into the five API-key env vars." The repo's configuration reference — which /docs itself designates as "the source of truth" — presents "Four independent slots" (Default, Smart, NER, Wonderwall). Four, five, and six are all used for the same concept depending on which page you read.
Consequence: A self-hoster following the site's mental model looks for six slot env vars in CONFIGURATION.md and finds four, then has to reverse-engineer that embeddings and the reranker are counted as "slots" on one surface but not the other. Inconsistent core terminology across the two doc surfaces the project explicitly links together.
The fix: Pick one taxonomy (e.g. "four LLM slots + embedding + reranker"), use it on both the site docs and CONFIGURATION.md, and reconcile the "six slots / five keys / four slots" arithmetic in one table.
What they do well
Exceptional machine-readable surface area: llms.txt, agents.md, index.md, two OpenAPI 3.1 specs, an RFC 9727 api-catalog, an MCP manifest with tools, agent-skills index, and a served /skill.md — all live and returning 200.
Honest failure-mode documentation: the caveats section covers no-chargebacks, double-pay avoidance, 404-on-status semantics, and re-402 debugging — rare candor for a payments API.
Versioning and rate-limit policy is a contract, not prose: API-Version headers, RFC 9745/8594 deprecation signaling, and RateLimit-* headers are declared in the site OpenAPI spec.
Top 3 recommendations
Regenerate the /docs wire-format reference (accepts[], 202 body, status enum) from the live API — chain support, cancel_token, and run states have all drifted since July.
Make the OpenAPI schema the single source of truth for seed validation (6/400 minimums) and fix the contradicting numbers in x-guidance and /docs.
Give every endpoint on /docs an explicit base URL, separating self-hosted engine surfaces from the hosted x402 API, and update llms.txt/agents.md to the current three-chain payment story.
Fixed
0
Skip
6
Fail
1
Failing pages
https://www.miroshark.xyz/docs
Summary
Verified 20 runnable examples from MiroShark's public docs (https://www.miroshark.xyz/docs, https://x402.miroshark.xyz/skill.md): 13 PASS, 6 SKIP, 1 FAIL. All free network examples work exactly as documented — the 402 challenge, /suggest, /health, /ready, and both CDP discovery curls return the documented shapes, and every documented npm/pip package installs with its documented import paths resolving. The one failure is the Python Solana client example on /docs: after installing exactly as documented (pip install 'x402[svm,requests]'), the documented import from x402.mechanisms.svm.exact.client import ExactSvmScheme raises ImportError: SVM mechanism requires solana packages — the unpinned svm extra pulls solana 0.40.3, which no longer ships the solana.rpc.api module that x402 2.24.0 imports (ModuleNotFoundError: No module named 'solana.rpc.api'). The failure occurs before any credential or payment is involved. Paid /run examples were skipped: no funded wallet credentials were provided, and running them settles a real, non-refundable $1 USDC payment. Python installs required a --user --break-system-packages environment adaptation for the sandbox's PEP 668 policy; snippet content was not modified.
Required credentials
X402_BUYER_PRIVATE_KEY — funded Base USDC wallet (not provided)
Installs x402 2.24.0; all documented EVM import paths resolve
2
pip install 'x402[svm,requests]'
PASS
Install exits 0 (but see #5)
3
Python Base client (x402ClientSync + ExactEvmScheme → POST /run)
SKIP
Requires funded X402_BUYER_PRIVATE_KEY; executes a real $1 payment
4
Python Solana client (ExactSvmScheme + KeypairSigner → POST /run)
FAIL
ImportError at the documented import, before credentials are read. Diagnosis: x402 2.24.0 imports solana.rpc.api, removed in solana 0.40.3 which the unpinned svm extra installs. Suggested solution (unverified): docs should pin a compatible solana version (e.g. solana<0.40) or upstream x402 should constrain its svm extra
5
npm install @x402/fetch @x402/evm viem
PASS
x402Client and registerExactEvmScheme import paths resolve
6
TypeScript client (client.fetch → POST /run)
SKIP
Requires funded X402_BUYER_PRIVATE_KEY
7
npx awal x402 pay https://x402.miroshark.xyz/run --body '{"prompt":"Your scenario"}'
SKIP
Initiates a real $1 payment; requires wallet sign-in and USDC funding
POST /suggest {"prompt": "AI regulation backlash in Europe"}
PASS
200; returned data.ideas (empty list on one call, which skill.md documents as the transient-blip behavior — a second call with another topic returned populated ideas)