📖 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

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

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

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.

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.

Accepting an x402 PAYMENT-SIGNATURE is deliberately not implemented: that means verifying and settling an EIP-3009 authorization, and moving money is not a change that should ride along with a discovery change. See aimarket_hub/x402.py.

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

Start here: complete production deployment runbook. It is also available in Russian, Spanish, French and Chinese.

The runbook covers immutable commit-pinned releases, unprivileged systemd services, nginx/TLS on a hostname or /hub subpath, same-origin federation discovery and invoke, signed-manifest and real 402 assay evidence, protocol-only federation admission, UFW/Fail2ban/SSH hardening, backups, reboot acceptance, Alien Monitor and SKOPOS enrollment. Do not expose the provider backend or replace the Hub's Ed25519 key during a routine upgrade.

Reference record for the maintained public installation: ../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.