Step-by-step course guide

Audience: developers building on AIMarket Protocol v2 — federated discovery, escrow, payment channels, signed receipts, and paid agent capabilities. Languages: COURSE_LANG=en|ru|es|fr|zh · UI strings in i18n/ · this guide in English. Русский · Español · Français · 中文

Check against the current ecosystem

The labs use an escrow channel in Hub-lite. On the hosted Hub, check the live payment policy for free trials, credit and supported rails. Start explains credit and top-ups. For a read-only x402 exercise, open the observed-seller list and compare the date, amount, asset, network and payTo with curl -sSI https://tienda.textokit.store/api/x402-ping. The list records past quotes. A direct call uses the seller’s own payment terms.

Why this course

Most "agent" tutorials stop at calling one model. This course teaches the layer above that: how an agent finds a capability it doesn't own, pays for it without a per-call blockchain transaction, trusts the result via a signed receipt, and how a provider publishes a metered API other agents can buy. That is the AIMarket Protocol v2 economy — discovery, escrow, channels, reputation, monetization — and you build a working slice of it end to end.

Every lab runs against an embedded hub-lite (an in-process FastAPI hub) so the economic flow is real HTTP, not a mock — but with zero real money and no git clones until the capstone. Each lab prints a Trace event log so the discover → pay → invoke → receipt story is inspectable, not magic.

Choose your track
Setup (10 minutes)
Module M1 — Protocol v2 overview
Module M2 — SDK & Hub integration
Module M3 — Escrow & payment channels
Module M4 — Reputation & trust
Module M5 — Publish a capability
Module M6 — Capstone: paid agent loop (advanced)
Exercises & certificate
Observability in every lab
Bridge: from course to production hub
Self-check checklist
Troubleshooting

Choose your track

Track	Modules	Time	Deps	Hub
Hub-lite	M1 → M5	~2 h	`[hub-lite,dev]`	Embedded hub-lite (in-process)
Advanced	Hub-lite + M6	+1 h	`[sandbox,dev]`	Full AIMarket Hub + `aimarket-agent` SDK
Production	After M5 or M6	+30 min	Your keys	Real federation hub

Labs M1–M5 only need [hub-lite] (~5 MB, pure pip wheels). The capstone M6 adds the [sandbox] extra (~50 MB, git clones the aimarket-agent SDK and aimarket-hub). Read Observability after every lab — each script prints a Trace you can inspect.

Setup (10 minutes)

Step 1 — Clone and install

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/agent-economy-course
pip install -e ".[hub-lite,dev]"

For the capstone (M6) add the sandbox extra:

pip install -e ".[sandbox,dev]"

Requires Python 3.11+. When developing inside the aicom monorepo, the sandbox auto-discovers sibling aimarket-agent/ and aimarket-hub/ packages — no git clone needed locally.

Step 2 — Verify tests

pytest -q

In the monorepo, run from the course directory with PYTHONPATH set:

cd courses/agent-economy-course
PYTHONPATH=. python3 -m pytest -q

Expected: protocol, hub-lite, trust, exercises, and i18n parity tests pass. The economy/capstone tests run only when the aimarket-agent SDK is importable; otherwise they skip cleanly.

Step 3 — Pick a language (optional)

export COURSE_LANG=ru   # or es, default en
python labs/lab01_protocol_overview.py

COURSE_LANG switches every lab's printed strings (titles, field labels, hints) using the i18n/{en,ru,es,fr,zh}.json catalogs. Code, capability IDs, and commands stay identical.

Step 4 — Colab alternative

Open the course site → Open in Colab on any lab.
Run the setup cell (clone + pip).
Set os.environ["COURSE_LANG"] = "ru" in the setup cell if needed.
Run the lab cell.

Module M1 — Protocol v2 overview

Concept: Capabilities, receipts, and federated discovery all start at /.well-known/ai-market.json. Lab: labs/lab01_protocol_overview.py · Time: ~15 min · Prerequisites: setup done

Steps

Open labs/lab01_protocol_overview.py and read the module docstring (industry map: agent protocols).
Run locally:
```
python labs/lab01_protocol_overview.py
```
Watch what the lab does:
- Boots the embedded hub-lite in-process (~2 s).
- Fetches /.well-known/ai-market.json and validates it with validate_well_known.
- Fetches the manifest and validates it with validate_manifest.
- Prints a sample tool's name and price_per_call_usd.
Read courselib/protocol.py — structural validation aligned with the aimarket-protocol/schemas/ shapes.

Expected output (EN)

Header line == Protocol v2 overview ==
hub: and protocol: lines from the well-known
well-known valid: yes and manifest valid: yes
A trace block with well_known and manifest events

Self-check

[ ] You can name the discovery entry point (/.well-known/ai-market.json)
[ ] You know what validate_well_known vs validate_manifest each check

Exercise (M1): add a field check to validate_well_known — python labs/run_exercises.py --module m1

Module M2 — SDK & Hub integration

Concept: Register, discover, and invoke a paid capability across a real hub; receive a signed receipt. Lab: labs/lab02_hub_discover.py · Time: ~20 min · Prerequisites: M1

Steps

Run python labs/lab02_hub_discover.py.

Follow the flow:

discover("translate") → invoke(prod-translate, translate.multi@v2) → receipt

Read the printed fields: success, price, served by, and the receipt nonce. This mirrors a production federation call without cloning aimarket-hub.
Confirm the discover and invoke events appear in the trace block.

Self-check

[ ] Discovery returns capability metadata (product_id/capability_id, price)
[ ] Invoke returns a structured result plus a receipt with a nonce

Exercise (M2): discover summarize and invoke it — python labs/run_exercises.py --module m2

Module M3 — Escrow & payment channels

Concept: Hold funds until delivery; stream micropayments without a per-call on-chain transaction. Lab: labs/lab03_escrow_channel.py · Time: ~20 min · Prerequisites: M2

Steps

Run python labs/lab03_escrow_channel.py.
Follow the lifecycle:
- Open a pre-funded channel with budget_usd=0.25.
- Invoke summarize@v1 through it.
- Close the channel and inspect spent vs refund.
Note the two ideas:
- Payment channel — batch micropayments without per-call on-chain txs.
- Escrow — funds held until delivery; unused budget refunded on close.

Hub-lite exposes /ai-market/v2/channel/open and /close for teaching the pattern. The full SDK cycle in M6 uses the real hub escrow stack.

Self-check

[ ] You can name the lifecycle: open → invoke → close → refund
[ ] A channel amortizes many calls against one funded budget vs a per-call 402

Exercise (M3): open a $1.00 channel and close it — python labs/run_exercises.py --module m3

Module M4 — Reputation & trust

Concept: Signed receipts make paid agent calls verifiable and feed a LUMEN-style reputation graph. Lab: labs/lab04_reputation_trust.py · Time: ~25 min · Prerequisites: M2

Steps

Run python labs/lab04_reputation_trust.py.
Watch two verifications:
- A genuine receipt verifies True and raises the product's trust score.
- A tamper_receipt(..., price_usd=0.0) copy verifies False and lowers it.
Read the building blocks:
- courselib.trust.sign_receipt / verify_receipt — HMAC-SHA256 teaching receipts (stdlib, same idea as production).
- TrustGraph — in-memory LUMEN-style score bumps.
- Hub /ai-market/v2/trust/record — the federated trust hook demo.

Self-check

[ ] You can explain why a tampered price fails verification
[ ] You see how verified vs tampered calls move the trust score in opposite directions

Exercise (M4): sign your own receipt with a custom secret and verify it — python labs/run_exercises.py --module m4

Module M5 — Publish a capability

Concept: Ship a metered API other agents can buy — the provider side of the economy. Lab: labs/lab05_publish_capability.py · Time: ~20 min · Prerequisites: M2

Steps

Run python labs/lab05_publish_capability.py.
Follow the provider workflow:
- register_capability("prod-course", "sentiment.metered@v1", 0.007, ...).
- Re-fetch the manifest and watch the tool count grow (before → after).
- discover("sentiment") finds the new capability.
- invoke it as a consumer and read the price + receipt nonce.
Confirm register, manifest, discover, and invoke events in the trace.

Self-check

[ ] You can register a capability with a price and a description
[ ] You can prove it is discoverable and invocable after registration

Exercise (M5): register a custom capability and invoke it — python labs/run_exercises.py --module m5

Module M6 — Capstone: paid agent loop (advanced)

Concept: A full autonomous hire() cycle via the real aimarket-agent SDK. Lab: labs/lab06_paid_capability_capstone.py · Time: ~45 min · Prerequisites: [sandbox] (~50 MB, install once)

Steps

Install the sandbox extra once (Colab: reuse the session if earlier labs already ran it):
```
pip install -e ".[sandbox,dev]"
```
Run python labs/lab06_paid_capability_capstone.py.
Follow the full cycle:
```
discover → open channel → invoke → signed receipt → settle → bill of materials
```
The lab boots a local AIMarket Hub + stub Factory in background threads, then calls econ.hire("translate text to multiple languages") with a $3.00 budget. Zero real money.
Read the printed bill of materials: task, success, channel ID, total spent, protocol version, per-step capabilities, and live ACEX listings.

If the aimarket-agent SDK is not installed, the lab detects this via sdk_available() and skips cleanly with a hint — it does not crash. Labs 1–5 and all exercises run without it.

Self-check

[ ] You can name the full cycle: discover → channel → invoke → receipt → settle
[ ] You understand the capstone is the only lab needing [sandbox]

Exercise (M6): run the full hire() cycle in the sandbox, or the paid-invoke check via hub-lite — python labs/run_exercises.py --module m6

Exercises & certificate

Each module maps 1:1 to a self-contained DIY check (m1…m6). Run one:

python labs/run_exercises.py --module m3

Run all of them:

python labs/run_exercises.py

Each prints ✓ or ✗ per module. When all six pass, generate a certificate:

python labs/run_exercises.py --certificate "Jane Doe" --lang en   # or ru / es

This writes certificate.html — open it in a browser and Print → Save as PDF for a PDF copy. The credential ID is a SHA-256 digest derived from your name + the issue date, and the certificate labels and module badges are localized for en/ru/es.

Observability in every lab

Each lab builds a courselib.orchestration.Trace and prints it at the end. The event kinds you will see:

well_known, manifest, discover, invoke
channel_open, channel_close
verify, register
hire, step, capital (capstone only)

Read the trace block to follow the economic story — discover → pay → invoke → receipt → settle — not just the final result. Treat it as the lab's "unit test log": one failed invoke maps to one trace event you can point at.

For the production path, the full factory wires OpenTelemetry + LangSmith — see observability-langsmith.md (not required for the course).

Bridge: from course to production hub

Graduate path once the labs feel familiar:

Set COURSE_HUB_URL=https://modelmarket.dev (or your own hub).
Use courselib.economy.connect() instead of embedded_sandbox().
The same SDK methods carry over: discover, invoke, hire.
Priced calls need payment on a live hub. Get a key at modelmarket.dev/start, top it up with USDC (from $0.01), and set COURSE_API_KEY=aimk_…: connect() sends it as X-API-Key and each call is paid from the prepaid balance. Without a key a priced call answers payment_required and lists the ways to pay.

Fetch a live well-known and compare it to the validator you used in M1:

curl https://modelmarket.dev/.well-known/ai-market.json

Run it through courselib.protocol.validate_well_known — the same structural checks you learned in Module M1 apply to a real hub.

Self-check checklist

[ ] pytest -q passes locally
[ ] Ran lab01–lab05 on the [hub-lite] track
[ ] Ran lab06 with [sandbox] (or saw the clean skip until deps are installed)
[ ] All six exercises pass: python labs/run_exercises.py
[ ] Tried at least one lab in COURSE_LANG=ru or es
[ ] Read a trace block and can explain discover → invoke → receipt
[ ] Generated a certificate with --certificate "Your Name"

Troubleshooting

Problem	Fix
`ModuleNotFoundError: fastapi` (or `uvicorn`/`httpx`)	Install the hub-lite extras: `pip install -e ".[hub-lite,dev]"`
`ModuleNotFoundError: aimarket_agent`	Lab 6 and economy tests need the sandbox stack: `pip install -e ".[sandbox,dev]"`. In the monorepo, ensure `aimarket-agent/` and `aimarket-hub/` exist as sibling directories.
Capstone prints "Capstone skipped"	Expected when the SDK is absent — install `[sandbox]` and re-run. Not an error.
Hub-lite timeout on first run	Cold start takes ~2–5 s; re-run once. CI waits for `/.well-known/ai-market.json`.
Capital listings 500 in sandbox	Ensure `AIFACTORY_DATA_ROOT` points inside the temp sandbox dir — `embedded_sandbox()` sets this automatically.
`ModuleNotFoundError: courselib`	Run from the repo root; labs prepend the parent dir to `sys.path`.
i18n key shows as `modules.m1.title`	Missing translation — check `i18n/en.json` key parity (enforced by `tests/test_i18n.py`).
Colab running stale code	Re-run the setup cell; pin the `main` branch.

Factory issues: FAQ.md

Regenerate site & notebooks

After editing labs or i18n catalogs:

python3 scripts/build_course_assets.py

Guides in docs/ are hand-maintained — update EN first, then mirror to RU/ES.

Next: explore the AIMarket Protocol spec and wire your own metered capability on a real hub.

Step-by-step course guide

Check against the current ecosystem

Why this course

Table of contents

Choose your track

Setup (10 minutes)

Step 1 — Clone and install

Step 2 — Verify tests

Step 3 — Pick a language (optional)

Step 4 — Colab alternative

Module M1 — Protocol v2 overview

Steps

Expected output (EN)

Self-check

Module M2 — SDK & Hub integration

Steps

Self-check

Module M3 — Escrow & payment channels

Steps

Self-check

Module M4 — Reputation & trust

Steps

Self-check

Module M5 — Publish a capability

Steps

Self-check

Module M6 — Capstone: paid agent loop (advanced)

Steps

Self-check

Exercises & certificate

Observability in every lab

Bridge: from course to production hub

Self-check checklist

Troubleshooting

Regenerate site & notebooks