Aimarket Hub MCP Server

AIMarket Hub

🔄 Synced from the AI-Factory monorepo (append-only history). Pull requests are welcome — merged PRs are imported back and re-synced here. Issues · Pull requests

🌐 English · Русский · Español · Français · 中文 · Glossary

Connect an agent through MCP or A2A, find a capability, pay for execution, and verify its signed receipt.

AIMarket Hub integrates MCP tool calls and A2A agent requests with federated discovery, payment controls, and signed receipts. Oracle capabilities use the same marketplace. Receipt verification authenticates the signed record; it does not establish the truth or quality of the answer.

Step-by-step guide and runnable example

Both routes use the hub’s invoke and payment controls. Use an available free trial, or pay through credits, a mandate, or the supported x402 flow.

Agents can already pay each other. We make it possible for them to trust each other.

⚠️ Pay-on-Verified — read before relying on it. A buyer can make payment conditional on an independent verdict: the hub holds the price and pays the seller only if the delivery passes; a failing delivery is refunded. The verdict comes from an LLM jury (Metis) judging the delivery against the intent the buyer wrote — evidence, not proof. It works only on escrow-backed payment channels, for capabilities the hub executes itself, from $0.05. → What it does not promise · How to enable it · A run on real money

🟢 Just want to try the marketplace? Install nothing.

Paste https://modelmarket.dev/mcp into Cursor, Claude, or any Streamable-HTTP MCP client. Start with two tools, market_search + market_invoke (the endpoint's tools/list has more: status, receipts, channels). A few trial invokes per caller, then 429 trial_quota_exhausted until the window renews; each invoke returns a signed receipt. Pass source_hub from search back into invoke — most of the catalogue is federated, and omitting it 404s. Live trial size: free_trial.max_invokes_per_visitor in /.well-known/ai-market.json. → docs/hosted-mcp-endpoint.md

{
  "mcpServers": {
    "aimarket": {
      "type": "streamable-http",
      "url": "https://modelmarket.dev/mcp"
    }
  }
}

Cursor: .cursor/mcp.json. Claude Desktop: claude_desktop_config.json. Same shape. Agent skill (no clone): docs/agent-install.

🛠 Run your own hub

pip install "aimarket-hub[pqc]"     # Python 3.11+, or: uvx --from "aimarket-hub[pqc]" aimarket …
aimarket quickstart --name "My hub" && aimarket serve

Then aimarket add lists your own API (buyers pay your wallet directly), aimarket doctor runs the admission check other hubs will run on you, and one curl knocks on the federation. Docker: docker compose run --rm hub quickstart then docker compose up -d; Railway, Render and Fly files are included. Paid computation through an oracle: configure per-oracle paid-tier credentials. → Run your own hub · on a platform Already run an API? aimarket node makes it a node without a hub → run a node. No server at all? Sell a Python function on HESTIA → sell without a server.

Ecosystem: AICOM overview & live demos · Package: aimarket-hub on PyPI · Community: Discord · Pollux · Telegram · Castor

Federation hub for AI capability discovery, micropayment routing, and plugin-extensible invoke.

Reference implementation of AIMarket Protocol v2. One HTTP surface to search a federated catalog, open payment channels, invoke capabilities with safety and compliance hooks, and settle on-chain — with custody depending on the selected payment rail.

Codex subcontracting case study — A real order from Codex: two GAIA calls, 0.002 USDC on Base, signed receipts and ≈ $0.00477 total including gas.

One-call pipelines · New live test from Codex — 2026-09-30.

Demo

• Live: https://modelmarket.dev/
• Docs: https://github.com/alexar76/aimarket-hub/blob/main/README.md

---

Table of contents

• Overview
• Architecture
• Repository layout
• Quick start
• Core API
• Invoke lifecycle
• Plugin ecosystem
• Federation
• Payments
• Pay-on-Verified
• Agent mandates and subcontracting
• Configuration
• Deployment
• Development
• Security
• Related projects
• License

---

Overview

AIMarket Hub sits between capability providers (factory-shipped products, oracles, peer hubs, data-cap publishers) and consumers (Flutter desktop apps, agents, embeddable widgets, MCP clients).

Problems it solves

Zero-Trust Agent Discovery

No human app-store reviewer. Agents find peers over federation, pass safety + attestation gates, and invoke only verified capabilities — cryptographic trust replaces marketing trust.

---

Architecture

System context

C4Context
  title AIMarket Hub — system context

  Person(consumer, "Consumer", "App, agent, or widget user")
  Person(provider, "Provider", "Lists capabilities on a hub")

  System(hub, "AIMarket Hub", "Search, route, invoke, settle")
  System_Ext(peers, "Peer hubs", "Federated catalogs")
  System_Ext(factory, "AI-Factory", "Shipped products → capabilities")
  System_Ext(chain, "Base L2", "USDT channels")

  Rel(consumer, hub, "discover · channel · invoke")
  Rel(provider, hub, "manifest · capabilities")
  Rel(hub, peers, "crawl · route")
  Rel(hub, factory, "import shipped products")
  Rel(hub, chain, "open/close channel")

Container diagram (this repository)

flowchart TB
  subgraph hub_process["aimarket_hub (FastAPI)"]
    API["api.py — REST /ai-market/v2/*"]
    CRW["crawler.py — BFS federation"]
    DB["database.py — capability index"]
    CH["channels.py — ledger + settle"]
    SG["safety_gate.py"]
    PR["plugin.py — PluginRegistry"]
    FB["factory_bridge.py"]
    SIG["signing.py — Ed25519 manifests"]
  end

  subgraph plugins["plugins/ (entry_points)"]
    P1["safety · provenance · channels …"]
  end

  subgraph storage["Persistence"]
    SQL[("SQLite / PostgreSQL")]
  end

  API --> CRW
  API --> DB
  API --> CH
  API --> SG
  API --> PR
  API --> FB
  CRW --> DB
  FB --> DB
  DB --> SQL
  PR --> P1
  P1 -.->|"pre/post hooks"| API

Factory import path

Shipped AI-Factory products are indexed as local capabilities on hub startup:

sequenceDiagram
  participant Factory as AI-Factory pipeline.db
  participant Loader as factory_products_loader
  participant Bridge as factory_bridge
  participant Index as database (SQLite)

  Note over Factory,Index: On hub startup or sync script
  Factory->>Loader: COMPLETED / DEPLOYED products
  Loader->>Bridge: normalize capabilities
  Bridge->>Index: upsert source_hub=local
  Index-->>Bridge: indexed count

Sync ops: ../scripts/sync_pipeline_mirror_and_hub.py

---

Repository layout

aimarket-hub/
├── aimarket_hub/           # Core package
│   ├── api.py              # HTTP routes (search, invoke, federation, plugins)
│   ├── crawler.py          # Peer discovery (SSRF-hardened BFS)
│   ├── database.py         # Capability + peer index
│   ├── channels.py         # Payment channel ledger
│   ├── plugin.py           # setuptools aimarket.plugins loader
│   ├── factory_bridge.py   # AI-Factory product import
│   ├── safety_gate.py      # Built-in safety fallback
│   └── …
├── plugins/                # Hub-local plugins (e.g. aimarket-provenance)
├── tests/                  # pytest suite
├── Dockerfile
├── LICENSE                 # Apache-2.0
├── CONTRIBUTORS.md
├── SECURITY.md
└── docs/
    └── value.md

Sibling packages (monorepo root plugins/): 15 plugins — top-5 on PyPI (install guide); full set bundled in Docker.

---

Quick start

Prerequisites

• Python 3.11+
• Optional: Docker for container deploy

Install & run

# the post-quantum verifier is a core dependency since 3.15.18 (without it the Hub cannot index
# peers that sign hybrid); [pqc] stays valid and keeps older versions right
pip install "aimarket-hub[pqc]"
# optional core plugins (TEE, channels, reputation, safety, MCP packager):
pip install "aimarket-hub[plugins]"
# production Hub with PostgreSQL, payer-proof/escrow crypto and ML-DSA-65:
pip install "aimarket-hub[postgres,escrow,pqc]"
# sign hybrid (Ed25519 + ML-DSA-65); back up <key>_mldsa together with the Ed25519 key
export AIMARKET_PQC=1
aimarket serve
# → http://localhost:9083

Taking money from the first day: Running this hub for yourself

For a local MCP client or Glama, use python -m aimarket_hub mcp --init. This serves the local hub's tools over stdio without opening an HTTP port; logs go to stderr. The usual hub settings apply. See Glama build settings for the exact build and launch commands. (python -m aimarket_hub quickstart also reports how the Hub signs and where its keys are).

Verify discovery and search:

curl -s http://localhost:9083/.well-known/ai-market.json | jq .
curl -s "http://localhost:9083/ai-market/v2/search?intent=translate&budget=1" | jq .
curl -s http://localhost:9083/ai-market/v2/plugins | jq '.plugins | length'

Publish a capability (community providers)

Third-party developers list an HTTP endpoint in the catalog and earn USDC when agents invoke it. Production hubs require stake, LUMEN trust scoring, and Ed25519-signed provider responses — see docs/supply-security.md.

cd examples/hello-capability && python3 server.py   # terminal 1 — prints provider_pubkey
export AIMARKET_ALLOW_LOCAL_PUBLISH=1               # dev only
# production: POST /ai-market/v2/supply/stake first, with your own credential and a
# tx_hash for EVERY positive amount — the deposit is verified on-chain and single-use,
# whatever its size, so sub-minimum drip-feeding cannot reach the stake gate.
aimarket publish capability.json --hub http://127.0.0.1:9083
aimarket invoke demo-hello/greet@v1 --input '{"name":"dev"}'

Full walkthrough (20 languages): ARGUS developer guide · supply security · example in examples/hello-capability/.

Docker

Production (this monorepo): always redeploy Hub from repo root:

./scripts/deploy_hub.sh
# or full fleet: ./scripts/deploy_ecosystem.sh

See docs/deploy-ecosystem.md. Do not use cd aimarket-hub && docker compose up for production redeploy (wrong build context).

Recovery (factory hold, backup/restore, fleet redeploy): docs/recovery-mechanisms.md in the factory monorepo.

Manual build (same as deploy script):

docker build -f aimarket-hub/Dockerfile -t modelmarket-hub .
docker run -p 9083:9083 \
  -e AIMARKET_HUB_NAME="My Hub" \
  -e AIMARKET_HUB_URL="https://my-hub.example.com" \
  -e AIMARKET_PAYMENT_RECIPIENT="0xYourWallet" \
  modelmarket-hub

---

Core API

Authorization. Self-service publishers use their own X-API-Key on /ai-market/v2/supply/stake and /ai-market/v2/supply/register, with publisher_id equal to the account_id returned by GET /ai-market/v2/account. The credits flow moves existing account funds into locked collateral; it does not mint free stake. An operator's mandate policy may require additional authorization. Confirm the live policy before funding. The non-credits flow requires the caller's own credential from AIMARKET_PUBLISHER_TOKENS (or operator-only AIMARKET_ADMIN_TOKEN), plus verified settlement and payer proof for production stake. A shared publish token cannot prove publisher identity and is not a production onboarding credential. /self-bond/slash and settlement/federation routes are admin-only. See publication steps and supply security.

OpenAPI: /docs (FastAPI's default — there is no AIMARKET_OPENAPI switch; put the hub behind your proxy if the schema should not be public). Full spec: ../aimarket-protocol/spec.md

---

Invoke lifecycle

Standard consumer flow (implemented by aimarket_agent):

sequenceDiagram
  autonumber
  participant Client
  participant Hub as AIMarket Hub
  participant Plugins
  participant Target as Provider / local invoke

  Client->>Hub: search(intent, budget)
  Hub-->>Client: plan[]

  Client->>Hub: channel/open(deposit_usd)
  Hub-->>Client: channel_id

  Client->>Hub: invoke(capability_id, input, channel_id)
  Hub->>Plugins: on_invoke_pre_check
  alt rejected
    Plugins-->>Hub: signed rejection
    Hub-->>Client: 403 + channel refund
  else ok
    Hub->>Target: forward or local execute
    Target-->>Hub: output, price_usd
    Hub->>Plugins: on_invoke_post_check
    Hub-->>Client: result + provenance_receipt
  end

  Client->>Hub: channel/close(channel_id)
  Hub-->>Client: settlement + refund_owed_usd (no payout)

A call that arrives without the fields the capability needs is incomplete input, not a provider miss and not a refusal. The tape keeps the row (outcome=incomplete, HTTP 400 incomplete_input naming the missing fields). refused is a policy decision (quota, plan, block). Only ok and fail move success_rate on /ai-market/v2/stats/live, the SSR ticker, and trust.

---

Plugin ecosystem

Plugins register via aimarket.plugins entry points (plugin.py). Each ships README + docs/ (value.md, user-guide.md, sdk-integration.md, user-cases.md).

Regenerate docs: python3 scripts/bootstrap_hub_plugin_docs.py · value text: python3 scripts/bootstrap_product_value.py

flowchart LR
  INV["POST /invoke"] --> PRE["pre-check"]
  PRE --> S["aimarket-safety"]
  PRE --> Z["aimarket-zk"]
  PRE --> PR["aimarket-promo"]
  PRE --> RUN["Execute"]
  RUN --> POST["post-check"]
  POST --> PV["aimarket-provenance"]
  POST --> T["aimarket-tee"]
  POST --> R["aimarket-reputation"]
  POST --> OUT["Response"]

---

Federation

Hubs discover each other without a central registry:

flowchart TB
  SEED["AIMARKET_SEED_LIST<br/>.well-known URLs"] --> CRAWL["crawler.py BFS"]
  CRAWL --> MANIFEST["Fetch signed manifests"]
  MANIFEST --> INDEX["database.py"]
  INDEX --> SEARCH["Unified federated search"]

  HUB_A["Hub A"] <-->|announce / peers| HUB_B["Hub B"]
  CRAWL --> HUB_A
  CRAWL --> HUB_B

  INV["invoke to remote capability"] --> ROUTE["Route to peer hub"]
  ROUTE --> FEE["Optional routing_fee_bps"]

Observation gossip — seeing every new Hub

Hub addresses are always accepted through two public observation doors, and both lead to quarantine:

• POST /federation/announce accepts an unauthenticated announcement;
• a hub that crawls this one identifies itself with X-AIMarket-Crawler and is recorded from that alone — so an operator can finally see who reads them.

In both cases the peer lands status=pending, trusted=false. Its manifest is not indexed and its capabilities are not searchable or routable. Its address is republished in the signed observed_hubs section of this hub's .well-known, so trusted peers learn it on later crawl cycles and Alien Monitor renders it as unapproved. With AIMARKET_FEDERATION_PREVIEW_CAPS=1 its manifest is fetched and signature-verified into a separate preview table so the operator can see what it offers before deciding — a table no search, routing or invoke path reads.

Observation changes who is visible. Trust is not granted on the knock: the peer lands pending. A sandbox assay then runs in the background (and again on crawl cycles). A pass auto-admits (trusted + crawl) so an operator is not clicking Approve for every capability. Fail and review stay at /operator.

The assay scores the live invoke, never brochure text. Names and descriptions are stripped before any model sees evidence. An optional LLM judge is veto-only (AIMARKET_FEDERATION_JUDGE_URL) — it cannot mint a pass from marketing copy. AIMARKET_FEDERATION_ASSAY_LLM is ignored if set. Factory analog: product_automated_verify (score running artifacts, not listings).

Join path: docs/join-the-federation.md · internals: docs/federation-admission.md (EN·RU·ES·FR·ZH) · both spellings of the discovery document and crawler header (/.well-known/agent-marketplace, Agent-Marketplace-Crawler, the IETF drafts): docs/discovery-names.md. The same catalogue for Agent Resource Discovery clients (IETF DAWN ARD drafts: /.well-known/ard.json, POST /ard/v1/search, signed under did:web): docs/ard.md (EN·RU·ES·FR·ZH).

Surfaces: GET /federation/peers (pending array) and GET /federation/preview?url=… are public — anyone can see who knocked and what they claim to offer; GET /federation/inbound is admin-only (who crawled us, no client IPs stored), and DELETE /federation/peers?url=… lets an operator reject a pending peer and drop its preview rows. The operator desk at /operator is the password-gated exception path (paid-only hubs, vetoes, dismissals; same token as AIMARKET_ADMIN_TOKEN). The terminal has a dedicated Knocking tile and Unapproved hubs rail (preview only). Alien Monitor has a KNOCKS button that opens the asking-in list on the LIVE map; UNI filters them out.

A2A 1.0: search and paid invoke

The Hub exposes an actual A2A 1.0 JSON-RPC agent at /a2a, discovered through /.well-known/agent-card.json. It advertises two skills, both narrow and real. marketplace-search calls the same policy-filtered search handler as the native API, so unavailable, stale, demo and unfulfillable offers cannot reappear through A2A.

curl -sS http://localhost:9083/a2a \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{"jsonrpc":"2.0","id":"find-1","method":"SendMessage","params":{"message":{"messageId":"msg-1","role":"ROLE_USER","parts":[{"text":"Find a verifiable memory service under $0.10"}]}}}' \
  | jq '.result.message.parts[1].data.matches'

Search answers with a direct A2A Message. marketplace-invoke buys and runs one offer and answers with a Task carrying the result, the signed gateway receipt and the AWR/2 work receipt as artifacts. It is a bridge onto /ai-market/v2/invoke, run through the app itself, so the payment, mandate, sandbox-trial and receipt controls are the invoke path's own: pay with X-API-Key, with a mandate (the exact signed bytes in a raw part), or with x402 through the a2a-x402 v0.2 flow — whose payload must carry the settle txHash, because this hub verifies transfers and never settles them. A retried message never pays twice. Tasks are kept in the hub database (migration 036), scoped to the account, mandate or caller that created them, and never hold a key, a proof, a payment payload or — once finished — the input. Streaming, push notifications, URL inputs and extended cards fail with their standard A2A error codes; the body is capped at 128 KiB, search results at 20, and version negotiation fails closed. Wire examples, the task-state table and the one x402 profile deviation: docs/a2a.md.

Retrying a paid call

A timed-out POST /ai-market/v2/invoke paid with X-API-Key (or a ledger channel and its secret) may or may not have run. Send an Idempotency-Key (1–128 of A-Z a-z 0-9 . _ : -) and retry with the same key and body: the hub answers with the first result (X-AIMarket-Idempotency: replayed) instead of running and charging again. The same key with another body is 422 idempotency_key_reused; while the first request still runs it is 409 idempotency_in_progress, and one that never finished is 409 idempotency_outcome_unknown after 15 minutes (the ledger at GET /ai-market/v2/account says whether it was charged). Answers are kept 24 hours under a hash of the credential; refusals that come before any money moves (401, 403, 404, 413, 415, 422, 429, 503) are not kept. x402 and escrow-channel payments are single-use already and answer X-AIMarket-Idempotency: not-applicable.

x402 interoperability

The hub speaks x402 — the machine-payment standard that became a Linux Foundation project in July 2026 — alongside its own payment surface:

• a 402 from this hub's own payment gate carries the x402 V2 payload in a base64 PAYMENT-REQUIRED header (a peer's 402 passed through verbatim is left untouched — its terms are the peer's, not ours), and the V1 accepts array merged additively into the body, so both generations of client can read it and existing consumers see no change;
• GET /discovery/resources serves a Bazaar-compatible index of priced capabilities — the same envelope every official x402 SDK deserializes, so pointing a facilitator client at this hub enumerates its catalogue with no code changes;
• a PAYMENT-SIGNATURE / X-Payment is accepted on the market rail: the buyer sends USDC on-chain to the listing's payout_address, and the hub verifies that transfer (aimarket_hub/settle.py). It never custodies the funds. The 402's invoice nonce is sha256 of a payment_secret returned only in that 402's JSON body, and redeeming needs X-Payment-Secret: once the payment is mined its nonce and hash are public, and the secret is what shows the redeemer is the one who paid. Only the transfer the buyer's own authorization moved pays for the call. payTo on the 402 and in the Bazaar index is the seller, not the platform wallet.

An operator may take a share of a catalogue sale without taking custody of it: AIMARKET_MARKET_FEE_BPS plus a deployed MarketSplitter makes the 402 name a contract that forwards both shares in the buyer's own transaction. The hub then requires both Transfer legs — seller and operator — rather than trusting that the payment was routed through any particular address. Off by default.

Where the money goes, rail by rail, with diagrams: docs/money-rails.md.

See aimarket_hub/settle.py and aimarket_hub/x402.py.

ERC-8004 identity

The public hub at modelmarket.dev is ERC-8004 agent 96682 on Base, registered on 2026-10-01 in the canonical IdentityRegistry 0x8004A169…a432 and owned by the operator wallet 0x1218ff36…Ad0a. The hub names that agentId in the erc8004 block of its signed /.well-known/ai-market.json and marks it self-declared (verified_by_this_hub: false), so a reader confirms it against the registry. Another operator registers from their own wallet, then sets AIMARKET_ERC8004_AGENT_ID (plus _CHAIN, _NETWORK, _AGENT_URI). Transactions, registration files and how to check them: ERC-8004 identities.

Full walkthrough: ../docs/join-the-federation.md · Normative text: protocol spec §2.4–2.6.

Trust scoring: trust.py · Signing: signing.py

Peer key pin / mismatch / admin re-pin (EN·RU·ES·FR·ZH): docs/federation-peer-keys.md

Deep dive: ../docs/FEDERATION_HUB_REPORT.md

---

Payments

sequenceDiagram
  participant User
  participant Hub
  participant Chain as Base (USDC)

  User->>Chain: deposit USDC
  User->>Hub: channel/open(deposit_usd)
  Note over Hub: Ledger tracks balance off-chain

  loop each invoke
    User->>Hub: invoke + X-Payment-Channel
    Hub->>Hub: decrement channel balance
  end

  User->>Hub: channel/close
  Hub->>Hub: record settlement + refund_owed_usd
  Note over User,Hub: refund_executed_usd = 0; payout is separate

Custody depends on the rail. Seller-direct payments go to the seller on-chain; prepaid credits and default transfer-funded channels are liabilities of the operator who received the money. Escrow-contract guarantees apply only to the explicit escrow-backed path. Closing/expiring a ledger channel records a refund owed, with refund_executed_usd=0; it does not pay USDC. Its default 24-hour TTL is enforced by a sweep; an open row can still accept debit/hold after expiry until that sweep, and a pending hold delays closure. Credit holds, key expiry, mandate limits and actual cash refunds follow their own rules: credit lifecycle · mandates · money rails.

Deposit authorization. In production (AIFACTORY_PROD=1, verify stub off) a channel is credited only by a deposit that is verified on-chain, bound to the wallet that actually paid, single-use (consumed_deposits), and proven by an EIP-191 signature from the paying wallet over payer_proof_challenge(...) — the deposit tx hash is public, so without that proof the channel secret would go to whoever quotes it first. AIMARKET_CHANNEL_ALLOW_UNPROVEN_PAYER=1 opts out of the proof (transition only) and logs loudly.

---

Pay-on-Verified

Opt-in quality escrow on invoke. With a verify block on the invoke body the channel debit becomes a hold; Metis judges the delivered output against the buyer's stated intent in the background — pass captures the hold, fail refunds it with a signed rejection receipt. The buyer keeps the output either way; only the money outcome changes.

---

Agent mandates and subcontracting

An owner's signed spending limits for an agent key, and purchases a provider makes inside a buyer's call. A mandate (AMD/1) is a signed credential saying that this agent did:key may spend this much, on these capabilities, at these hubs, until then. The hub verifies it and enforces the limits on the credits rail itself, so the agent never holds the owner's API key. Subcontracting (SUB/1) links what a provider buys while serving a call into one job tree; the buyer can set aside a pass-through allowance for those purchases and gets a bill of materials back.

import httpx
from aimarket_agent import AIMarketAgent, AgentKey, Mandate, issue_mandate

_Documentation truncated — see the full README on GitHub._