MiroShark
Pay-per-run · x402 · v1

Run MiroShark over x402

Pay $1 in USDC over HTTP. Get back a world.

MiroShark is a paid x402 endpoint. No account, no API key, no signup — if your agent can sign an EVM or Solana transaction, it can POST a prompt, pay $1, and launch a full multi-agent simulation. This is the guide for buyers, consumers and integrators.

The one call

POST https://x402.miroshark.xyz/run
Content-Type: application/json

{"prompt": "How will developers react if OpenAI ships GPT-6 next month?"}

#  → 402 Payment Required   (your x402 client signs $1 USDC and retries)
#  → 202 Accepted           {"data": {"run_id": "run_…", "wait_url": "…"}}

Prefer to let an LLM do the wiring? On the home page there's a one-click Copy x402 prompt button — paste it into any agent and it knows the whole dance. This page is the long-form reference behind that prompt.

Contents
00Overview

One POST, one dollar, one world

MiroShark is a paid x402 endpoint. Your agent POSTs a prompt, pays $1 USDC over HTTP, and gets back a live URL where a full multi-agent simulation report appears in ~10 minutes. No account, no API key, no signup.

What you get for $1

The run ingests your seed, extracts entities into a knowledge graph, spawns ~25 grounded agent personas, simulates 10 rounds of Twitter + Reddit + a Polymarket-style prediction market, and synthesizes a markdown report — belief drift, top posts, market trajectories, a knowledge-graph view.

Flat price, real economics

You always pay a flat $1 USDC. The pipeline costs MiroShark roughly $0.16–0.26 in LLM spend for a standard run (~$0.55–0.76 with deep research), bounded by a per-run $0.95 ceiling. A real run took ~9 minutes and produced a 37 KB report.

No account, no key

There is no signup, OAuth, or API key. The only credential is a wallet that can sign a USDC transfer. After you pay, the returned run_id is the token for every follow-up call — polling and the report are public and unauthenticated.

Two chains, one endpoint

The same POST /run accepts USDC on either Base or Solana. The 402 challenge advertises both as separate accepts[] entries; your client pays on whichever chain its wallet is funded on.
POST /run  ($1 USDC)
   │
   ├─ ingest      seed → entities                  (~8 s)
   ├─ ontology    entity types                     (~10 s)
   ├─ graph_build Neo4j knowledge graph            (~11 s)
   ├─ create      simulation scaffold              (~0 s)
   ├─ prepare     ~25 grounded personas            (~70 s)
   ├─ simulate    10 rounds · Twitter/Reddit/Market (~6–18 min)
   └─ report      cited markdown post-mortem
        │
        └─▶  share_url  (auto-published, recap card, 7 panels)
01Endpoint

The endpoint, seeds & price

POST /run with exactly one seed — a prompt, an article URL, or raw text. The price is a flat $1.00 USDC, settled on Base or Solana — the 402 advertises both and your wallet picks the chain it holds.

One seed, three shapes

Provide exactly one of these in the JSON body to seed the simulation:
{"prompt":  "<scenario or question, 4–4000 chars>"}      ← most common
{"url":     "<article / news URL — MiroShark fetches & simulates it>"}
{"article": "<raw document text, 4–200000 chars>"}

Price

$1.00 USDC — 6 decimals, so amount: "1000000" atomic units. The x402 v2 exact scheme, settled through the Coinbase CDP facilitator.

No gas needed

The facilitator sponsors the settlement fee on both chains — you fund the wallet with ~$1 USDC only, no ETH (Base) or SOL (Solana) required. On Base you sign an EIP-3009 transferWithAuthorization; on Solana, an SPL Token transfer.

Where the $1 goes — pick the chain your wallet holds

Base mainnet   network  eip155:8453
               USDC     0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
               payTo    0x67976cebb5266b50a08c0dcb676e03baf305e3a2
               amount   "1000000"

Solana mainnet network  solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
               USDC     EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
               payTo    7SdBWQZZM46E1ZmsFhbNN1UD4UquyYsvNGNoas6UCHip
               amount   "1000000"

Always trust the authoritative values in the live 402 response's PAYMENT-REQUIRED header (base64 JSON, field accepts[]) over anything hardcoded — a real x402 client reads them for you at call time. The values above are just a head-start so you can pre-fund the right wallet.

02Protocol

The payment dance

The standard x402 v2 flow: POST → 402 with a PAYMENT-REQUIRED header → sign the USDC transfer → re-POST with X-PAYMENT → 202 Accepted with your run_id and follow URLs. Gas is sponsored by the CDP facilitator.

1. POST /run  (no payment)
        ↓
2. 402 Payment Required  + PAYMENT-REQUIRED header (base64 accepts[])
        ↓
3. client decodes accepts[], signs the USDC transfer authorization
        ↓
4. POST /run again  + X-PAYMENT header (the signed payload), SAME body
        ↓
5. server settles on-chain → 202 Accepted + PAYMENT-RESPONSE (tx hash)

What a v2 SDK does for you

Every step above is automatic with an x402-aware client: it catches the 402, decodes accepts[], signs against the matching chain's requirements, and replays the request with X-PAYMENT. You write one POST and read the 202.

The 202 response body

On success you get a run_id plus two ways to follow the run. The PAYMENT-RESPONSE header carries the on-chain tx hash for your records.
HTTP/2 202 Accepted
PAYMENT-RESPONSE: <base64 SettleResponse — tx hash + payer + network>

{
  "success": true,
  "data": {
    "run_id":    "run_86ead0ea7fa7",
    "status":    "queued",
    "stages":    ["ingest","ontology","graph_build","create","prepare","simulate","report"],
    "wait_url":  "https://x402.miroshark.xyz/wait/run_86ead0ea7fa7",
    "status_url":"https://x402.miroshark.xyz/status/run_86ead0ea7fa7",
    "payer":     "0xYourWalletAddress",
    "payment_chain":   "base",
    "payment_network": "eip155:8453"
  }
}
03Clients

Pay from any runtime

Drop-in code for the official x402 SDK in Python (Base + Solana) and TypeScript, the awal CLI for shell agents, the payments MCP for Claude Desktop / ChatGPT, and an ERC-7710 sidecar for MetaMask Smart Accounts.

Python — Base (EVM), official x402 SDK

pip install 'x402[evm,requests]' eth-account requests
import os
from eth_account import Account
from x402.client import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm.exact.client import ExactEvmScheme

account = Account.from_key(os.environ["X402_BUYER_PRIVATE_KEY"])

client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(signer=account))   # Base mainnet
session = x402_requests(client)   # handles 402 → sign → retry automatically

resp = session.post(
    "https://x402.miroshark.xyz/run",
    json={"prompt": "How will developers react if OpenAI releases GPT-6 next month?"},
    timeout=120,
)
data = resp.json()["data"]
print("Run ID:", data["run_id"], "| follow:", data["wait_url"])

Fund the address with ~$1+ USDC on Base mainnet — no ETH needed, settlement gas is sponsored.

Python — Solana (SVM)

Same flow, different scheme — install the svm extra and register the Solana scheme; the adapter does 402 → sign SPL transfer → retry.
pip install 'x402[svm,requests]'
import os, json
from solders.keypair import Keypair
from x402.client import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.svm.exact.client import ExactSvmScheme
from x402.mechanisms.svm.signers import KeypairSigner

SOLANA_MAINNET = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"

raw = os.environ["SOLANA_BUYER_PRIVATE_KEY"].strip()
kp = (Keypair.from_bytes(bytes(json.loads(raw))) if raw.startswith("[")
      else Keypair.from_base58_string(raw))

client = x402ClientSync()
client.register(SOLANA_MAINNET, ExactSvmScheme(signer=KeypairSigner(kp)))
session = x402_requests(client)   # picks the Solana accepts[] entry automatically

resp = session.post(
    "https://x402.miroshark.xyz/run",
    json={"prompt": "Your scenario"}, timeout=120,
)
print(resp.json()["data"]["run_id"])   # paid on: "solana"

TypeScript / JavaScript

npm install @x402/fetch @x402/evm viem
import { x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
const signer = privateKeyToAccount(process.env.X402_BUYER_PRIVATE_KEY as `0x${string}`);
registerExactEvmScheme(client, { signer });

const res = await client.fetch("https://x402.miroshark.xyz/run", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "Your scenario" }),
});
const data = (await res.json()).data;

Shell / CLI agents

Claude Code, Codex CLI, Gemini CLI — use the Agentic Wallet CLI, which handles sign-in, USDC funding and the dance:
npx awal x402 pay \
  https://x402.miroshark.xyz/run \
  --body '{"prompt":"Your scenario"}'

MCP-only hosts

Claude Desktop, ChatGPT, Cherry Studio — install @coinbase/payments-mcp once, restart the host, then call make-x402-request with the URL + JSON body.

MetaMask Smart Accounts

For delegated / recurring budgets, an ERC-7710 sidecar takes the same dance at POST /run-7710 — grant an ERC-7715 permission once, then a session key pays per run inside it.

Any x402 v2 client works — these are the common ones. To mint a throwaway EVM wallet locally (the key never leaves your machine): python -c "from eth_account import Account; a=Account.create(); print(a.address, a.key.hex())", then fund it with USDC on Base.

04Inputs

Tune the run

Three optional fields ride along with any seed: deep_research for a live-web context sweep, prediction_market to pin the central market, and affiliate to earn 50% of a referred run's net profit.

deep_research — live-web context

Set "deep_research": true to run a multi-query live-web sweep before the sim — it plans ~3 searches, runs them against a web-search model, and synthesizes a richer, current seed with named actors. Noticeably better for fast-moving or niche topics. Off by default.
{"prompt": "EU AI Act enforcement in 2026",
 "deep_research": true}

prediction_market — pin the market

By default MiroShark designs the Polymarket question for you. Pass a bare string to force the central market, or an object to set the opening price and outcome labels.
{"prompt": "...",
 "prediction_market": {
   "question": "Will Argentina win the 2026 FIFA World Cup?",
   "outcome_a": "YES", "outcome_b": "NO",
   "initial_probability": 0.28
 }}

affiliate — earn 50% of net profit

Refer paid runs and earn half the profit. Pass an affiliate wallet — an EVM 0x address ora base58 Solana address — and it's logged against every run you send. The payout follows the address's chain family.

{"prompt": "Your scenario",
 "affiliate": "0xYourAffiliateWalletAddress"}

net_profit = $1.00 (price)  −  the run's actual LLM cost
            → split 50 / 50 between MiroShark and the affiliate

A standard run costs ~$0.20, so net profit ≈ $0.80 → the affiliate earns ≈ $0.40 per referred run; a deep-research run earns ≈ $0.12–0.22. Completed runs only, profit floored at $0, and payouts settle off-chain from the logged data — the $1 still settles in full on-chain at request time.

05Polling

Follow the run & read the report

The run_id is the token — no auth. Poll /status for JSON, open /wait for an auto-refreshing page, or pull the finished report as raw markdown or JSON from /report. Every run auto-publishes a shareable recap card.

status_url — JSON, for agents

GET /status/<run_id> — no auth, structured for polling. Poll until status is terminal; on completed, share_url is the absolute share-page URL.

wait_url — HTML, for humans

GET /wait/<run_id> — a public page that auto-refreshes every 5 s, shows the live stage + progress bar, and links to /share/<sim_id> once the report renders. Close the tab and the run continues server-side.

The status payload (declared in /openapi.json)

GET /status/<run_id>
{
  "success": true,
  "data": {
    "run_id": "run_86ead0ea7fa7",
    "status": "running",        // queued | running | completed | failed | budget_exceeded | cancelled
    "progress": 42,             // 0–100
    "current_stage": "simulate",
    "current_round": 4,
    "message": "Round 4/10",
    "simulation_id": null,      // set on completion
    "share_url": null,          // set on completion → https://<host>/share/<sim_id>
    "budget": {"cost_usd": 0.11, "tokens_used": 184223, "calls": 57},
    "payment_chain": "solana",
    "payment_network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
  }
}

Poll until status is completed, failed, budget_exceeded or cancelled. One subtlety: stages here is an object keyed by stage name, whereas the stages in the 202 body is an array— don't reuse one parser for both.

Read the report without the website

Once completed, pull the report text directly — no HTML, no auth:
GET /report/<run_id>?format=md     → raw markdown
GET /report/<run_id>?format=json   → {report_markdown, title, share_url, …}
Before the run finishes these return 409 with the current status.

The recap card (auto-unfurl)

Every completed run produces a 1200×630 PNG leading with the outcome, agent/round counts and spend — the image that unfurls on X / Discord / Slack / iMessage. Grab it directly:
GET /api/simulation/<sim_id>/share-card.png
Generated on first request and cached, so it's cheap to hot-link.
06Free

Free pre-flight & health

Three unpaid helpers: /suggest turns a vague topic into launchable prompts before you spend a cent, and /health + /ready tell you the service is up so your settle doesn't fail.

/suggest — ideas before you spend

Not sure what to run? POST /suggest (free, no payment) turns a vague topic into up to 5 launchable ideas, each with a ready-to-run prompt you can drop straight into /run. Rate-limited per IP and cached; returns an empty list on a transient blip rather than erroring.
POST /suggest   {"prompt": "stablecoin regulation"}
→ {"data": {"ideas": [{title, pitch, prompt, angle}, …]}}

/health & /ready — is it up?

Check readiness before you pay — if /ready is 503, your settle will probably fail.
GET /health   → liveness, no downstream checks
GET /ready    → 200 when DB + Neo4j are reachable; 503 otherwise
There are no chargebacks, so waiting for a green /ready is the cheapest insurance you have.
07Discovery

Discover & verify

MiroShark is cataloged across the main x402 directories — CDP Bazaar, agentic.market, x402scan, AgentCash, Ampersend — so an agent can find and vet it by semantic search before ever making a paid call.

Listed as “MiroShark”

Tags Simulation, Research, Search, Crypto, AI, with a service logo at /logo.png. An agent-facing manual for the full suggest → pay → poll → report loop is served at GET /skill.md.

Pick before paying

Each directory exposes the same accepts[] shape as the live 402 plus the input/output schemas — so an agent can choose MiroShark by semantic search and code against it without first making a paid request.

Where MiroShark indexes

  • CDP Bazaar — indexes on each successful settle; reads the service metadata + bazaar input/output schemas.
  • agentic.market — mirrors CDP Bazaar automatically.
  • x402scan & AgentCash — read GET /openapi.json (OpenAPI 3.1) as the canonical contract.
  • Ampersend marketplace — curated catalog; maps /skill.md + /logo.png to its skillmd_url / logo_url fields.
# CDP discovery is read-only and unauthenticated:
curl 'https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=miroshark'
curl 'https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0x67976cebb5266b50a08c0dcb676e03baf305e3a2'
Verify the live listing
08Reference

Wire format (hand-rolled)

If you don't use a v2-aware SDK, here are the exact bytes: the base64 PAYMENT-REQUIRED challenge with both accepts[] entries, the X-PAYMENT payload shape, and the PAYMENT-RESPONSE that carries your tx hash.

1 · The 402 challenge (decoded PAYMENT-REQUIRED)

{
  "x402Version": 2,
  "resource": {
    "url": "https://x402.miroshark.xyz/run",
    "serviceName": "MiroShark",
    "tags": ["Simulation","Research","Search","Crypto","AI"]
  },
  "accepts": [
    { "scheme":"exact", "network":"eip155:8453",
      "asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount":"1000000",
      "payTo":"0x67976cebb5266b50a08c0dcb676e03baf305e3a2",
      "maxTimeoutSeconds":300, "extra":{"name":"USDC","version":"2"} },
    { "scheme":"exact", "network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount":"1000000",
      "payTo":"7SdBWQZZM46E1ZmsFhbNN1UD4UquyYsvNGNoas6UCHip",
      "maxTimeoutSeconds":300, "extra":{"feePayer":"<facilitator-sponsored>"} }
  ]
}
Two entries — Base (EVM) and Solana — both $1 USDC. Pick the one matching your wallet's chain.

2 · Retry with X-PAYMENT (Base / EVM example)

Sign an EIP-3009 transferWithAuthorization for amount of the USDC asset, to payTo; base64-encode the PaymentPayload and send it in the X-PAYMENT header with the same body.
{
  "x402Version": 2,
  "accepted": { … the chosen accepts[] entry … },
  "resource": "https://x402.miroshark.xyz/run",
  "payload": {
    "signature": "0x…",
    "authorization": {
      "from": "0xYourWalletAddress",
      "to":   "0x67976cebb5266b50a08c0dcb676e03baf305e3a2",
      "value":"1000000",
      "validAfter":"…", "validBefore":"…",
      "nonce":"0x<random 32 bytes>"
    }
  }
}
On Solana you build and sign an SPL Token transfer of the same amount, leaving feePayerto the facilitator — the SDK's SVM scheme handles it.

3 · The settle (decoded PAYMENT-RESPONSE)

{
  "success": true,
  "transaction": "0x1f2ab48e…2ee06a",   // on-chain USDC transfer
  "network": "eip155:8453",
  "payer": "0xYourWalletAddress"
}
Verify the transaction on BaseScan (Base) or Solscan (Solana — the value is a base58 signature). The same payment_chain / payment_network ride along in the 202 body and every /status response.

Full reference: the x402 v2 specification.

09Caveats

Gotchas & no chargebacks

x402 is final — once USDC settles there is no chargeback. Design retries that never double-pay, know what 402 / 429 / 404 each mean, and understand there is no automatic refund if a paid run fails.

No chargebacks — ever

Once your USDC settles, the operator has it; x402 has no chargebacks. If the X-PAYMENT POST errors mid-flight, check the chain explorer for your signed nonce (EVM) or signature (Solana) before retryingso you don't double-pay.

No automatic refund on failure

If a run shows failed or budget_exceededafter settle, the $1 is already paid — there's no auto-refund. Contact the operator with your run_id for a manual review.

Runs take 10–25 min

The simulate stage is ~6–18 min on its own. A 429 means the server hit its concurrency cap — retry with backoff. Polling is free, so poll /status rather than re-POSTing.

404 on status_url

Means the run_id is wrong or you polled a redeployed instance with a wiped DB. Re-POST /runonly if you've confirmed on BaseScan/Solscan that the original payment never settled.

402 returned again after you sent X-PAYMENT?

Usually insufficient USDC, a signature mismatch, a reused nonce (EVM) or a stale blockhash (Solana). Check the balance on BaseScan / Solscan, mint a fresh nonce, confirm the EIP-712 domain matches extra.name / extra.version, and make sure you signed the right chain's accepts[] entry.

Heads-up for pay/ pay.sh users: the CLI only routes x402 for endpoints in its catalog. MiroShark's listing is pending; until it merges, pay falls back to MPP and won't settle here — use any direct x402 client above.

Ship it

One POST. One dollar. Ten minutes.

Copy the agent prompt from the home page, or wire the SDK straight into your runtime with the snippets above. Either way, the run_id is your only token.