### Install Python x402 SDK

Source: https://www.miroshark.xyz/docs

Command to install the official x402 SDK with EVM support.

```bash
pip install 'x402[evm,requests]' eth-account requests
```

--------------------------------

### Install Solana SVM Dependencies

Source: https://www.miroshark.xyz/docs

Required package installation for enabling Solana SVM support in x402.

```bash
pip install 'x402[svm,requests]'
```

--------------------------------

### GET /health & GET /ready

Source: https://www.miroshark.xyz/docs

Endpoints to verify the operational status of the service.

```APIDOC
## GET /health

### Description
Checks the liveness of the service without downstream checks.

### Method
GET

### Endpoint
/health

## GET /ready

### Description
Checks if the database and Neo4j are reachable. Returns 200 if ready, 503 otherwise.

### Method
GET

### Endpoint
/ready
```

--------------------------------

### Initialize Python x402 client

Source: https://www.miroshark.xyz/docs

Setup for the synchronous x402 client using an EVM account for Base mainnet.

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

--------------------------------

### Install TypeScript EVM Dependencies

Source: https://www.miroshark.xyz/docs

Required packages for x402 integration in TypeScript/JavaScript environments.

```bash
npm install @x402/fetch @x402/evm viem
```

--------------------------------

### 202 Accepted response example

Source: https://www.miroshark.xyz/docs

The response body returned upon successful payment and run initiation.

```http
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"
  }
}
```

--------------------------------

### Retrieve Ecosystem Data via API

Source: https://www.miroshark.xyz/docs

Example response structure for the machine-readable ecosystem catalog endpoint.

```json
GET /api/ecosystem.json
{ "success": true,
  "data": {
    "schema_version": "1",
    "count": 14,
    "ecosystem": [
      { "name": "Sparkleware", "category": "integration",
        "x_handle": "…", "repo": "https://github.com/…" },
      …
    ] } }
```

--------------------------------

### GET /platform/v2/x402/discovery/search

Source: https://www.miroshark.xyz/docs

Searches for MiroShark resources using a query string.

```APIDOC
## GET /platform/v2/x402/discovery/search

### Description
Performs a search for MiroShark resources based on a provided query string.

### Method
GET

### Endpoint
https://api.cdp.coinbase.com/platform/v2/x402/discovery/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search term (e.g., 'miroshark')
```

--------------------------------

### GET /api/ecosystem.json

Source: https://www.miroshark.xyz/docs

Retrieves the machine-readable catalog of projects, agents, and tools built on MiroShark.

```APIDOC
## GET /api/ecosystem.json

### Description
Retrieves a crawlable list of projects, agents, and tools built on MiroShark. Each entry includes the name, URL, description, category, X handle, and repository link.

### Method
GET

### Endpoint
/api/ecosystem.json

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - The ecosystem catalog data
- **schema_version** (string) - The version of the schema
- **count** (integer) - Total number of entries
- **ecosystem** (array) - List of ecosystem projects

#### Response Example
{
  "success": true,
  "data": {
    "schema_version": "1",
    "count": 14,
    "ecosystem": [
      {
        "name": "Sparkleware",
        "category": "integration",
        "x_handle": "…",
        "repo": "https://github.com/…"
      }
    ]
  }
}
```

--------------------------------

### GET /platform/v2/x402/discovery/merchant

Source: https://www.miroshark.xyz/docs

Retrieves merchant information associated with a specific payment address.

```APIDOC
## GET /platform/v2/x402/discovery/merchant

### Description
Retrieves merchant details for a given payment address.

### Method
GET

### Endpoint
https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant

### Parameters
#### Query Parameters
- **payTo** (string) - Required - The payment address to look up
```

--------------------------------

### GET /api/project/<id>/stats

Source: https://www.miroshark.xyz/docs

Retrieves statistics scoped to a specific project workspace.

```APIDOC
## GET /api/project/<id>/stats

### Description
Retrieves statistics for a specific project, including consensus distribution and quality distribution.

### Method
GET

### Endpoint
/api/project/<id>/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **consensus_distribution** (object) - Distribution of consensus for the project.
- **quality_distribution** (object) - Quality metrics distribution for the project.
```

--------------------------------

### Trigger Automated Deep Research

Source: https://www.miroshark.xyz/docs

Example of a prompt input that triggers the server-side live-web deep research sweep.

```json
{"prompt": "EU AI Act enforcement in 2026"}
// → live-web deep research runs automatically
```

--------------------------------

### GET /api/stats

Source: https://www.miroshark.xyz/docs

Aggregates consensus distribution and confidence metrics across all public completed simulations.

```APIDOC
## GET /api/stats

### Description
Retrieves platform-wide statistics including consensus distribution and average confidence.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **consensus_distribution** (object) - Distribution of consensus across simulations.
- **average_confidence** (number) - Average confidence score across all simulations.
```

--------------------------------

### GET /api/simulation/<sim_id>/share-card.png

Source: https://www.miroshark.xyz/docs

Retrieves a 1200x630 PNG recap card for a completed simulation run, suitable for social media unfurling.

```APIDOC
## GET /api/simulation/<sim_id>/share-card.png

### Description
Retrieves a 1200x630 PNG image representing the outcome, agent/round counts, and spend of a simulation. This image is generated on the first request and cached.

### Method
GET

### Endpoint
/api/simulation/<sim_id>/share-card.png

### Parameters
#### Path Parameters
- **sim_id** (string) - Required - The unique identifier of the simulation run.
```

--------------------------------

### GET /api/simulation/<id>/frame/<round>

Source: https://www.miroshark.xyz/docs

Retrieves a compact snapshot of a specific simulation round, including agent actions, active agent counts, market prices, and belief states.

```APIDOC
## GET /api/simulation/<id>/frame/<round>

### Description
Returns a compact snapshot of the simulation for a given ID and round number. This endpoint is used to power replay scrubbers and CLI subcommands.

### Method
GET

### Endpoint
/api/simulation/<id>/frame/<round>

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the simulation.
- **round** (integer) - Required - The specific round number to retrieve.

#### Query Parameters
- **platforms** (string) - Optional - Filter data by specific platforms.
- **include_belief** (boolean) - Optional - Whether to include belief state data in the response.
- **include_market** (boolean) - Optional - Whether to include market price data in the response.
```

--------------------------------

### GET /report/<run_id>

Source: https://www.miroshark.xyz/docs

Retrieves the final report for a completed simulation run in markdown or JSON format.

```APIDOC
## GET /report/<run_id>

### Description
Fetches the completed report for a run. Returns a 409 status if the run is not yet finished.

### Method
GET

### Endpoint
/report/<run_id>

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier for the simulation run.

#### Query Parameters
- **format** (string) - Optional - The desired output format: 'md' for raw markdown or 'json' for a structured object.
```

--------------------------------

### GET /status/<run_id>

Source: https://www.miroshark.xyz/docs

Retrieves the current status of a simulation run. Poll this endpoint until the status reaches a terminal state.

```APIDOC
## GET /status/<run_id>

### Description
Returns the current status, progress, and budget information for a specific simulation run.

### Method
GET

### Endpoint
/status/<run_id>

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier for the simulation run.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains run details including status, progress, current_stage, and budget.

### Response Example
{
  "success": true,
  "data": {
    "run_id": "run_86ead0ea7fa7",
    "status": "running",
    "progress": 42,
    "current_stage": "simulate",
    "current_round": 4,
    "message": "Round 4/10",
    "simulation_id": null,
    "share_url": null,
    "budget": {"cost_usd": 0.11, "tokens_used": 184223, "calls": 57},
    "payment_chain": "solana",
    "payment_network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
  }
}
```

--------------------------------

### GET /api/simulation/<id>/cost.json

Source: https://www.miroshark.xyz/docs

Retrieves the estimated cost of a specific simulation run, including token and latency breakdowns.

```APIDOC
## GET /api/simulation/<id>/cost.json

### Description
Returns the estimated cost of a simulation run in USD, including breakdowns by model and phase.

### Method
GET

### Endpoint
/api/simulation/<id>/cost.json

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the simulation run.

### Response
#### Success Response (200)
- **estimated_cost_usd** (number) - The total estimated cost in USD.
- **token_totals** (object) - Total tokens used.
- **latency_totals** (object) - Total latency metrics.
- **by_model** (object) - Cost breakdown by model.
- **by_phase** (object) - Cost breakdown by simulation phase.
- **is_estimate** (boolean) - Flag indicating if the value is an estimate.
```

--------------------------------

### Implement Revenue Sharing with x402aff

Source: https://www.miroshark.xyz/docs

Use the x402aff library to route payments into per-builder 0xSplits contracts instead of a personal wallet.

```javascript
npm install x402aff viem     # or: pip install x402aff

import { Affiliation } from "x402aff";

const aff = new Affiliation({ appCode: "bc_yourcode", sellerPayout: "0x…" });

// aff.payTo is a drop-in x402 DynamicPayTo callback:
paymentMiddleware(facilitator, {
  "/api/data": { payTo: aff.payTo, extensions: aff.extensions },
});
```

--------------------------------

### POST /suggest

Source: https://www.miroshark.xyz/docs

Generates launchable simulation ideas and prompts based on a provided topic.

```APIDOC
## POST /suggest

### Description
Turns a vague topic into up to 5 launchable ideas, each with a ready-to-run prompt. This endpoint is free and rate-limited per IP.

### Method
POST

### Endpoint
/suggest

### Request Body
- **prompt** (string) - Required - The topic or subject to generate ideas for.

### Request Example
{
  "prompt": "stablecoin regulation"
}

### Response
#### Success Response (200)
- **data** (object) - Contains a list of ideas, each with title, pitch, prompt, and angle.
```

--------------------------------

### POST /run

Source: https://www.miroshark.xyz/docs

Initiates a multi-agent simulation run. This endpoint requires a payment of $1 USDC via the x402 protocol on either Base or Solana chains.

```APIDOC
## POST /run

### Description
Initiates a multi-agent simulation run. The server responds with a 402 Payment Required status containing payment details. Upon successful payment of $1 USDC, the simulation begins, and a run_id is returned for tracking.

### Method
POST

### Endpoint
/run

### Request Body
- **seed** (string) - Required - The input seed used to generate the simulation entities and knowledge graph.

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the simulation run.
- **share_url** (string) - The URL where the final multi-agent simulation report will be published.
```

--------------------------------

### Generate Simulation Ideas

Source: https://www.miroshark.xyz/docs

Converts a topic into launchable prompts. This endpoint is free, rate-limited, and cached.

```http
POST /suggest   {"prompt": "stablecoin regulation"}
→ {"data": {"ideas": [{title, pitch, prompt, angle}, …]}}
```

--------------------------------

### POST /run

Source: https://www.miroshark.xyz/docs

Initiates a simulation run. This endpoint follows the x402 v2 payment flow: an initial request triggers a 402 Payment Required response, followed by a signed payment submission to receive a 202 Accepted response.

```APIDOC
## POST /run

### Description
Initiates a simulation run by providing a seed. The request requires a payment flow using the x402 v2 protocol.

### Method
POST

### Endpoint
/run

### Request Body
- **prompt** (string) - Optional - Scenario or question (4–4000 chars).
- **url** (string) - Optional - Article or news URL to simulate.
- **article** (string) - Optional - Raw document text (4–200000 chars).

### Request Example
{
  "prompt": "Analyze the impact of AI on global markets."
}

### Response
#### Success Response (202)
- **success** (boolean) - Indicates if the request was accepted.
- **data** (object) - Contains run_id, status, stages, wait_url, status_url, payer, payment_chain, and payment_network.

#### Response Example
{
  "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"
  }
}
```

--------------------------------

### Implement Solana SVM Payment Scheme

Source: https://www.miroshark.xyz/docs

Configures the x402 client with a Solana keypair signer to handle automated SPL transfers for API access.

```python
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"
```

--------------------------------

### Performance Optimization Metrics

Source: https://www.miroshark.xyz/docs

Comparison of performance improvements between the naive baseline and the optimized engine implementation.

```text
Neo4j writes        1 tx per entity      →  batched UNWIND      (10×)
Chunk processing    sequential           →  ThreadPoolExecutor (3×)
Config generation   sequential batches   →  parallel batches   (3×)
Platform execution  partial concurrency  →  all 3 in parallel
Memory compaction   blocking             →  background thread
```

--------------------------------

### Implement TypeScript EVM Payment Scheme

Source: https://www.miroshark.xyz/docs

Configures the x402 client with an EVM account signer for automated payment processing.

```typescript
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;
```

--------------------------------

### Ingestion Pipeline Workflow

Source: https://www.miroshark.xyz/docs

Visual representation of the text ingestion process from NER through contradiction adjudication and graph creation.

```text
text  →  NER (with ontology)
      →  batch embed (text-embedding-3-large | Ollama)
      →  entity resolve (fuzzy + vector + LLM reflection)
      →  MERGE entities (canonical UUIDs)
      →  contradiction adjudication (invalidate old)
      →  CREATE RELATION {valid_at, invalid_at, kind, source_type, source_id}
```

--------------------------------

### Execute x402 Request via CLI Agent

Source: https://www.miroshark.xyz/docs

Uses the Agentic Wallet CLI to handle payment and request execution.

```bash
npx awal x402 pay \
  https://x402.miroshark.xyz/run \
  --body '{"prompt":"Your scenario"}'
```

--------------------------------

### Register Builder Code Extension

Source: https://www.miroshark.xyz/docs

Attach a builder code to the x402 client to enable on-chain revenue attribution for runs.

```javascript
npm install @x402/extensions

import { BuilderCodeClientExtension } from "@x402/extensions/builder-code";

// on the same x402Client() you registered the scheme on, before paying:
client.registerExtension(new BuilderCodeClientExtension("bc_yourcode"));
// every payment you drive now carries your code on-chain
```

--------------------------------

### Payment network configuration

Source: https://www.miroshark.xyz/docs

Network and USDC contract details for Base and Solana mainnets.

```text
Base mainnet   network  eip155:8453
               USDC     0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
               payTo    0x6cab485fc28ec70d3845113b704d4824e4d2b24f
               amount   "1000000"

Solana mainnet network  solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
               USDC     EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
               payTo    9vWbPNMvt8ui1cNN8jWWPUWT5LPmeXzq7nr3vry1vMPH
               amount   "1000000"
```

--------------------------------

### Generate Local EVM Wallet

Source: https://www.miroshark.xyz/docs

Command to generate a throwaway EVM wallet address and private key for funding.

```bash
python -c "from eth_account import Account; a=Account.create(); print(a.address, a.key.hex())"
```

--------------------------------

### POST /run

Source: https://www.miroshark.xyz/docs

Executes a research run based on the provided prompt. The system automatically performs a live-web deep research sweep if only a prompt is provided.

```APIDOC
## POST /run

### Description
Initiates a research run. The API processes the prompt and returns a run ID and a wait URL for tracking progress.

### Method
POST

### Endpoint
https://x402.miroshark.xyz/run

### Request Body
- **prompt** (string) - Required - The research prompt or scenario to be processed.
- **prediction_market** (string) - Optional - Pin the central market for the run.

### Response
#### Success Response (200)
- **run_id** (string) - Unique identifier for the research run.
- **wait_url** (string) - URL to monitor the status of the run.
```

--------------------------------

### Configure Prediction Market Parameters

Source: https://www.miroshark.xyz/docs

Define custom market questions, outcome labels, and initial probabilities by passing an object to the prediction_market field.

```json
{
 "prompt": "...",
 "prediction_market": {
   "question": "Will Argentina win the 2026 FIFA World Cup?",
   "outcome_a": "YES", "outcome_b": "NO",
   "initial_probability": 0.28
 }}
```

--------------------------------

### Execute x402 Request in Python

Source: https://www.miroshark.xyz/docs

Standard implementation for making a POST request to the MiroShark API using the x402 session wrapper.

```python
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"])
```

--------------------------------

### Simulation Engine Architecture Diagram

Source: https://www.miroshark.xyz/docs

Visual representation of the round memory, platform integration, and belief state tracking.

```text
┌──────────────────────────────────────────────────────────┐
│        Round Memory (sliding window)                     │
│  Old rounds:        LLM-compacted summaries              │
│  Previous round:    full action detail                   │
│  Current round:     live (partial)                       │
└────┬─────────────┬─────────────┬─────────────────────────┘
     │             │             │
┌────▼────┐   ┌────▼────┐   ┌────▼──────────┐
│ Twitter │   │ Reddit  │   │ Polymarket    │
│ Posts   │   │ Comments│   │ Trades (AMM)  │
│ Likes   │   │ Upvotes │   │ Single market │
│ Reposts │   │ Threads │   │ Buy/Sell/Wait │
└────┬────┘   └────┬────┘   └────┬──────────┘
     │             │             │
┌────▼─────────────▼─────────────▼─────────────────────────┐
│        Market-Media Bridge                               │
│  Social sentiment   → trader prompts                     │
│  Market prices      → social media prompts               │
│  Social posts       → trader observation                 │
└────┬─────────────┬─────────────┬─────────────────────────┘
     │             │             │
┌────▼─────────────▼─────────────▼─────────────────────────┐
│        Belief State (per agent)                          │
│  Positions:   topic → stance (-1 to +1)                  │
│  Confidence:  topic → certainty (0 to 1)                 │
│  Trust:       agent → trust level (0 to 1)               │
└──────────────────────────────────────────────────────────┘
```

--------------------------------

### Persona Grounding Architecture

Source: https://www.miroshark.xyz/docs

Visual representation of the five-layer grounding process that feeds into the Wonderwall agent loop.

```text
entity ─┬─ attrs            (Neo4j properties)
        ├─ relationships   (1-hop edges)
        ├─ semantic        (vector neighbours)
        ├─ BFS context     (multi-hop)
        └─ web enrichment  (Perplexity / Sonar - public figures only)
                  ↓
        persona prompt  ─▶  Wonderwall agent loop
```

--------------------------------

### Seed the /run endpoint

Source: https://www.miroshark.xyz/docs

Provide exactly one of these JSON objects in the body to seed the simulation.

```json
{"prompt":  "<scenario or question, 4–4000 chars>"}      ← most common
{"url":     "<article / news URL - MiroShark fetches & simulates it>"}
{"article": "<raw document text, 4–200000 chars>"}
```

--------------------------------

### Retrieval Pipeline Workflow

Source: https://www.miroshark.xyz/docs

Visual representation of the parallel search strategy and re-ranking process for query execution.

```text
query
  ├─ vector edge   (Neo4j HNSW)        ─┐
  ├─ BM25 edge     (Neo4j fulltext)    ─┼─ temporal + kind filters → fused top 30
  └─ BFS traversal (from seed entities) ┘
                                       ↓
                BGE-reranker-v2-m3 (MPS / CUDA / CPU)
                                       ↓
                top N tagged with _sources ("v" / "k" / "g" / combos)
```

--------------------------------

### Service Health and Readiness Checks

Source: https://www.miroshark.xyz/docs

Verifies service availability before initiating paid requests to prevent settlement failures.

```http
GET /health   → liveness, no downstream checks
GET /ready    → 200 when DB + Neo4j are reachable; 503 otherwise
```

--------------------------------

### x402 Payment Challenge Structure

Source: https://www.miroshark.xyz/docs

The decoded PAYMENT-REQUIRED challenge provides the resource URL and accepted payment schemes for EVM and Solana chains.

```json
{
  "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":"0x6cab485fc28ec70d3845113b704d4824e4d2b24f",
      "maxTimeoutSeconds":300, "extra":{"name":"USDC","version":"2"} },
    { "scheme":"exact", "network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount":"1000000",
      "payTo":"9vWbPNMvt8ui1cNN8jWWPUWT5LPmeXzq7nr3vry1vMPH",
      "maxTimeoutSeconds":300, "extra":{"feePayer":"<facilitator-sponsored>"} }
  ]
}
```

--------------------------------

### x402 v2 payment flow

Source: https://www.miroshark.xyz/docs

The standard sequence for handling 402 Payment Required responses and re-submitting requests.

```text
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  + PAYMENT-SIGNATURE header (the signed payload), SAME body
        ↓
5. server settles on-chain → 202 Accepted + PAYMENT-RESPONSE (tx hash)
```

--------------------------------

### MiroShark Execution Pipeline

Source: https://www.miroshark.xyz/docs

Visual representation of the POST /run endpoint workflow and estimated processing times for each stage.

```text
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)
```

--------------------------------

### POST /run-7710

Source: https://www.miroshark.xyz/docs

Executes a research run using delegated or recurring budgets via ERC-7710 sidecar.

```APIDOC
## POST /run-7710

### Description
Executes a research run using delegated permissions (ERC-7715) for recurring budgets.

### Method
POST

### Endpoint
https://x402.miroshark.xyz/run-7710
```

--------------------------------

### Fetch Completed Run Reports

Source: https://www.miroshark.xyz/docs

Retrieve the final report in markdown or JSON format once a run is completed.

```http
GET /report/<run_id>?format=md     → raw markdown
GET /report/<run_id>?format=json   → {report_markdown, title, share_url, …}
```

--------------------------------

### Retrieve Simulation Recap Card

Source: https://www.miroshark.xyz/docs

Fetches a 1200x630 PNG image for social media unfurling. The image is generated on the first request and cached.

```http
GET /api/simulation/<sim_id>/share-card.png
```

--------------------------------

### CDP Discovery Endpoints

Source: https://www.miroshark.xyz/docs

Use these read-only, unauthenticated endpoints to search for MiroShark or retrieve merchant payment details.

```bash
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=0x6cab485fc28ec70d3845113b704d4824e4d2b24f'
```

--------------------------------

### PAYMENT-RESPONSE Structure

Source: https://www.miroshark.xyz/docs

The decoded response confirming successful settlement of the transaction.

```json
{
  "success": true,
  "transaction": "0x1f2ab48e…2ee06a",   // on-chain USDC transfer
  "network": "eip155:8453",
  "payer": "0xYourWalletAddress"
}
```

--------------------------------

### PAYMENT-SIGNATURE Payload (EVM)

Source: https://www.miroshark.xyz/docs

Structure for the PAYMENT-SIGNATURE header, requiring an EIP-3009 transferWithAuthorization signature.

```json
{
  "x402Version": 2,
  "accepted": { … the chosen accepts[] entry … },
  "resource": "https://x402.miroshark.xyz/run",
  "payload": {
    "signature": "0x…",
    "authorization": {
      "from": "0xYourWalletAddress",
      "to":   "0x6cab485fc28ec70d3845113b704d4824e4d2b24f",
      "value":"1000000",
      "validAfter":"…", "validBefore":"…",
      "nonce":"0x<random 32 bytes>"
    }
  }
}
```

--------------------------------

### Retrieve Run Status Payload

Source: https://www.miroshark.xyz/docs

Poll the /status endpoint to monitor progress, budget usage, and completion status of a run.

```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"
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.