# DopamineDesk x402 Marketplace MCP Server

[![Base Mainnet](https://img.shields.io/badge/Network-Base_Mainnet-blue)](https://base.org)
[![x402 Protocol](https://img.shields.io/badge/Protocol-x402_v2-green)](https://ai-data-marketplace-1042299154756.us-central1.run.app/.well-known/x402)
[![x402scan](https://img.shields.io/badge/x402scan-live_catalog-00c2ff)](https://www.x402scan.com/server/8dd63536-ba25-40f4-b36a-7d05ed18d007)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Server-purple)](https://modelcontextprotocol.io)
[![npm](https://img.shields.io/npm/v/dopaminedesk-ai-data-marketplace-mcp?label=npm)](https://www.npmjs.com/package/dopaminedesk-ai-data-marketplace-mcp)
[![npm downloads](https://img.shields.io/npm/dm/dopaminedesk-ai-data-marketplace-mcp?label=monthly%20downloads)](https://www.npmjs.com/package/dopaminedesk-ai-data-marketplace-mcp)
[![Tests](https://github.com/jblaz6335/mcp-server-aidatamarketplace/actions/workflows/test.yml/badge.svg)](https://github.com/jblaz6335/mcp-server-aidatamarketplace/actions/workflows/test.yml)

Decision-ready machine-to-machine reports paid per request with the **x402 Payment Protocol** on **Base Mainnet**.

**No API key. No account. No subscription.** Buy one current answer in USDC when a workflow needs it. The catalog includes agent-readiness audits, vendor onboarding risk, transaction preflight, live x402 opportunity research, company intelligence, endpoint verification, website due diligence, VIN safety, market checks, security research, and atomic EVM reads.

Every billable route accepts `?preview=true`. The preview is a live contract proof showing the source, freshness, required inputs, and response shape. It deliberately withholds the decision-ready values delivered by the paid call.

Start with the free `find_marketplace_products` MCP tool. Give it the buyer's task in plain language and it returns three ranked live products plus one `recommended_purchase` containing the exact price, required inputs, and ready preview and paid-call payloads. Replace the example inputs with the buyer's real values, preview when available, and only use the paid call after the user authorizes the listed price and payment method.

## Try it without a wallet

[Open a live Shopify catalog preview](https://ai-data-marketplace-1042299154756.us-central1.run.app/api/v1/shopify_store_lookup?domain=smallcrewmerch.com&preview=true&utm_source=github&utm_campaign=readme-free-preview). It runs the public source and shows the response contract; the complete catalog result remains behind the 0.01 USDC payment gate. No account, key, or payment is needed for the preview.

To try the MCP adapter in an existing client, [copy the two-tool configuration](examples/mcp-client.json) and ask your agent: “Find a tool to check a public Shopify storefront. Show me its price and free preview; do not pay.” Compact mode keeps the full catalog behind two tools. The [free integration check](examples/README.md) shows the same discovery and preview path end to end.

The store publishes [live, deduplicated settlement totals](https://ai-data-marketplace-1042299154756.us-central1.run.app/api/v1/settlement_metrics?days=90) that separate external payments from owner-controlled tests. Paid API calls demonstrate use of the store; they are **not** a count of unique people or proof that each buyer installed this MCP package. npm download counts also include automated installs.

## Engineering overview

This repository contains the open-source MCP buyer adapter and client. The marketplace backend is a separate service.

```mermaid
flowchart LR
    A[MCP client] --> B[Local adapter]
    B --> C[OpenAPI discovery and free previews]
    B --> D[Opt-in capped payment]
    D --> E[Marketplace endpoint]
    E --> F[Result and settlement details]
```

The adapter derives tools from the service's OpenAPI contract, keeps signing keys local, and rejects disabled, conflicting, malformed, and over-cap payment requests. Inspect [payment flow](PAYMENT_FLOW.md), [client examples](examples/README.md), and [automated verification](#verification-and-engineering-scope).

## Install

```bash
npx -y dopaminedesk-ai-data-marketplace-mcp
```

Use it from any stdio-compatible MCP client:

```json
{
  "mcpServers": {
    "dopaminedesk-data-marketplace": {
      "command": "npx",
      "args": ["-y", "dopaminedesk-ai-data-marketplace-mcp"]
    }
  }
}
```

Official MCP Registry name: `io.github.jblaz6335/ai-data-marketplace`.

### Small tool list for existing agents

Set `X402_TOOL_MODE=compact` to expose just `find_marketplace_products` and `purchase_marketplace_product`. All live products remain available through those two tools. The default `full` mode keeps the product-specific tools for existing integrations.

No environment variable or wallet key is required to start the default server. A wallet is needed only if the buyer chooses locally signed auto-pay. The remote `/mcp` URL is a separate authenticated publisher integration, not the public stdio install URL.

Ready-to-copy configurations and a free end-to-end client check are in [examples/README.md](./examples/README.md). The check discovers a real product and requests its free preview. It never signs or submits a payment.

## Buy with credits instead of configuring a wallet

The service is already indexed in APIHub's external x402 catalog. Buyers with APIHub credits can ask its proxy to sign and settle a marketplace call without keeping a Base wallet or gas in the calling process:

```bash
npx @apihubio/cli register
npx @apihubio/cli topup 5
npx @apihubio/cli call https://ai-data-marketplace-1042299154756.us-central1.run.app/api/v1/evm_block_number
```

APIHub is an independent third party with its own account, credit, markup, and terms. Direct x402 remains the self-custody path. Both routes settle the protected endpoint before its paid result is delivered.

## Inspect a live contract

```bash
curl "https://ai-data-marketplace-1042299154756.us-central1.run.app/api/v1/company_intelligence?preview=true&domain=example.com"
```

The proof includes source, freshness, request parameters, top-level fields, response shape, and a purchase block. Decision-ready values remain in the paid result.

## Optional one-call purchasing

The current npm release can complete the x402 challenge, authorization, retry, and settlement automatically. Install the public package directly:

```bash
npx -y dopaminedesk-ai-data-marketplace-mcp
```

The buyer key stays inside the local MCP process and is never sent to the marketplace. Use a dedicated low-balance Base wallet, not a primary wallet.

```json
{
  "mcpServers": {
    "dopaminedesk-data-marketplace": {
      "command": "npx",
      "args": ["-y", "dopaminedesk-ai-data-marketplace-mcp@2.11.3"],
      "env": {
        "X402_AUTO_PAY": "true",
        "X402_EVM_PRIVATE_KEY": "YOUR_DEDICATED_BUYER_WALLET_KEY",
        "X402_MAX_PAYMENT_USDC": "0.25"
      }
    }
  }
}
```

Call a product with `auto_pay: true`. The adapter refuses disabled, conflicting, invalid, or over-cap purchases. It never falls back to an uncapped payment.

For automated client installation, see [`llms-install.md`](./llms-install.md). Its default configuration exposes free discovery and previews without collecting a wallet key or enabling automatic payment.

## Verification and engineering scope

The [public verification hub](https://ai-data-marketplace-1042299154756.us-central1.run.app/verification) and [machine verification record](https://ai-data-marketplace-1042299154756.us-central1.run.app/.well-known/marketplace-verification.json) expose the production evidence.

I built this adapter around these constraints:

- the production OpenAPI contract is the source of truth for tool discovery;
- live contract proofs verify the source and schema without replacing the paid product;
- automatic purchasing is opt-in, locally signed, and protected by a hard per-call cap;
- conflicting, malformed, disabled, and over-cap payment attempts fail closed;
- settlement details stay attached to the delivered result for reconciliation.

Run the verification suite locally:

```bash
npm ci
npm test
```

## Production contracts

- **Store:** https://ai-data-marketplace-1042299154756.us-central1.run.app/
- **OpenAPI:** https://ai-data-marketplace-1042299154756.us-central1.run.app/openapi.json
- **Postman:** https://ai-data-marketplace-1042299154756.us-central1.run.app/postman.json
- **LLM manifest:** https://ai-data-marketplace-1042299154756.us-central1.run.app/llms.txt
- **x402 manifest:** https://ai-data-marketplace-1042299154756.us-central1.run.app/.well-known/x402
- **x402scan:** https://www.x402scan.com/server/8dd63536-ba25-40f4-b36a-7d05ed18d007

The MCP adapter builds its tool list from the production OpenAPI document. Counts, prices, availability, data mode, and source declarations come from the live contract instead of a hand-written endpoint list.

Every billable product uses x402 v2 exact payments on Base mainnet through the Coinbase CDP facilitator:

1. Call the endpoint and read the base64 `PAYMENT-REQUIRED` response header.
2. Sign the exact authorization with a compatible x402 buyer client.
3. Retry with `PAYMENT-SIGNATURE`.
4. Read settlement details from `PAYMENT-RESPONSE`.

See [PAYMENT_FLOW.md](PAYMENT_FLOW.md) for the manual and legacy confirmed-transaction paths.

## Buyer-ready outcomes

| Product | What the paid call delivers | Price (USDC) |
| :--- | :--- | :--- |
| [`shopify_store_lookup`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/shopify_store_lookup?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Current public Shopify products, variants, prices, and availability | **0.010** |
| [`ssl_certificate`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/ssl_certificate?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Live certificate authorization, issuer, expiry, and fingerprint | **0.010** |
| [`stock_research_brief`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/stock_research_brief?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Current market quote joined with recent official SEC filing metadata | **0.010** |
| [`storefront_intelligence_report`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/storefront_intelligence_report?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Public Shopify catalog, availability, TLS, and declared agent-commerce evidence in one report | **0.030** |
| [`agent_readiness_audit`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/agent_readiness_audit?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Scored evidence and prioritized repairs for the discovery files agents use to find, understand, and buy from a site | **0.025** |
| [`evm_receipt`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/evm_receipt?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Live transaction status, gas use, contract creation details, and normalized event logs across Base, Ethereum, or Arbitrum | **0.003** |
| [`evm_block_number`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/evm_block_number?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Current block height from a supported EVM network without maintaining an RPC integration | **0.001** |
| [`vendor_risk_report`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/vendor_risk_report?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Vendor onboarding decision with current identity, sanctions, domain, TLS, hosting, and website evidence | **0.020** |
| [`x402_market_opportunity_report`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/x402_market_opportunity_report?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Live x402 demand, competition, health, pricing, and build recommendation | **0.010** |
| [`transaction_preflight`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/transaction_preflight?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Read-only transaction simulation evidence before signing | **0.005** |
| [`company_intelligence`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/company_intelligence?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Company enrichment and vendor research brief | **0.010** |
| [`x402_endpoint_preflight`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/x402_endpoint_preflight?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | x402 endpoint verification, challenge linting, and buyer compatibility evidence | **0.003** |
| [`website_due_diligence`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/website_due_diligence?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Website trust, security, metadata, and risk evidence in one report | **0.040** |
| [`vehicle_safety_report`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/vehicle_safety_report?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | VIN decode, recall, complaint, and buyer safety evidence | **0.008** |
| [`crypto_market_snapshot`](https://ai-data-marketplace-1042299154756.us-central1.run.app/products/crypto_market_snapshot?utm_source=github&utm_medium=readme&utm_campaign=buyer_outcomes) | Current multi-asset pricing and market context | **0.004** |

These are complete paid deliverables, not teaser text. The lower-level catalog remains available for workflows that need a single chain read, filing, sanctions check, quote, or verification result.

If this open-source buyer adapter saves you integration work, you can [support its maintenance on Ko-fi](https://ko-fi.com/C2A325JGKN/).

## Published distribution

- [npm package](https://www.npmjs.com/package/dopaminedesk-ai-data-marketplace-mcp)
- [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jblaz6335%2Fai-data-marketplace)
- [Smithery](https://smithery.ai/server/jblaz6335/dopaminedesk-agent-data-arcade)
- [x402scan](https://www.x402scan.com/server/8dd63536-ba25-40f4-b36a-7d05ed18d007)

## License

MIT License. Open-source MCP buyer adapter and marketplace client.