aimarket-hub 3.0.0

AI Market Federation Hub — crawl, index, search, and route AI capabilities across the network

AIMarket Hub

Ecosystem: AICOM overview & live demos · Package version: 3.0.0 (pyproject)

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
Well-known	/.well-known/ai-market.json
Plugin demo	/plugins/demo
Widget demo	/widget/demo
Plain-language value	docs/value.md

---

Table of contents

• Overview
• Architecture
• Repository layout
• Quick start
• Core API
• Invoke lifecycle
• Plugin ecosystem
• Federation
• Payments
• 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

Killer feature — 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 killer features

---

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

pip install aimarket-hub
# optional core plugins (TEE, channels, reputation, safety, MCP packager):
pip install "aimarket-hub[plugins]"
aimarket serve
# → http://localhost:9083

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'

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	/ai-market/v2/manifest	Ed25519-signed capability catalog
GET	/ai-market/v2/search	NL federated search (intent, budget, category)
POST	/ai-market/v2/invoke	Invoke capability (plugin hooks, safety gate)
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
POST	/ai-market/v2/federation/crawl	Trigger BFS crawl of seed peers
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

OpenAPI: /docs when AIMARKET_OPENAPI=1. 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

---

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

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

Deep dive: ../docs/FEDERATION_HUB_REPORT.md

---

Payments

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

  User->>Chain: deposit USDT
  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->>Chain: settle spent + refund remainder

Field	Default	Notes
Chain	Base (L2)	AIMARKET_PAYMENT_CHAIN
Token	USDT	AIMARKET_PAYMENT_TOKEN
Recipient	env required	AIMARKET_PAYMENT_RECIPIENT

Protocol principle: no custody — channels are on-chain constructs; hub holds ledger state only.

---

Configuration

Variable	Default	Description
AIMARKET_HUB_NAME	AIMarket Hub	Display name in manifests
AIMARKET_HUB_URL	http://localhost:9083	Public URL (receipts, well-known)
AIMARKET_PAYMENT_CHAIN	base	Settlement chain
AIMARKET_PAYMENT_TOKEN	USDT	Settlement token
AIMARKET_PAYMENT_RECIPIENT	—	Required in production
AIMARKET_CRAWL_INTERVAL_S	3600	Federation crawl period
AIMARKET_ROUTING_FEE_BPS	100	Routing fee (1% = 100 bps)
AIMARKET_SEED_LIST	—	Comma-separated peer .well-known URLs
AIMARKET_PLUGIN_WHITELIST	—	Restrict loaded plugins
DATABASE_URL	SQLite file	PostgreSQL for production

---

Deployment

Production reference: ../docs/production-modelmarket-dev.md

Checklist item	Action
TLS	Terminate at nginx / Caddy → hub container
Secrets	AIMARKET_PAYMENT_RECIPIENT, DB URL via env — not in git
Factory sync	Cron or webhook → sync_pipeline_mirror_and_hub.py
Plugins	pip install desired plugins before aimarket serve
Health	GET /.well-known/ai-market.json + /ai-market/v2/stats/live

---

Testing & coverage {#testing--coverage}

CI runs on every push (workflow); coverage badge is refreshed from pytest --cov on main.

cd aimarket-hub
pip install -e ".[dev]"
pytest tests/ -q --cov=aimarket_hub

Development

pip install -e ".[dev]"

Key test modules: test_api.py, test_crawler.py, test_plugin_system.py, test_channels.py, test_cross_hub_integration.py

Add a plugin: create package under ../plugins/ with pyproject.toml entry point aimarket.plugins.

---

Security

• SSRF protection on federation crawler (crawler.py)
• Signed manifests — Ed25519 (signing.py)
• Safety gate on every invoke (safety_gate.py)
• Vulnerability reports: SECURITY.md → [e-mail]

---

Related projects

Project	Relationship
AICOM / AI-Factory	Ships products → hub index
aimarket-protocol	Normative v2 spec
aimarket-sdks	Client SDKs (Dart alpha)
aimarket-widget	Embeddable UI
oracles	Verifiable math capabilities — randomness, VDF, consensus, reputation (listed on hub)
desktop-integrations	8 Flutter consumer apps
Ecosystem architecture	Full monorepo diagram

---

License

Apache-2.0 — see LICENSE. Maintainers: CONTRIBUTORS.md.