nostr-merchant

The AI that runs your NOSTR business. A local-first Python agent that holds the whole merchant toolkit — it checks its Lightning wallet, publishes notes and listings, runs a Shopstr storefront, answers encrypted DMs, triages its NOSTR inbox to draft and post replies, and pays for paywalled MCP tools over NWC — all under sats budget caps it can't exceed. Built on five MCP servers (nwc-mcp, nostr-ops-mcp, marketplace-mcp, albyhub-admin-mcp, paywall-mcp) — 37 tools the agent picks from.

Ollama-first, API-pluggable. Built on pydantic-ai — no LangChain. MIT.

v0.3 — engagement inbox. Seven CLI commands. nostr-merchant inbox triages replies/mentions on your recent posts and drafts responses in your voice (read-only, language-matched); inbox --post walks each draft (approve / edit / skip), confirms, and publishes the approved ones as NIP-10 replies. The agent layer enforces a budget-and-audit safety pipeline on top of every MCP server's own safety stack; the self-paying-for-tools loop holds end to end given a working LLM backend (Ollama / Anthropic / OpenAI). (Renamed from llmops-agent in v0.2.)

---

Install

pipx install nostr-merchant          # recommended: isolated CLI
# or:  uvx --from nostr-merchant nostr-merchant --help
# or:  pip install nostr-merchant

The five MCP servers it drives are launched on demand via npx -y — no separate install. You need Python 3.11+, an NWC-compatible wallet (e.g. Alby Hub), and an LLM backend (see Usage).

---

Status

Layer	State
Design doc	✅ Done — ../03-python-reference-agent-design.md
Package scaffold (uv init, pyproject.toml, ruff/mypy/pytest config)	✅ Done
config.py — env-driven Pydantic Settings	✅ Done
budget.py — persistent rolling-window tracker	✅ Done
audit.py — NDJSON writer	✅ Done
mcp_servers.py — MCPServerStdio launch + doctor probe	✅ Done
agent.py — Pydantic AI agent + process_tool_call middleware	✅ Done
workflows/research.py — self-paying research workflow	✅ Done
cli.py — typer entry-point with ask / doctor / budget / audit / config-print / version	✅ Done
Live LLM smoke test (Anthropic Haiku)	✅ Done — end-to-end ask returns a real nwc_get_balance receipt with all 37 substrate tools loaded

Usage

# from this directory, with uv-installed venv
uv run nostr-merchant --help
uv run nostr-merchant version
uv run nostr-merchant budget                # snapshot, no LLM needed
uv run nostr-merchant config-print          # effective config, secrets masked
uv run nostr-merchant doctor                # ping each configured MCP server
uv run nostr-merchant ask "What's my Lightning wallet balance?"   # the main demo loop
uv run nostr-merchant audit --tail 20       # recent audit entries

Or run the whole sequence with the bundled script: ./smoke.sh (full run — the ask is read-only, so it can never move sats) or ./smoke.sh --no-ask (skip the LLM call entirely).

ask requires a working LLM backend, set via NOSTR_MERCHANT_MODEL:

• anthropic:claude-haiku-4-5-20251001 (or any Anthropic/OpenAI model) — fast, reliable tool-calling. Set ANTHROPIC_API_KEY (or OPENAI_API_KEY) in ~/.nostr-merchant/.env. Recommended for most setups.
• ollama:<model> — fully local, no KYC, no phone-home (the sovereignty default). Needs Ollama at localhost:11434. Reality check: a 37-tool agent loop wants real hardware — a small model on a CPU-only box is too slow to be practical. Run Ollama on a GPU, or use a hosted model and keep your wallet + keys local (the trust boundary that actually matters).