BasicSwap AMM Pro

A risk-managed market-making controller for BasicSwap DEX. The v0.2.0 release is paper-first by default: it runs independent market profiles for XMR/BTC, XMR/LTC, and XMR/BCH, values per-market inventory, builds multi-level bid/ask ladders, applies inventory skew, enforces circuit breakers, stores state, exposes health/metrics, and simulates reconciliation.

No strategy guarantees profit. Atomic swaps have settlement, chain-fee, inventory, counterparty-behavior, software, and adverse-selection risks. Start with disposable capital and paper mode.

What works now

• XMR/BTC, XMR/LTC, and XMR/BCH cross-rates from CoinGecko
• Optional BTC/LTC, BTC/BCH, and LTC/BCH profiles
• Independent spreads, sizing, inventory targets, and risk limits per market
• Pluggable market-data adapters
• Inventory-aware quote skew
• Multi-level quote ladder
• Risk states: STARTING, PAPER, ACTIVE, REDUCE_ONLY, PAUSED, HALTED
• Persistent JSON state plus realized, unrealized, and total mark-to-market P&L indicators
• Prometheus metrics on /metrics with provisioned Grafana dashboards and alert rules
• Status and quotes on /health, /status, and /quotes
• Emergency stop using a HALT file
• BasicSwap HTTP adapter with configurable endpoints
• Docker image, Compose file, systemd unit, tests, and CI

Safety boundary

Live publishing is intentionally guarded. mode: live requires both:

1. AMM_PRO_LIVE_ACK=I_UNDERSTAND_ATOMIC_SWAP_MARKET_MAKING_RISK
2. Confirmed endpoint mappings for the exact BasicSwap release you run

The default API paths are examples based on common BasicSwap JSON route naming and must be verified locally. Paper mode never submits or revokes offers.

Run locally

cp config.example.yaml config.yaml
python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
amm-pro --config config.yaml

Then open:

http://127.0.0.1:8787/status
http://127.0.0.1:8787/markets
http://127.0.0.1:8787/markets/XMR%2FLTC
http://127.0.0.1:8787/quotes
http://127.0.0.1:8787/metrics

Run tests:

pytest -q
ruff check .

Docker

cp config.example.yaml config.yaml
mkdir -p data
chmod 700 data
docker compose up --build -d

BasicSwap may run on the host or another container. Adjust basicswap.base_url; on Linux, Compose maps host.docker.internal to the host gateway.

Grafana dashboards

Docker Compose provisions Prometheus and Grafana automatically. Open Grafana at:

http://127.0.0.1:3000

The default development login is admin / admin; change GRAFANA_ADMIN_PASSWORD before exposing it anywhere. Dashboards are version-controlled under grafana/dashboards/:

• Executive overview
• Markets and quote activity
• Risk states and operator pause
• IRC and self-hosted ntfy notifications
• Runtime and process operations
• Profit and loss by market

Prometheus alerts cover service loss, paused or halted states, cycle failures, IRC disconnection, IRC queue backlog, ntfy failures, and prolonged operator pause.

Dashboard previews

These illustrative previews show the provisioned layout; live values come from Prometheus after startup.

The P&L dashboard exposes portfolio value, realized P&L, unrealized mark-to-market P&L, and total P&L per market. Values remain denominated in each market's quote asset; unlike quote assets must be converted before portfolio-wide financial reporting. Deposits and withdrawals also require separate cash-flow accounting.

Emergency stop

touch data/HALT

The engine enters HALTED. Removing the file does not clear the halted state automatically; restart with an explicit operator decision after inspecting the incident.

Configuration logic

The mid price is the median of valid sources. Quotes are centered on an inventory-adjusted reservation price:

inventory deviation = current base weight - target base weight
skew bps = clamp(deviation × skew factor, ±max skew)
reservation price = fair price × (1 - skew bps / 10,000)

Too much of a market base asset lowers both bid and ask centers, discouraging additional purchases and making sales more attractive. Each market has independent sizing, spread, inventory, and risk settings. Each ladder level widens by level_spacing_bps.

Before enabling live mode

• Verify BasicSwap version and JSON API routes with curl
• Confirm coin IDs, amount units, rate units, swap type, offer expiry, auto-accept behavior, and response schemas
• Add authenticated access or bind BasicSwap only to loopback/private networking
• Test offer creation and revocation with dust-sized disposable amounts
• Configure wallet synchronization, confirmed balance, open-bid, and failed-swap checks
• Add chain-fee estimates to the spread floor
• Run paper mode through volatile and stale-data scenarios
• Back up BasicSwap wallet data independently

Architecture

flowchart LR
    FEEDS[External price feeds] --> AGG[Price aggregator]
    WALLETS[BasicSwap wallets] --> INV[Inventory model]
    AGG --> STRAT[Multi-market strategy]
    INV --> STRAT
    STRAT --> RISK[Risk engine]
    RISK --> EXEC[BasicSwap adapter]
    RISK --> EVENTS[Event bus]
    EVENTS --> NTFY[Self-hosted ntfy]
    EVENTS --> IRC[Persistent IRC bot]
    IRC --> FISH[Optional FiSH encryption]
    FISH -->|encrypted !start / !stop| CONTROL[Operator control]
    CONTROL --> RISK
    EXEC --> LEDGER[(SQLite / PostgreSQL)]
    RISK --> METRICS[Prometheus / Grafana]

Risk states

stateDiagram-v2
    [*] --> STARTING
    STARTING --> PAPER: dependencies healthy
    PAPER --> ACTIVE: live gates approved
    PAPER --> PAUSED: !stop or safety condition
    ACTIVE --> REDUCE_ONLY: inventory warning
    ACTIVE --> PAUSED: !stop or circuit breaker
    ACTIVE --> HALTED: critical failure
    REDUCE_ONLY --> ACTIVE: exposure normalized
    REDUCE_ONLY --> PAUSED: !stop or elevated risk
    PAUSED --> PAPER: !start in paper mode
    PAUSED --> ACTIVE: !start in validated live mode
    PAUSED --> HALTED: emergency HALT
    HALTED --> STARTING: explicit operator recovery
    note right of PAUSED
      Quoting is stopped.
      IRC remains connected and accepts
      authorized !start / !stop commands.
    end note

Modular strategies

The engine includes composable modules for balanced market making, accumulation, distribution, trend and volatility adaptation, thin-liquidity harvesting, time-of-day schedules, adaptive spread and fill-rate control, inventory risk, triangular opportunity bias, fee-aware pricing, capital allocation, market dominance, position protection, portfolio goals, and opportunity scoring. See docs/STRATEGY_MODULES.md.

Documentation

Start with the detailed RUNBOOK.md, then use docs/README.md for topic-specific references. FreeBSD, Linux, Docker, monitoring, incident-response, backup, and live-mode safety procedures are included.

Repository layout

src/amm_pro/       application code
grafana/           provisioned dashboards and datasource
prometheus/        scrape configuration and alert rules
config.example.yaml
Dockerfile
docker-compose.yml
deploy/systemd/
deploy/freebsd/
docs/
tests/

License

AGPL-3.0-or-later. See LICENSE.md and DISCLAIMER.md.

Clean-release capabilities

• Multi-market paper quoting for XMR/BTC, XMR/LTC and XMR/BCH.
• SQLite or PostgreSQL cycle persistence.
• API-key protected operator endpoints and WebSocket market events.
• Deterministic backtesting CLI.
• Prometheus metrics, Docker, systemd and FreeBSD service definitions.
• Live mode requires both the environment acknowledgement and validated adapter configuration. Offer submission is disabled by default.

See docs/API.md, docs/DATABASE.md, and docs/BACKTESTING.md.

Notifications

The release provides self-hosted ntfy delivery and a continuously connected IRC control bot with optional FiSH/Blowcrypt channel encryption. The IRC service remains online when quoting is stopped, supports keyed channels, and accepts authorized !start and !stop commands. Both subscribe to engine events without blocking market cycles. See docs/NOTIFICATIONS.md for configuration, FiSH keys, authentication, TLS, connection persistence, and operational guidance.

Accumulate a specific coin

Markets can intentionally acquire one side of a pair while only accepting prices that retain a configured edge from fair value.

strategy:
  mode: accumulate
  accumulate_asset: XMR
  strength_bps: 75
  min_entry_edge_bps: 20
  target_weight: 0.65
  protect_accumulated_asset: true

On XMR/BTC, accumulate_asset: XMR generates improved bids and can suppress XMR asks. Setting accumulate_asset: BTC generates improved asks and can suppress bids. Once the target portfolio weight is reached, the market returns to its normal balanced ladder. See docs/STRATEGY.md for operating guidance.