feat(server): actp serve — AIP-2.1 quote-channel daemon

New CLI command + Python package (agirails.server):

  $ actp serve --policy ./provider-policy.json --port 8787 \
               --network base-sepolia

FastAPI app exposes:
  GET  /                                    — health (provider+chains)
  POST /quote-channel/{chainId}/{txId}      — counter-offer ingest

POST endpoint enforces the AIP-2.1 §8 security model:
  - URL path binding (chainId / txId match message)
  - TTL + 30s grace (cheap reject before sig recovery)
  - EIP-712 signature recovery via CounterOfferBuilder.verify
  - in-memory nonce LRU dedup (caller plugs distributed store
    for multi-worker deploys)

Verified counters are evaluated against a loaded ProviderPolicy
via evaluate_counter (walk / concede strategies, concede_pct math,
floor + ideal band check). Verdicts logged for the operator;
v1 does NOT auto-deliver CounterAccept back to the buyer (AIP-2.1
§5.3 — operator handles reply).

Package contents:
  server/policy.py         — ProviderPolicy + PricingPolicy + loader
  server/policy_engine.py  — evaluate_counter → Verdict
  server/quote_channel.py  — QuoteChannelHandler + InMemoryDedupStore
  server/app.py            — FastAPI factory create_app(...)
  cli/commands/serve.py    — typer command wiring uvicorn

FastAPI + uvicorn ship as the optional [server] extra to keep
library-only callers free of the install cost:
  pip install agirails[server]

21 tests cover: policy invariants + JSON loader, policy engine
verdicts (accept/reject/walk/concede), QuoteChannelHandler
(valid/path-mismatch/tampered-sig/expired/dedup/wrong-type),
InMemoryDedupStore atomicity + expiry, FastAPI surface via
TestClient (health + 201/400 routing).

P2.2 of python-sdk parity sprint.

Author: DamirAGI

CHANGELOG.md

@@ -141,6 +141,25 @@ swaps needed only if:
   reverted with kernel `_requesterCheck` / `_providerCheck` mismatch.
   Legacy EOA / mock path is preserved when wallet provider lacks
   `pay_actp_batched`.
+- **`actp serve` — AIP-2.1 quote-channel daemon.** New CLI command +
+  Python package (`agirails.server`) that runs a FastAPI app exposing:
+  - `GET /` — health check (provider address + supported chainIds)
+  - `POST /quote-channel/{chainId}/{txId}` — receives AIP-2.1
+    `agirails.counteroffer.v1` messages, runs URL-path-binding +
+    TTL-with-grace + EIP-712 signature verification (via
+    `CounterOfferBuilder`) + in-memory nonce dedup, then evaluates the
+    verified counter against a loaded `ProviderPolicy`
+    (`ACCEPT` / `COUNTER` / `REJECT` verdicts logged for the operator).
+  Includes `ProviderPolicy` + `PricingPolicy` dataclasses with JSON
+  loader (`load_policy_from_file`), minimal `evaluate_counter` policy
+  engine (walk / concede strategies with concede_pct math), and
+  `QuoteChannelHandler` framework-agnostic verifier with
+  `InMemoryDedupStore`. FastAPI / uvicorn ship as the optional
+  `server` extra — install via `pip install agirails[server]`. Mirrors
+  the TS daemon's v1 surface; out-of-scope (parity-matched): on-chain
+  INITIATED watcher (lives in `actp agent`) and reverse-channel
+  delivery of `CounterAcceptMessage` (operator-handled per
+  AIP-2.1 §5.3).
 - **`X402Adapter` auto-registration** — when an `ACTPClient` is created
   with a `wallet_provider` exposing `send_transaction` (both
   `EOAWalletProvider` and `AutoWalletProvider` qualify) and `mode` is
@@ -159,7 +178,6 @@ swaps needed only if:
   by passing `private_key=None` (orchestrator side).
 
 ### Coming in 3.x
-- `actp serve` daemon (FastAPI quote-channel HTTP for AIP-2.1)
 - Web Receipts (EIP-712 ReceiptWrite + agirails.app upload)
 - `actp repair`, `actp claim-code`, `actp request`, `actp verify` CLI commands
 

pyproject.toml

@@ -75,6 +75,10 @@ security = [
 mutation = [
     "mutmut>=2.4.0",                # Mutation testing
 ]
+server = [
+    "fastapi>=0.110.0",             # actp serve daemon (AIP-2.1 quote channel)
+    "uvicorn>=0.30.0",
+]
 
 [project.scripts]
 actp = "agirails.cli.main:run"

src/agirails/cli/commands/serve.py

@@ -0,0 +1,145 @@
+"""``actp serve`` — run the AIP-2.1 quote-channel daemon.
+
+Loads a ProviderPolicy JSON file, builds a FastAPI app via
+:func:`agirails.server.app.create_app`, and serves it with uvicorn.
+
+Scope:
+  - accept + verify incoming counter-offers via :class:`QuoteChannelHandler`
+  - log the policy verdict (ACCEPT / COUNTER / REJECT) per round
+  - one-line health response on ``GET /``
+
+Not in scope here (matches TS daemon v1):
+  - On-chain INITIATED-tx detection (handled by ``actp agent`` /
+    long-running `Agent` instances).
+  - Sending CounterAcceptMessage back to buyer (no reverse-endpoint
+    discovery in v1 — operator handles delivery).
+
+Usage::
+
+    actp serve --policy ./provider-policy.json --port 8787 --network base-sepolia
+    actp serve --policy ./provider-policy.json --mock        # local testing
+
+Example policy JSON (saved as ``provider-policy.json``)::
+
+    {
+      "services": ["text-generation"],
+      "pricing": {
+        "min_acceptable": {"amount": 500000, "currency": "USDC", "unit": "base"},
+        "ideal_price":    {"amount": 1000000, "currency": "USDC", "unit": "base"}
+      },
+      "quote_ttl": "15m",
+      "counter_strategy": "concede",
+      "concede_pct": 30,
+      "max_requotes": 2
+    }
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from agirails.cli.utils.output import print_error, print_info, print_success
+
+
+def serve(
+    policy: Path = typer.Option(
+        ...,
+        "--policy",
+        help="Path to ProviderPolicy JSON file.",
+        exists=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    port: int = typer.Option(
+        8787, "--port", min=1, max=65535, help="HTTP port to listen on."
+    ),
+    host: str = typer.Option(
+        "0.0.0.0", "--host", help="Bind address (default: 0.0.0.0)."
+    ),
+    network: str = typer.Option(
+        "base-sepolia",
+        "--network",
+        help="Network — base-sepolia | base-mainnet | mock.",
+    ),
+    mock: bool = typer.Option(
+        False,
+        "--mock",
+        help="Use a mock provider address / zero kernel for local testing.",
+    ),
+    provider_address: Optional[str] = typer.Option(
+        None,
+        "--provider-address",
+        help=(
+            "Provider EOA / Smart Wallet address shown on /health. "
+            "Defaults to env ACTP_PROVIDER_ADDRESS or a placeholder."
+        ),
+    ),
+) -> None:
+    """Run a long-running provider daemon (AIP-2.1 quote channel)."""
+    try:
+        # Lazy imports — server stack is an optional dependency.
+        try:
+            import uvicorn  # noqa: F401
+        except ImportError as exc:
+            raise RuntimeError(
+                "uvicorn is not installed. Install the server extras:\n"
+                "  pip install agirails[server]"
+            ) from exc
+
+        from agirails.config.networks import get_network
+        from agirails.server.app import create_app
+        from agirails.server.policy import load_policy_from_file
+        from agirails.server.quote_channel import build_channel_path
+
+        # 1. Load + validate policy.
+        loaded_policy = load_policy_from_file(policy)
+
+        # 2. Resolve kernel address + chainId from network config.
+        if mock:
+            kernel_address = "0x" + "0" * 40
+            chain_id = 84532
+        else:
+            network_cfg = get_network(network)
+            kernel_address = network_cfg.contracts.actp_kernel
+            chain_id = network_cfg.chain_id
+
+        # 3. Provider address for /health.
+        import os
+        signer_address = (
+            provider_address
+            or os.environ.get("ACTP_PROVIDER_ADDRESS")
+            or "0x" + "0" * 40
+        )
+
+        # 4. Build app.
+        app = create_app(
+            policy=loaded_policy,
+            kernel_address_by_chain_id={chain_id: kernel_address},
+            signer_address=signer_address,
+            service_label="actp-serve",
+        )
+
+        # 5. Banner + serve.
+        print_success(f"actp serve listening on http://{host}:{port}")
+        print_info(f"  Network:       {network}{'  (mock)' if mock else ''}")
+        print_info(f"  Provider:      {signer_address}")
+        print_info(f"  Channel base:  {build_channel_path(chain_id, '<txId>')}")
+        print_info(f"  Health:        GET /")
+        print_info("")
+        print_info(
+            "Counter-offers POSTed to /quote-channel/{chainId}/{txId} are verified +"
+        )
+        print_info(
+            "evaluated against the policy. Verdicts are logged here; v1 does NOT"
+        )
+        print_info(
+            "auto-deliver CounterAccept back to the buyer (AIP-2.1 §5.3)."
+        )
+
+        import uvicorn as _uvicorn
+
+        _uvicorn.run(app, host=host, port=port, log_level="info")
+    except Exception as exc:
+        print_error(f"actp serve failed: {exc}")
+        raise typer.Exit(code=1)

src/agirails/cli/main.py

@@ -130,6 +130,7 @@ def main(
 from agirails.cli.commands import test as test_cmd
 from agirails.cli.commands import register as register_cmd
 from agirails.cli.commands import negotiate as negotiate_cmd
+from agirails.cli.commands import serve as serve_cmd
 
 # Register commands
 app.command(name="init")(init_cmd.init)
@@ -163,6 +164,9 @@ def main(
 app.command(name="register")(register_cmd.register)
 app.command(name="negotiate")(negotiate_cmd.negotiate)
 
+# AIP-2.1 quote-channel daemon
+app.command(name="serve")(serve_cmd.serve)
+
 # Deploy subcommand group
 deploy_app = typer.Typer(
     name="deploy",

src/agirails/server/__init__.py

@@ -0,0 +1,41 @@
+"""AGIRAILS server package — ``actp serve`` daemon for AIP-2.1 quote channel."""
+
+from agirails.server.policy import (
+    PLATFORM_MIN_BASE_UNITS,
+    PricingPolicy,
+    ProviderPolicy,
+    load_policy_from_dict,
+    load_policy_from_file,
+)
+from agirails.server.policy_engine import (
+    Verdict,
+    VerdictAction,
+    evaluate_counter,
+)
+from agirails.server.quote_channel import (
+    DEDUP_TTL_SECONDS,
+    HandlerContext,
+    HandlerResult,
+    InMemoryDedupStore,
+    QuoteChannelHandler,
+    TTL_GRACE_SECONDS,
+    build_channel_path,
+)
+
+__all__ = [
+    "PLATFORM_MIN_BASE_UNITS",
+    "PricingPolicy",
+    "ProviderPolicy",
+    "load_policy_from_dict",
+    "load_policy_from_file",
+    "Verdict",
+    "VerdictAction",
+    "evaluate_counter",
+    "DEDUP_TTL_SECONDS",
+    "HandlerContext",
+    "HandlerResult",
+    "InMemoryDedupStore",
+    "QuoteChannelHandler",
+    "TTL_GRACE_SECONDS",
+    "build_channel_path",
+]

src/agirails/server/app.py

@@ -0,0 +1,115 @@
+"""
+FastAPI app factory for the AIP-2.1 quote channel daemon (``actp serve``).
+
+Builds an ASGI app exposing:
+
+  - ``GET  /``                                 → health check
+  - ``POST /quote-channel/{chainId}/{txId}``   → counter-offer ingest
+
+The counter-offer endpoint runs :class:`QuoteChannelHandler` (signature
++ TTL + dedup + path-binding checks) and, on success, evaluates the
+verified message against the loaded :class:`ProviderPolicy` via
+:func:`evaluate_counter`. The verdict is logged but NOT auto-sent back
+to the buyer in v1 (see AIP-2.1-DRAFT §5.3 — operator handles reply
+delivery).
+
+Note: FastAPI / uvicorn are an OPTIONAL dependency. Install with::
+
+    pip install agirails[server]
+
+@module server/app
+"""
+
+from typing import Any, Dict
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from agirails.server.policy import ProviderPolicy
+from agirails.server.policy_engine import evaluate_counter
+from agirails.server.quote_channel import (
+    HandlerContext,
+    QuoteChannelHandler,
+    build_channel_path,
+)
+from agirails.utils.logger import Logger
+
+_logger = Logger("agirails.server.app")
+
+
+def create_app(
+    policy: ProviderPolicy,
+    kernel_address_by_chain_id: Dict[int, str],
+    signer_address: str,
+    service_label: str = "actp-serve",
+) -> Any:
+    """Construct the FastAPI app.
+
+    Args:
+        policy: Loaded :class:`ProviderPolicy`.
+        kernel_address_by_chain_id: Mapping ``{chainId: kernel_address}``
+            so the handler can verify EIP-712 signatures bound to the
+            on-chain ACTPKernel for each supported chain.
+        signer_address: Provider address (shown on the health endpoint
+            for operational visibility).
+        service_label: Identifier returned by the health check.
+
+    Returns:
+        A configured :class:`fastapi.FastAPI` instance ready to be
+        passed to ``uvicorn.run`` or mounted under a parent app.
+    """
+    app = FastAPI(title="AGIRAILS — actp serve", version="1.0.0")
+    handler = QuoteChannelHandler(
+        kernel_address_by_chain_id=kernel_address_by_chain_id,
+    )
+
+    @app.get("/")
+    async def health() -> Dict[str, Any]:
+        return {
+            "status": "ok",
+            "provider": signer_address,
+            "chains": list(kernel_address_by_chain_id.keys()),
+            "service": service_label,
+        }
+
+    @app.post("/quote-channel/{chain_id}/{tx_id}")
+    async def quote_channel(
+        chain_id: int, tx_id: str, request: Request
+    ) -> Any:
+        try:
+            payload = await request.json()
+        except Exception:
+            return JSONResponse(
+                status_code=400,
+                content={"accepted": False, "reason": "Invalid JSON"},
+            )
+
+        result = handler.handle(
+            payload,
+            HandlerContext(path_chain_id=chain_id, path_tx_id=tx_id),
+        )
+
+        # Evaluate verified counter-offers against policy and log the verdict.
+        # The HTTP response is the handler's accepted-or-not signal; the
+        # verdict is operator-visible via logs (v1 doesn't auto-deliver
+        # CounterAcceptMessage back — see AIP-2.1 §5.3).
+        if result.parsed_message is not None:
+            try:
+                verdict = evaluate_counter(result.parsed_message, policy)
+                _logger.info(
+                    f"[counter] tx={tx_id[:12]}… "
+                    f"counter={result.parsed_message.counterAmount} "
+                    f"→ {verdict.action.value}: {verdict.reason}"
+                )
+            except Exception as exc:
+                _logger.warning(
+                    f"[counter] tx={tx_id[:12]}… "
+                    f"policy eval failed: {exc}"
+                )
+
+        return JSONResponse(status_code=result.status, content=result.body)
+
+    return app
+
+
+__all__ = ["create_app"]