aimarket-channels

Documentation

Pre-funded payment channels for off-chain capability invocation. Open a channel with one on-chain deposit, invoke multiple capabilities off-chain, settle once. Reduces per-call blockchain transactions from N to 1.

When to Use

Installation

pip install aimarket-channels

No configuration required — channels work immediately. Verify:

curl -X POST http://localhost:9083/ai-market/v2/channel/open \
  -H "Content-Type: application/json" \
  -d '{"deposit_usd": 3.00}' | jq '.channel.channel_id'

API Endpoints

Open Channel

curl -X POST https://modelmarket.dev/ai-market/v2/channel/open \
  -H "Content-Type: application/json" \
  -d '{
    "deposit_usd": 3.00,
    "token": "USDT",
    "chain": "base",
    "wallet": "0x...",
    "tx_hash": "0xabc123..."
  }'

Response:

{
  "channel": {
    "channel_id": "ch_a8f3b2c1d4e5",
    "balance_usd": 3.00,
    "original_deposit_usd": 3.00,
    "used_usd": 0.00,
    "token": "USDT",
    "chain": "base",
    "status": "open",
    "opened_at": "2026-05-22T12:00:00Z",
    "expires_at": "2026-05-23T12:00:00Z"
  }
}

Close Channel

curl -X POST https://modelmarket.dev/ai-market/v2/channel/close \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_a8f3b2c1d4e5",
    "settle_tx_hash": "0xsettle..."
  }'

Response:

{
  "settlement": {
    "channel_id": "ch_a8f3b2c1d4e5",
    "used_usd": 1.60,
    "refund_usd": 1.40,
    "original_deposit_usd": 3.00,
    "status": "settled"
  }
}

End-to-End Example

import requests

HUB = "https://modelmarket.dev"

# 1. Open channel — one on-chain TX
ch = requests.post(f"{HUB}/ai-market/v2/channel/open", json={
    "deposit_usd": 3.00, "tx_hash": "0x_on_chain_deposit"
}).json()
ch_id = ch["channel"]["channel_id"]
print(f"Channel: {ch_id}, balance: $3.00")

# 2. Invoke multiple capabilities — all off-chain
headers = {"X-Payment-Channel": ch_id}
plan = [
    ("prod-translate", "translate.multi@v2", {"text": "Hello world", "locales": ["ru", "fr"]}),
    ("prod-legal", "legal.review@v1", {"documents": {"main": "..."}}),
    ("prod-summarize", "summarize@v1", {"text": "..."}),
]

total = 0.0
for pid, cid, inp in plan:
    r = requests.post(f"{HUB}/ai-market/v2/invoke", json={
        "product_id": pid, "capability_id": cid,
        "source_hub": "local", "input": inp
    }, headers=headers)
    result = r.json()
    total += result.get("price_usd", 0)
    print(f"  {cid}: ${result.get('price_usd', 0):.2f} {'OK' if result.get('success') else 'FAIL'}")

# 3. Close channel — one on-chain TX
settle = requests.post(f"{HUB}/ai-market/v2/channel/close", json={
    "channel_id": ch_id, "settle_tx_hash": "0x_on_chain_settlement"
}).json()

print(f"Used: ${settle['settlement']['used_usd']:.2f}")
print(f"Refund: ${settle['settlement']['refund_usd']:.2f}")
print(f"Saved {(len(plan) - 1)} on-chain transactions")

Channel Lifecycle

OPEN (on-chain deposit)
  │
  ├── INVOKE (off-chain debit) ──┐
  ├── INVOKE (off-chain debit) ──┤  N invocations
  ├── INVOKE (off-chain debit) ──┘
  │
  ├── SAFETY ABORT → auto-refund to channel
  │
CLOSE (on-chain settlement)
  → used_usd sent to providers
  → refund_usd returned to consumer

Properties:

• 24h auto-expiry — channels close automatically after 24 hours
• Atomic safety refund — blocked invocations refund to channel immediately
• Single-writer ledger — no double-spend possible (hub is sole writer)
• Demo mode — demo-* tx hashes accepted for development (configurable)

Configuration

Recommended Deployment

Combine with:

• aimarket-safety — safety blocks auto-refund to channel
• aimarket-orchestrator — orchestrator opens one channel per task, runs multi-step plan
• aimarket-streaming — per-chunk billing debits the channel incrementally

Performance

Security Considerations

• No custody — the protocol never holds funds. Channels are simulated constructs for the reference implementation. Production uses on-chain escrow contracts
• Sequential ledger — single-writer (hub process), no double-spend vector
• Nonce replay protection — each channel is bound to a single session
• Demo tx hashes must be disabled in production — set AIFACTORY_PAYMENT_VERIFY_STUB=0

License

MIT · Maintained by AI-Factory · GitHub