Bitswarm — Agent playbook

Copy-paste commands for LLM/agent runners.

Clone first (Gitkey):

./bin/gitkey clone \
  https://www.gitkey.dev/r/bitswarm/announce.json \
  ./bitswarm
cd ./bitswarm
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export BASE=http://127.0.0.1:8765
export LUD16=YOU@lexe.app
# optional NWC for paying (never commit / echo the URI):
# export OPEN_SWARM_NWC_FILE=/path/to/nwc.json

Exit codes (thick CLI): 0 ok · 1 error · 2 usage/blocked · 3 pay/claim failed.

Legal: allowlisted SPDX fixtures only on the site catalog. Local magnets stay local.

1) Catalog poll (JSON)

python thick-client/seed_cli.py catalog --api "$BASE" | jq '{count,allowlist,ids:[.items[].id]}'
curl -sS "$BASE/api/catalog" | jq '.items[]|{id,spdx,piece_count}'

2) Seed-to-earn (register lud16 + BT seed)

python thick-client/seed_cli.py seed \
  --api "$BASE" \
  --fixture legal-torrent-seed \
  --lud16 "$LUD16" \
  --seconds 12 \
  --json | jq '{ok,payee,bittorrent,license_spdx}'

Register only (no listen):

python thick-client/seed_cli.py seed --register-only --fixture legal-torrent-seed --lud16 "$LUD16" --json

3) Pay-per-piece (model stub)

Invoice only (agent shows QR / bolt11 to user):

python thick-client/seed_cli.py get \
  --api "$BASE" \
  --fixture tiny-lm-demo \
  --piece 0 \
  --invoice-only --json | jq '{ok,invoice_id,amount_sats,payee,memo,bolt11_prefix}'

Pay with NWC + claim + save bytes (agent wallet path):

python thick-client/seed_cli.py get \
  --api "$BASE" \
  --fixture tiny-lm-demo \
  --piece 0 \
  --nwc-file "$OPEN_SWARM_NWC_FILE" \
  --pay --save /tmp/oswarm-piece0.bin --json | jq '{ok,paid,claimed,verified,saved,payee,amount_sats}'

Whole-file:

python thick-client/seed_cli.py get --fixture tiny-lm-demo --whole --invoice-only --json

4) Prove no illegal index

python thick-client/seed_cli.py seed-local \
  --magnet 'magnet:?xt=urn:btih:deadbeefdeadbeefdeadbeefdeadbeefdeadbeef' \
  --lud16 "$LUD16" --prove-blocked --json | jq '{ok,local_only,site_blocked}'

5) Web UI paths (human / browser agent)

See DEMOS.md for evidence paths and expected outcomes.