Run a Delegate Server

A delegate renews users’ VTXOs before batch expiry without holding their keys. Fulmine, Ark Labs’ wallet daemon, can run as a headless delegate.

What you’re running

Fulmine is a wallet daemon that doubles as delegate infrastructure: clients hand it presigned, tamper-proof settlement intents and it submits them in a batch swap before their VTXOs expire — fully self-custodial (see Settlement Intent Delegation for the model). The delegate service signs batch transactions with the wallet’s key, so a wallet must be created and unlocked before the Delegate API becomes ready. You do this once; after that, FULMINE_UNLOCKER_* auto-unlock keeps the delegate live across restarts. Fulmine has no flag to hide the Web UI; just ignore it. Fulmine listens on three ports:

Port	Env var	Purpose
`7000`	`FULMINE_GRPC_PORT`	gRPC API (not needed for a delegate-only deployment)
`7001`	`FULMINE_HTTP_PORT`	REST API (mounted under `/api`) and Web UI; delegation status lookups
`7002`	`FULMINE_DELEGATE_PORT`	Delegate API — info and submission, served at `/v1/...` (no `/api` prefix)

Prerequisites

Docker — the quickest way to run Fulmine.
jq — used below to pipe the generated key straight into the next call.
The mainnet Arkade Service URL: https://arkade.computer.

Fulmine’s REST and gRPC interfaces are not authenticated. Do not expose them to the public internet — keep the daemon on a private network or behind a reverse proxy with its own access control.

Quickstart with Docker

Start Fulmine with delegation enabled

Set the password once as a shell variable — the rest of the quickstart reuses it, so there is nothing to retype. Use a strong value: at least 8 characters with a number and a special character.

export FULMINE_PASSWORD='CHANGE_ME'

docker run -d --name fulmine \
  -p 7001:7001 -p 7002:7002 \
  -e FULMINE_ARK_SERVER="https://arkade.computer" \
  -e FULMINE_DELEGATE_ENABLED=true \
  -e FULMINE_DELEGATE_FEE=0 \
  -e FULMINE_UNLOCKER_TYPE=env \
  -e FULMINE_UNLOCKER_PASSWORD="$FULMINE_PASSWORD" \
  -e FULMINE_DISABLE_TELEMETRY=true \
  -v fulmine-data:/app/data \
  ghcr.io/arklabshq/fulmine:latest

This publishes the HTTP port (7001, for status lookups and the Web UI) and the delegate port (7002, the Delegate API). The gRPC port (7000) is intentionally left unpublished — it isn’t needed for a delegate-only deployment.

Telemetry is on unless you turn it off, so FULMINE_DISABLE_TELEMETRY=true is set explicitly here.

Create the wallet (one-time only)

Generate a mnemonic, create the wallet, then unlock it. The mnemonic never leaves your shell, so there is nothing to copy by hand. Auto-unlock handles every subsequent restart.

# 1 — generate a 12-word mnemonic and hold it in a shell variable
MNEMONIC=$(curl -s http://localhost:7001/api/v1/wallet/genseed | jq -r .mnemonic)
echo "$MNEMONIC"   # ← back this up now, before going any further

# 2 — create the wallet
curl -s -X POST http://localhost:7001/api/v1/wallet/create \
  -H "Content-Type: application/json" \
  -d "{\"mnemonic\":\"$MNEMONIC\",\"password\":\"$FULMINE_PASSWORD\",\"serverUrl\":\"https://arkade.computer\"}"

# 3 — unlock (needed only now; restarts auto-unlock from here on)
curl -s -X POST http://localhost:7001/api/v1/wallet/unlock \
  -H "Content-Type: application/json" \
  -d "{\"password\":\"$FULMINE_PASSWORD\"}"

Both create and unlock return {} on success.

Back up $MNEMONIC before you go on — those 12 words are your wallet seed, and losing them means losing the delegate key.

When an unlocker is configured, Fulmine creates the wallet with the unlocker’s password and ignores whatever create sends — so the two must agree, or auto-unlock will fail on the next restart. Driving both from $FULMINE_PASSWORD keeps them in sync.

Verify the delegate is live

The Delegate API is served on port 7002 at /v1/... (no /api prefix):

curl http://localhost:7002/v1/delegate/info
# → {"pubkey":"02a26861...","fee":"0","delegatorAddress":"ark1qzpq904...","delegateAddress":"ark1qzpq904..."}

A response with a pubkey means the delegate is ready for clients. Before the wallet is created and unlocked, this endpoint fails with service not ready instead.

delegateAddress is the delegate’s own offchain address, where clients pay your service fee. It is always present — including while FULMINE_DELEGATE_FEE is 0 — and is stable across restarts, which matters because clients build their intent proofs against it. The response repeats it under a deprecated delegatorAddress alias; prefer delegateAddress.

Essential environment variables

Fulmine is configured entirely through FULMINE_-prefixed environment variables — there are no CLI flags. These are the ones that matter for a headless delegate:

Variable	Example (mainnet)	Purpose
`FULMINE_ARK_SERVER`	`https://arkade.computer`	Arkade Service the daemon connects to
`FULMINE_DELEGATE_ENABLED`	`true`	Turns on delegate functionality (default `false`)
`FULMINE_DELEGATE_PORT`	`7002`	Delegate server port (must differ from gRPC/HTTP)
`FULMINE_DELEGATE_FEE`	`0`	Service fee applied by the delegate (default `0`)
`FULMINE_UNLOCKER_TYPE`	`env`	Auto-unlock on restart: `env` (password in env var) or `file` (password file)
`FULMINE_UNLOCKER_PASSWORD`	`YourStr0ng!Pass`	Wallet password for the `env` unlocker
`FULMINE_DISABLE_TELEMETRY`	`true`	Turns telemetry off — it is on unless you set this
`FULMINE_DATADIR`	`/app/data`	Data directory — image default, persisted by the volume

The env unlocker keeps the quickstart short, but the password is then visible to anyone who can run docker inspect on the container. In production prefer the file unlocker, which reads the password from a mounted file you can lock down with filesystem permissions. See the Fulmine repo for the full configuration.

How a wallet uses your delegate

Once your server is up, a client wallet uses it in three steps:

Discover — the wallet calls GET /v1/delegate/info (port 7002) to read your delegate pubkey, fee, and address, then builds a delegated address with an operator + user + delegate spend path.
Delegate — the wallet submits a presigned intent and forfeit transactions to POST /v1/delegate (port 7002). The intent is bound by a time window and signed with BIP322, so your server cannot alter or redirect the funds — only submit what was authorized.
Renew — your server watches those VTXOs and submits the intent in a batch swap just before expiry. Status can be tracked via GET /api/v1/delegates on the HTTP port (7001), which accepts status (pending, completed, failed), limit, and offset query parameters.

# Submit a delegation (client side) — Delegate API on port 7002
curl -X POST http://localhost:7002/v1/delegate \
  -H "Content-Type: application/json" \
  -d '{"intent": {"message": "{\"vtxos\": [...]}", "proof": "<base64 psbt>"}, "forfeitTxs": ["<base64 psbt>"]}'

The info endpoint is also exposed at /v1/delegator/info as a legacy alias, but /v1/delegate/info is preferred. For a complete client-side example of building the intent and forfeit transactions, see the TS-SDK delegate.js example.

Next Steps

VTXO Management

Automatic renewal and recovery from the client side

Settlement Intent Delegation

The delegation workflow and security model in depth

Fulmine Reference

The wallet daemon powering your delegate

Fulmine on GitHub

Source, releases, and full configuration

Getting Started

Bitcoin

Advanced Features

What you’re running

Prerequisites

Quickstart with Docker

Essential environment variables

How a wallet uses your delegate

Next Steps

VTXO Management

Settlement Intent Delegation

Fulmine Reference

Fulmine on GitHub

​What you’re running

​Prerequisites

​Quickstart with Docker

​Essential environment variables

​How a wallet uses your delegate

​Next Steps

VTXO Management

Settlement Intent Delegation

Fulmine Reference

Fulmine on GitHub

What you’re running

Prerequisites

Quickstart with Docker

Essential environment variables

How a wallet uses your delegate

Next Steps