Run a Solver

solverd watches the Arkade transaction stream for funded swaps and fills the ones your markets and prices accept. solver is its management CLI, a thin HTTP client that holds no keys. Both ship from arkade-os/solver.

This solver supports Arkade Asset swaps only. Lightning corridors are in development — Provide Liquidity has the status and the application path.

Before You Start

An arkd gRPC endpoint for your network — mainnet is https://arkade.computer
The matching Emulator endpoint — contact [email protected] for access. solverd refuses to start without both
A 32-byte hex wallet seed: openssl rand -hex 32. The solver spends from it unattended, so treat it like a hot-wallet key
BTC for fees and carrier amounts, plus the asset inventory each enabled direction pays out
A JSON price feed for each cross-asset market — any JSON endpoint works (see Add a Market)

Install

Binary
Docker

Each release ships solverd and solver for Linux and macOS, amd64 and arm64. Install both to a directory on PATH:

# Example: v0.0.5 on Linux amd64
curl -LO https://github.com/arkade-os/solver/releases/download/v0.0.5/solverd-linux-amd64
curl -LO https://github.com/arkade-os/solver/releases/download/v0.0.5/solver-linux-amd64
sudo install -m 0755 solverd-linux-amd64 /usr/local/bin/solverd
sudo install -m 0755 solver-linux-amd64 /usr/local/bin/solver

A container image is published alongside each release:

docker pull ghcr.io/arkade-os/solver:v0.0.5

The image’s entrypoint is solverd, and both binaries are on PATH inside the container, so the CLI is available with docker exec.The image sets SOLVER_DATADIR=/app/data and declares it a volume — mount a named volume there. That one directory holds the wallet and the SQLite database.

Run the Daemon

solverd takes no flags and no config file — configuration is entirely SOLVER_-prefixed environment variables:

Binary
Docker

SOLVER_ARK_URL=https://arkade.computer \
SOLVER_EMULATOR_URL=<EMULATOR_URL> \
SOLVER_WALLET_SEED=<32-byte-hex-seed> \
SOLVER_WALLET_PASSWORD=<wallet-password> \
solverd

docker run -it --rm \
  -e SOLVER_ARK_URL=https://arkade.computer \
  -e SOLVER_EMULATOR_URL=<EMULATOR_URL> \
  -e SOLVER_WALLET_SEED=<32-byte-hex-seed> \
  -e SOLVER_WALLET_PASSWORD=<wallet-password> \
  -v solverd-data:/app/data \
  -p 127.0.0.1:7171:7171 \
  ghcr.io/arkade-os/solver:v0.0.5

State lives in the solverd-data volume, so --rm is safe here. Keep It Running turns this into a supervised container.

Variable	Required	Default	Purpose
`SOLVER_ARK_URL`	Yes	None	arkd gRPC endpoint
`SOLVER_EMULATOR_URL`	Yes	None	Emulator endpoint
`SOLVER_WALLET_SEED`	Yes	None	32-byte hex wallet seed
`SOLVER_WALLET_PASSWORD`	No — set it anyway	Empty	Gates send, exit, settle, and seed export
`SOLVER_DATADIR`	No	`$HOME/.solverd` (`/app/data` in Docker)	Wallet and SQLite data
`SOLVER_GRPC_PORT`	No	`7170`	gRPC listener
`SOLVER_HTTP_PORT`	No	`7171`	HTTP API, CLI target, and web UI
`SOLVER_EXPLORER_URL`	No	None	Block explorer URL
`SOLVER_LOG_LEVEL`	No	`4` (info)	Log verbosity

Always set SOLVER_WALLET_PASSWORD. If unset it defaults to the empty string, and anyone who can reach the HTTP port can export the seed with an empty-password request.

The two ports must differ. First run initializes the wallet from the seed; later runs unlock and resume. Back up the data directory — it holds the wallet alongside your markets and trade history.

Keep It Running

In production, supervise the daemon so it restarts on failure and comes back with the host:

Binary (systemd)
Docker (restart policy)

/etc/systemd/system/solverd.service:

[Unit]
Description=Arkade reference solver
After=network-online.target

[Service]
User=solver
EnvironmentFile=/etc/solverd.env
ExecStart=/usr/local/bin/solverd
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Put the environment variables in /etc/solverd.env with mode 0600 — it holds the wallet seed in plaintext. solverd shuts down cleanly on SIGTERM.

sudo chmod 0600 /etc/solverd.env
sudo systemctl enable --now solverd

docker run -d --name solverd \
  --restart unless-stopped \
  -v solverd-data:/app/data \
  -p 127.0.0.1:7171:7171 \
  --env-file /etc/solverd.env \
  ghcr.io/arkade-os/solver:v0.0.5

Publishing to 127.0.0.1 keeps the API off the network — see the next section. The image ships no HEALTHCHECK; if you want one, probe GET /v1/status:

--health-cmd "wget -qO- http://localhost:7171/v1/status || exit 1"

Keep the Daemon Private

solverd has no authentication and no TLS on either listener, and both bind all interfaces — there is no bind-address setting. Everything except send, exit, settle, and seed export is completely unauthenticated, including adding and removing markets. The web UI on the HTTP port can export the wallet seed. Treat port 7171 as equivalent to the seed file.

Never expose 7170 or 7171 to the incoming internet. Firewall them; on Docker, publish to loopback only or not at all.
Use the CLI over SSH: shell into the host and run solver … against localhost, or docker exec solverd solver market list.
Reach the web UI over a VPN or cloud security groups restricted to your own addresses — or tunnel it: ssh -N -L 7171:127.0.0.1:7171 user@host, then open http://localhost:7171.
There is no rate limiting on password attempts, so a reachable port is a brute-force target.

Connect the CLI

Binary
Docker

solver status

The CLI targets http://localhost:7171 by default; set SOLVER_SERVER only if you changed SOLVER_HTTP_PORT.

The CLI ships inside the image, so alias it through the supervised container from Keep It Running:

alias solver='docker exec -it solverd solver'
solver status

Inside the container the daemon is already on localhost:7171 — no SOLVER_SERVER needed.

Every solver … command on the rest of this page now works verbatim in either setup. solver status is a liveness ping, not a health check of the trading loop. For machine output, global flags come before the subcommand: solver --json market list — the other order fails.

Fund the Wallet

solver address   # prints the Offchain (Ark) and Boarding (onchain) addresses

Fund the offchain address directly from a supported wallet such as arkade.money — no settle step needed. Or send mainnet BTC to the boarding address and pull it into Arkade:

solver settle    # joins a batch swap — can take minutes
solver balance

Funding is wallet-level; markets carry no balance of their own. Commands that move funds take --password, read SOLVER_PASSWORD, or prompt on a TTY. Later: solver send --to ark1… --amount <n> [--asset <id>] and solver exit --to bc1… --amount <sats> (BTC only).

Add a Market

solver market add \
  --base BTC \
  --quote <asset-id> \
  --price-feed "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd" \
  --min-base 1000 --max-base 100000 \
  --min-quote 10000 --max-quote 1000000 \
  --tolerance 100 \
  --fee 20

Flag	Meaning
`--base`, `--quote`	Asset id, or the literal `BTC`
`--price-feed`	URL returning the reference price, quote-per-base
`--price-path`	RFC 6901 JSON pointer to the price, e.g. `/bitcoin/usd`
`--min-`, `--max-`	Bounds per direction; `--max-* 0` disables that direction
`--tolerance`	Max deviation from the feed price, bps (default 10, cap 5000)
`--price-ttl`	Seconds a fetched price stays usable (default 15, cap 3600)
`--fee`	Your margin in bps, folded into the acceptance price (cap 5000)

Any JSON feed works. The price is located by the --price-path pointer; it is auto-derived only for URLs containing binance (pointer /price) and URLs carrying both ids= and vs_currencies= parameters. Every other feed requires --price-path, or the market fails to quote. Prices are fetched when an offer arrives — not on a schedule — and cached for the TTL; if the feed errors, the cache serves until it is six TTLs old, then quoting stops. A fill in that window executes at the cached price: at the default 15-second TTL that is at most 90 seconds stale, at the 3600 cap up to six hours. Set --price-ttl to the staleness you can afford. Asset decimals resolve from the indexer automatically. Set --min-base and --min-quote explicitly on every enabled direction. They default to 0, which the daemon accepts but the public registry rejects. With a funded wallet and one market enabled, the solver is live.

Verify and Operate

solver market list
solver market get --base BTC --quote <asset-id>
solver trades --limit 20

Failed fills appear in solver trades, but the failure reason is only in solver --json trades. Three more things worth knowing:

solver market update merges client-side with no version check — don’t edit the same market from the CLI and web UI at once, the second write silently wins.
solver market remove has no confirmation prompt. It stops future acceptance and leaves published offers unchanged.

Automate It

solver --json <command> is the supported automation interface: raw JSON on stdout, error: on stderr with exit code 1. The one documented HTTP endpoint is the liveness probe, GET /v1/status → {"running":true}. The rest of the HTTP and gRPC surface exists to serve the bundled CLI and web UI. It is unauthenticated, unversioned, and not a public API — keep it off the network and do not build against it. If you need a real integration surface, write to [email protected].

Get Discovered

A funded market does not make you findable. Wallets learn about you from a solver card — hand it out privately, publish your own registry, or list in the public one.

Get Discovered

Generate your solver card and choose how wallets find you.

Protocol Reference

The index of the focused Intents reference pages.

Understand Intents

Build with Intents

Earn Fees

Reference

Before You Start

Install

Run the Daemon

Keep It Running

Keep the Daemon Private

Connect the CLI

Fund the Wallet

Add a Market

Verify and Operate

Automate It

Get Discovered

Get Discovered

Protocol Reference

​Before You Start

​Install

​Run the Daemon

​Keep It Running

​Keep the Daemon Private

​Connect the CLI

​Fund the Wallet

​Add a Market

​Verify and Operate

​Automate It

​Get Discovered

Get Discovered

Protocol Reference

Before You Start

Install

Run the Daemon

Keep It Running

Keep the Daemon Private

Connect the CLI

Fund the Wallet

Add a Market

Verify and Operate

Automate It

Get Discovered