AIMarket Hub

Mirror — read-only. The canonical source for aimarket-hub lives in the AI-Factory monorepo. Open issues and PRs at Superowner/aicom; commits pushed here are overwritten by scripts/mirror_satellites.sh on the next sync run. See docs/repository-canonical-policy.md for the policy.

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

Overview

AIMarket Hub sits between capability providers (factory-shipped products, 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/): 14 pip-installable plugins copied into the hub Docker image.

Quick start

Prerequisites

Python 3.11+
Optional: Docker for container deploy

Install & run

pip install aimarket-hub
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 → security@aicom.io

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
desktop-integrations	8 Flutter consumer apps
Ecosystem architecture	Full monorepo diagram

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
aimarket_hub		aimarket_hub
docs		docs
nginx		nginx
plugins/aimarket-provenance		plugins/aimarket-provenance
scripts		scripts
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
USER_GUIDE.md		USER_GUIDE.md
docker-compose.yml		docker-compose.yml
plugins-demo.html		plugins-demo.html
plugins.json		plugins.json
pull_request_template.md		pull_request_template.md
pyproject.toml		pyproject.toml
terminal-home.html		terminal-home.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AIMarket Hub

Table of contents

Overview

Killer feature — Zero-Trust Agent Discovery

Architecture

System context

Container diagram (this repository)

Factory import path

Repository layout

Quick start

Prerequisites

Install & run

Docker

Core API

Invoke lifecycle

Plugin ecosystem

Federation

Payments

Configuration

Deployment

Testing & coverage {#testing--coverage}

Development

Security

Related projects

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

AIMarket Hub

Table of contents

Overview

Killer feature — Zero-Trust Agent Discovery

Architecture

System context

Container diagram (this repository)

Factory import path

Repository layout

Quick start

Prerequisites

Install & run

Docker

Core API

Invoke lifecycle

Plugin ecosystem

Federation

Payments

Configuration

Deployment

Testing & coverage {#testing--coverage}

Development

Security

Related projects

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages