caput.dev configure your bot →

Configuration

Everything the bot reads at startup and what each setting does.

Environment variables

Set these in your config.env file or as environment variables on your host.

Required

CAPUT_TX_HASH — your license transaction hash. The bot verifies this exists on the XRP Ledger at startup. Without it, the bot enters bootstrap mode and prompts you through the admin UI.

CAPUT_SELLER_WALLET — your XRPL wallet address. The bot knows this address, never your seed. Every signing event goes through your wallet app.

Network

CAPUT_NETWORK — testnet (default) or mainnet. Controls which XRPL node the bot connects to. Start on testnet. Flip to mainnet only after completing the mainnet checklist in OPERATIONS.md.

The bot connects to wss://s.altnet.rippletest.net:51233 on testnet and wss://xrplcluster.com on mainnet.

Ports

CAPUT_ADMIN_PORT — default 7777. The admin UI is bound to localhost only. Never expose this to the internet. If you're behind a reverse proxy, only proxy the public port.

CAPUT_PUBLIC_PORT — default 8080. The buyer-facing surface. This must be reachable by buyers. Expose it via your reverse proxy or hosting platform's public URL.

Storage

CAPUT_DATA_DIR — default ~/.config/caput/. Where the bot stores state.json, usage.cml, encrypted blobs, and fulfillments. This directory is your single most important backup target.

Wallet

CAPUT_WALLET_ADAPTER — default xaman. Which wallet signing flow to use for the seller.

Value Description
xaman Xaman mobile app (push notification + QR code)
crossmark Crossmark browser extension
gem Gem Wallet browser extension
manual Display unsigned JSON, paste signed blob back

Contract defaults

These set the defaults in the admin UI. Can be overridden per-invitation.

CAPUT_DEFAULT_DURATION — default 10 days. Enum: 5, 10, 15, 30.

CAPUT_DEFAULT_PREMIUM — default 5 percent. Range: 3–10.

CAPUT_DEFAULT_MARGIN — default 10 percent. Enum: 5, 10, 15, 20.

CAPUT_MIN_NOTIONAL — default 5 XRP. Minimum deposit the seller will accept. Recommended: keep this at 5+ so reserve costs stay under 20% of notional.

Public URL

CAPUT_PUBLIC_HOST — the public hostname buyers will use to reach your bot. Example: https://mybot.railway.app. This is embedded in invitation URLs. If not set, invitations won't have a clickable link.

RLUSD

CAPUT_RLUSD_ISSUER — default rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De (Ripple's RLUSD issuer on mainnet). You should never need to change this unless testing with a custom token.

Example config.env

CAPUT_NETWORK=testnet
CAPUT_TX_HASH=ABC123...your_license_tx_hash
CAPUT_SELLER_WALLET=rYourSellerWalletAddress
CAPUT_WALLET_ADAPTER=xaman
CAPUT_ADMIN_PORT=7777
CAPUT_PUBLIC_PORT=8080
CAPUT_PUBLIC_HOST=https://mybot.railway.app
CAPUT_DEFAULT_DURATION=10
CAPUT_DEFAULT_PREMIUM=5
CAPUT_DEFAULT_MARGIN=10
CAPUT_MIN_NOTIONAL=5

Bootstrap flow

If the bot starts without a complete configuration, it enters bootstrap mode. Open the admin UI at http://localhost:7777 and walk through five steps:

  1. Set passphrase — encrypts pre-signed blobs and fulfillments. Minimum 8 characters. You'll need this on every restart. There is no recovery if you lose it.

  2. Verify license — enter your purchase transaction hash. The bot fetches the transaction from the chain, confirms it's a valid Payment to the caput receiving address, and extracts your tier (1, 5, or 100 uses) from the memo.

  3. Connect wallet — enter your seller XRPL address. The bot verifies the account exists on-chain. It stores the address, never the seed.

  4. RLUSD trust line — the bot checks if your wallet has a trust line to the RLUSD issuer. If not, it prompts you to set one up in your wallet app and provides the issuer address. Click "Check" after setting it up.

  5. Ready — all steps complete. The bot launches the dashboard, starts the engine poll loop, and you can begin creating invitations.

Changing configuration after bootstrap

Most settings can be changed by editing config.env and restarting the bot. The passphrase, license, and wallet are stored in the .caput/ directory and persist across restarts.

To change the seller wallet: edit state.json in the data directory and update the seller_wallet field. The bot will use the new address on restart. Note: any active positions are tied to the original wallet and must settle before changing.

To add more uses: purchase a new license bundle. The new license's uses stack on top of existing ones.

Host-specific setup

The bot runs the same on any host. What differs is how you expose the public port and persist the data directory.

Railway: set env vars in the dashboard. Create a volume for .caput/. Railway auto-assigns a public URL.

Render: set env vars in the service settings. Create a Render Disk mounted at the data directory. Use a paid plan (free tier sleeps).

Fly.io: set secrets via flyctl secrets set. Create a volume via flyctl volumes create. Mount in fly.toml.

Self-hosted: copy config.env to the working directory. Use systemd for auto-restart. Set up nginx/caddy as reverse proxy. Back up the data directory via cron.