aimarket-hub

📖 Read-only mirror. aimarket-hub is published from the canonical AI-Factory monorepo. Pull requests are not accepted — any commit pushed here is overwritten by scripts/mirror_satellites.sh on the next sync. 🐞 Found a bug or have a request? Please open an issue.

AIMarket Hub

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

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. Two tools: market_search + market_invoke. A few trial invokes per caller, then 402; 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.

Ecosystem: AICOM overview & live demos · Package version: 3.5.4 (pyproject) · 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 — without custodial wallets.

Live hub	modelmarket.dev
MCP	https://modelmarket.dev/mcp
Agent skill	docs/agent-install
Well-known	/.well-known/ai-market.json
Plugin demo	/plugins/demo
Widget demo	/widget/demo
Plain-language value	docs/value.md

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

Problem	Hub answer
Fragmented AI APIs	Federated search over .well-known/ai-market.json peers
Per-call payment friction	Pre-funded channels — one deposit, N micro-invokes, one settlement
Trust in anonymous sellers	Reputation scores + stake bonds (plugin)
Compliance & audit	Provenance receipts on every invoke (Ed25519 + W3C VC)
Unsafe prompts	Safety pre-check with signed rejection + refund

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.

What	Federated discover → safety / reputation / TEE plugins → routed invoke
Why	Scales to millions of micro-capabilities; malicious listings can’t drain channels
Deep dive	docs/killer-feature-zero-trust-discovery.md · Ecosystem capabilities

---

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 (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

Method	Path	Description
GET	/.well-known/ai-market.json	Root discovery — chain, token, peers, signer key
GET	/.well-known/mcp/server-card.json	MCP server card (SEP-1649 / Smithery fallback)
GET	/llms.txt	Short agent-readable Hub + MCP door
GET / POST	/mcp	Hosted MCP — GET info; POST Streamable-HTTP (market_search, market_invoke)
GET	/.well-known/agent-card.json	A2A 1.0 Agent Card (cacheable + ETag)
POST	/a2a	A2A 1.0 JSON-RPC: marketplace search, paid invoke as Tasks, GetTask/ListTasks/CancelTask (docs/a2a.md)
GET	/ai-market/v2/manifest	Hybrid Ed25519 + ML-DSA-65 capability catalog when PQC is enabled
GET	/ai-market/v2/search	NL federated search (intent, budget, category)
POST	/ai-market/v2/supply/stake	Deposit publisher stake (unlock community publish)
POST	/ai-market/v2/supply/register	Publish community capability + invoke_url
POST	/ai-market/v2/invoke	Invoke capability (plugin hooks, safety gate)
POST	/ai-market/v2/receipts/verify	Verify a receipt against this Hub's pinned live Ed25519 + ML-DSA-65 identities
POST	/ai-market/v2/channel/open	Open pre-funded payment channel
POST	/ai-market/v2/channel/close	Close channel — settle + refund remainder
POST	/ai-market/v2/federation/announce	Peer hub announcement
GET	/ai-market/v2/federation/peers	Known peers + trust scores + pin status (key_mismatch)
GET	/ai-market/v2/federation/assay	Last sandbox scorecard (pass auto-admits by default)
POST	/ai-market/v2/federation/assay	Admin: re-run SSRF / signature / sandbox assay
POST	/ai-market/v2/federation/crawl	Trigger BFS crawl of seed peers
POST	/ai-market/v2/federation/peers/approve	Admin: toggle peer trusted (anti-TOFU)
POST	/ai-market/v2/federation/peers/repin	Admin: rotate a sticky peer pin after legitimate key change
GET	/ai-market/v2/plugins	Loaded plugin catalog
GET	/ai-market/v2/reputation/{hub_url}	Trust score breakdown
GET	/ai-market/v2/stats/live	Real-time invocation feed

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 + unused balance

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"]

Plugin	Category	One-line value
aimarket-provenance	compliance	Cryptographic receipt per AI output
aimarket-safety	security	Block jailbreak / injection before billing
aimarket-reputation	reputation	Stake-backed trust scores
aimarket-channels	infrastructure	Off-chain ledger, on-chain settlement
aimarket-tee	security	Hardware attestation (Nitro / TDX)
aimarket-auction	monetization	Spot bidding for scarce slots
aimarket-personas	tooling	Buyer-friendly agent personas
aimarket-streaming	monetization	SSE + per-token micro-billing
aimarket-nft	monetization	Transferable prepaid credit NFTs
aimarket-mcp-packager	tooling	MCP bundle for Claude Desktop
aimarket-orchestrator	monetization	NL task → capability chain planner
aimarket-data-cap	monetization	Private corpus → paid search
aimarket-promo	monetization	Signed time-locked discounts
aimarket-dataset	tooling	Weekly anonymized demand corpus
aimarket-zk	security	ZK proofs without revealing input

---

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).