Overview

Getting started

Install the tooling, build the workspace, and run the full onboarding — generate a seed, derive your mining address, create a payable BOLT12 offer, and BIP-322 sign the OCEAN message.

Build from source

The repo root is a Cargo workspace. Build every crate at once:

cargo build --release --workspace
# Binaries: target/release/oceanln (CLI) and target/release/oceanln-httpd (server)

Install the CLI

By default oceanln embeds the published lexe SDK and runs the wallet in-process — no separate lexe-sidecar needed. Install from the oceanln-cli crate (the repo root is a virtual workspace, so --path . won't work):

cargo install --path oceanln-cli      # CLI binary `oceanln`
# optional: the local HTTP server for a web/desktop frontend
cargo install --path oceanln-httpd    # binary `oceanln-httpd`

terminal

The in-process build gives you the full CLI, including init and offer. See the CLI reference for every command.

One-shot onboarding

init --generate does the whole onboarding at once — it generates a fresh 24-word seed (printed once), derives the mining address to register with OCEAN, and provisions the on-chain Lexe wallet.

oceanln init --generate
# one shot: generate seed + provision wallet + print mining address

It also persists the seed to ~/.config/oceanln/seed (0600), so later offer / payout runs don't re-prompt. The seed is saved before the network call, so a provisioning failure never loses a freshly generated seed. Add --dry-run to derive the seed and mining address without provisioning (no network).

key

The mnemonic is printed once and never written anywhere but the seed file you control. Write it down — it is the root of both your mining key and your Lightning node.

Full flow, sidecar-free

Because init persists the seed, the later steps read it automatically — no piping between commands:

# Create the wallet (seed persisted to ~/.config/oceanln/seed) + print address.
oceanln init --generate --json > wallet.json
# {"mnemonic":"...","mining_address":"bc1q...","provisioned":true,"seed_file":"/home/you/.config/oceanln/seed"}

# Create the offer, then sign the OCEAN message for it — no seed piping needed.
OFFER=$(oceanln offer --json --description "OCEAN payout" \
          | python3 -c 'import sys,json;print(json.load(sys.stdin)["offer"])')

# Register the mining address + $OFFER on ocean.xyz, copy the message it gives you:
oceanln payout --offer "$OFFER" --message "<exact OCEAN message>"

OCEAN's flow is offer-first: you give it an offer, it generates the message embedding that offer, then you sign. Passing --offer makes payout skip offer creation entirely and sign fully offline. Next, read the full CLI reference or wire a UI to the HTTP API.