📖 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

Ecosystem: AICOM overview & live demos · Package version: 3.2.1 (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.

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

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'

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. /supply/register takes the shared AIMARKET_PUBLISH_TOKEN. The routes that move or encumber stake — /supply/stake and /self-bond/register — take the caller's OWN credential from AIMARKET_PUBLISHER_TOKENS (or AIMARKET_ADMIN_TOKEN), because a shared token cannot prove which publisher is calling; in production a hub with neither configured refuses them with 503. /self-bond/slash and every settlement/federation route are admin-only.

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

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

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

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

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

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.

Configuration

Every default below is the value the code falls back to today; where a default is derived from another variable, the rule is spelled out rather than a number.

Core

Databases

Upgrading past the shared-database aliasing

This is a one-time migration step for any hub that already ran with AIMARKET_DB_PATH set — which includes every container here (Dockerfile, Dockerfile.standalone, docker-compose.yml, docker-compose.core.yml all export it).

Until this release the env var overrode the path a subsystem asked for, so the channel ledger (data/channels.db) and the provenance store (data/provenance.db) were created inside the hub file. Now that the explicit argument wins, those subsystems open their own files — and on an upgraded deployment those files start empty:

• the channel ledger loses its open channels and, more seriously, consumed_deposits — the table that makes an on-chain deposit single-use. An empty one lets every deposit already spent be replayed into a new funded channel;
• the provenance store loses its receipts.

The hub logs this at ERROR on startup (the requested file does not exist while the AIMARKET_DB_PATH file does), naming the file the data is still in. Do one of these before serving traffic:

# A. channel ledger — keep the shared file, no data moves, pre-upgrade behaviour exactly
export AIMARKET_CHANNELS_DB_PATH="$AIMARKET_DB_PATH"

# B. channel ledger — split it out: copy the file with the hub stopped
cp /app/data/hub.db /app/data/channels.db
export AIMARKET_CHANNELS_DB_PATH=/app/data/channels.db

Either way the tables the copy's owner does not use are simply never read. The provenance store has no path variable — it always derives provenance.db from the hub database's directory — so B is the only option there (cp /app/data/hub.db /app/data/provenance.db); skipping it starts an empty receipt store, which costs an audit trail but no money.

DATABASE_URL deployments are unaffected — PostgreSQL was always one shared database.

Channels

Pay-on-Verified

Supply security (community publishers)

Full model: docs/supply-security.md. A non-finite or non-numeric value in any threshold below is ignored with a warning and the documented default is used — a nan threshold would otherwise silently disable the gate it configures.

Deployment

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

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)
• Verified, single-use stake deposits — in production every stake credit needs an on-chain deposit that pays the platform recipient, and the hash is burned by an atomic claim before the credit, so one deposit can never fund two publishers even under concurrent requests. The claim is keyed on the canonical transaction id (an EVM hash is case-insensitive at the JSON-RPC layer, so 0xAB… and 0xab… are one deposit, not two) (supply_security.py)
• Residual — stake deposits are not payer-bound. The stake verifier answers "did somebody pay the platform?", not "did this publisher pay", so whoever submits a matching hash first gets the credit. Binding it needs a publisher→wallet record the stake ledger does not yet have; channel deposits are already bound (see the entry below). Until then, treat a stake deposit hash as a bearer secret and submit it before it is public
• Single-use channel deposits + payer proof — a verified deposit funds exactly one channel and only for the wallet that signed for it (channels.py)
• Stake mutation is per-subject, slashing is operator-only — a shared token can neither credit a stranger's stake nor burn a rival's bond (api.py)
• Vulnerability reports: SECURITY.md → alexar76@rambler.ru

Related projects

Community

The DIOSCURI twins answer questions from synced GitHub docs.

Ecosystem map: Alien Monitor · AICOM

License

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