Command Reference

Command Reference

Two programs. xrpl-trade proposes (never signs, never sees the seed). xrpl-sign signs — and only after the human has already approved that exact proposal hash. The --approve flag is not the approval: a CLI flag can never be human authorization. Global flag: --network {mainnet,testnet,devnet} selects a network for supported commands. It never reclassifies an existing credential. Mainnet signing requires a named profile bound to the proposal's network and account.

Conventions: --amount is always BASE units, --price is always QUOTE per BASE. Bare buy/sell default to the XRP/RLUSD pair.

Reading (no seed, no proposals, no approval)

balance [address] — XRP + trustline balances.

xrpl-trade balance
xrpl-trade balance r…

quote --pair P [--limit N] — order book top-of-book for any pair.

xrpl-trade quote --pair XRP/RLUSD
xrpl-trade quote --pair ARMY/XRP --limit 10
# explicit issuers also work:
xrpl-trade quote --base FUZZY --base-issuer r… --quote XRP

pairs — list approved pairs from ~/.xrpl/approved.json.

xrpl-trade pairs

inspect-token --currency C --issuer r… — issuer risk before you touch a token: verified domain, transfer fee, global-freeze / no-freeze flags.

xrpl-trade inspect-token --currency FUZZY --issuer r…

plan-trade --pair P --side {buy,sell} --amount A --price Px — read-only estimate: expected fill, price impact vs. mid, max spend.

xrpl-trade plan-trade --pair ARMY/XRP --side buy --amount 1000 --price 0.005

reconcile --hash H — validated ledger outcome of a submitted transaction (prefix of the hash is fine).

xrpl-trade reconcile --hash a2c72140

Writing (propose → human approves the exact hash → sign)

buy --pair P --amount A --price Px [--expires-in S] — propose buying BASE with QUOTE at a limit price. Expiry default 3600s, max 86400s.

xrpl-trade buy --pair XRP/RLUSD --amount 5 --price 1.52
xrpl-trade buy --pair ARMY/XRP --amount 1000 --price 0.005 --expires-in 600

sell --pair P --amount A --price Px [--expires-in S] — propose selling BASE for QUOTE at a limit price.

xrpl-trade sell --pair XRP/RLUSD --amount 5 --price 1.58

trustline (--pair P | --currency C --issuer r…) [--limit N] — propose a trustline (required before holding/trading any IOU).

xrpl-trade trustline --currency FUZZY --issuer r… --limit 1000000
xrpl-trade trustline --pair ARMY/XRP --limit 5000

cancel --seq N — propose cancelling the open offer with sequence N.

xrpl-trade cancel --seq 107197109

send --to r… --amount A [--ccy C] [--issuer r…] [--destination-tag N] — propose a payment. Only to allowlisted (address, tag) destinations.

xrpl-trade send --to r… --amount 10 --ccy XRP
xrpl-trade send --to r… --amount 50 --ccy RLUSD --issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De --destination-tag 12345

NFTs (v0.5)

nft-stage --file F --name N [--description D] [--royalty-bps B] [--taxon T] (v0.6.0) — validate + hash the artwork LOCALLY with zero network calls, then print a stage id. --file is required and must live inside the NFT media directory (~/.xrpl/media by default). --name is required. --royalty-bps defaults to 1000 (10%) and is immutable after mint; --taxon defaults to 0. Fully local: no IPFS, no ledger, no proposal.

xrpl-trade nft-stage --file ~/.xrpl/media/art.png --name \"Neon Drift\" --description \"Series 1, piece 3\"

nft-pin-and-propose --stage ID --approve-stage <full-sha256> — compare the independently reviewed full stage digest before credentials or upload are accessed, pin the staged art + metadata JSON to IPFS (external write via Muse's vault-provided Pinata credential), then PROPOSE the NFTokenMint. Pinning is an external write; unreferenced content can remain if a later step fails.

xrpl-trade nft-pin-and-propose --stage <stage-id> --approve-stage <full-reviewed-stage-sha256>
# → prints the full ceremony + proposal hash
# → NOTHING moves until a human approves that exact hash

nft-list --token-id ID --price-xrp P [--destination r…] [--expires-in S] — propose listing an owned NFT for sale. XRP only, sell offers only, ledger expiry required (default 24h). --destination makes it a private sale.

nft-inventory [address] — NFTs owned by an account (read-only).

nft-send --token-id ID --to <name|r-address> [--expires-in S] (v0.5.2) — propose gifting/transferring an NFT. Resolves the recipient from your favorites (case-insensitive) or a classic address. Creates a 0-XRP transfer offer with required expiry (default 24h) — the recipient must accept to claim it; accepting goes through nft-buy (needs the buy-side policy toggle on).

xrpl-trade nft-send --token-id 0009…B2B6 --to gridwizard

nft-buy --offer-index I — verify the sell offer from the ledger, then propose accepting it (XRP only). Re-verifies at signing time; refuses buy offers and IOU amounts.

nft-bid --token-id ID --seller r… --price-xrp P — propose a buy offer (bid). Disabled by default — opt in via the nft policy section.

nft-new — new mints from your favorite artists, with prices and xrp.cafe links (read-only).

Favorites (v0.5)

favorites add <name> <address> — watch an artist wallet (local file). favorites list, favorites rename <old> <new>, favorites remove <name>. Read-only, no approvals.

XRPresso discovery (v0.5.1)

Anonymous read-only search of the XRPresso marketplace (no key). Every result carries an xrpresso.io deep link — you buy in their UI.

xrpresso listings [--q …] [--sort …] — marketplace listings. xrpresso nfts — XRPresso-native NFT listings. xrpresso auctions — live auctions. xrpresso listing <id> — full detail. xrpresso stats — aggregates. xrpresso categories — category keys.

Profile (v0.5.3)

profile init — interactive questionnaire: display name, watch-only addresses, memberships, interests, alert preferences. Stored locally in ~/.xrpl/profile.json (owner-only 0600, schema v1). Never asks for a seed — seed-like input is refused with a warning and never stored.

profile show — print the current profile.

profile set <key> <value> — keys: display_name, alerts.price_moves, alerts.threshold_pct.

xrpl-trade profile set display_name \"Mike\"
xrpl-trade profile set alerts.threshold_pct 3

profile add-address r… / remove-address — watch-only XRPL addresses (checksum-verified; seed-like strings refused, never stored).

profile add-membership <tag> / remove-membership — open membership tags (e.g. xaodao).

profile add-interest <tag> / remove-interest — open interest tags (e.g. trading).

profile clear — delete the profile.

The profile never leaves your machine: no network, no proposals, no signing. Memberships drive reminders (e.g. DAO vote reminders), alert settings drive price-move alerts, interests personalize menus.

Giveaway (v0.6.0)

Newly public in v0.6.0 — a Friday community giveaway paid from the donation wallet. Entry = exactly 1 drop to the donation wallet with destination tag 777, and entrants must also have at least one other wallet action.

giveaway opt-in — PROPOSE an opt-in 1-drop payment (destination tag 777) to the donation wallet. It requires the normal human approval of the full proposal hash before signing.

xrpl-trade giveaway opt-in

giveaway entrants — list eligible entrants (read-only).

giveaway draw — the verifiable Friday draw. Winner selection is sha256(ledger_hash + \":\" + opt-in hashes in address order) mod N — selection-only and independently verifiable against the ledger by anyone.

giveaway status — entrants, giveaway config, and donation-wallet inventory (read-only).

giveaway gift --to <winner> --amount <n> --ccy XRP — PROPOSE a gift from the donation wallet. A human approves the exact proposal hash for each gift — never auto-sends.

xrpl-trade giveaway gift --to rWinner… --amount 5 --ccy XRP

giveaway setup — write the narrow giveaway signing policy (donation-wallet scope only). Mainnet credentials must come from Muse's secure vault; local giveaway seed files are testnet-only.

giveaway announce — draft the winner announcement text (no ledger write).

Wallet (v0.8 remediation)

Mainnet credentials are vault-only. Local testnet credentials use a separate typed, owner-only file bound to network and account; they are not signer fallbacks for mainnet.

wallet create --network testnet [--force] — generate a testnet wallet; local credentials are network-tagged and stored separately. Mainnet creation is refused; create mainnet credentials in your secure vault.

xrpl-trade wallet create --network testnet

wallet backup --network testnet — testnet-only backup flow. Mainnet backup/display is refused; keep mainnet credentials in your vault.

xrpl-trade wallet backup --network testnet

wallet forget-seed removes legacy disk seed material only after the explicit wallet-address confirmation. A fresh account needs the current ledger reserve to activate on mainnet. Testnet accounts can use xrpl-trade faucet --network testnet.

Setup & utilities

xrpl-trade setup — interactive. By default, register an existing public address and network; optionally generate a local wallet only on testnet/devnet. Mainnet credentials must be provisioned in the secure vault. xrpl-trade faucet --network {testnet,devnet} — free play-money for a fresh wallet. (No mainnet faucet exists — that's the point.)

xrpl-sign --hash H — check a proposal against policy, print the transaction-derived summary. Signs nothing. A short hash prefix is fine for this read-only check. xrpl-sign --profile <name> --hash <full-64-char-hash> --approve — mainnet requires a named profile and exact full hash. Muse must gate the call and bind real human approval to immutable operation inputs; the flag alone is not approval. Verifies the envelope, enforces policy, signs, submits, waits for a validated result, and audit-logs it. xrpl-sign --list — pending (unapproved) proposals. xrpl-sign init-policy — write the default ~/.xrpl/policy.json (testnet-locked). xrpl-sign migrate-policy — upgrade a v2/v3 policy file, keeping a .bak.

xrpl-sign init-profiles — generate named profile bindings from the configured public account/policy settings. Review profiles before use. xrpl-sign sync-profile --profile <name> — refresh the policy digest after a deliberate, reviewed policy change; old proposals must be rebuilt. xrpl-sign recover-state — validate state without changing it. For an explicit recovery, provide the damaged source digest and an independently reviewed replacement file/digest; the original is preserved. xrpl-sign migrate-state --profile <name> --legacy-state {default,giveaway} — move validated legacy obligations into the stable profile accounting namespace using the full source and reviewed replacement digests. xrpl-trade doctor — read-only local profile, signer/helper, file protection, and accounting diagnostics. It cannot verify Muse's actual vault or protected runtime boundary.

What the signer rejects (fail-closed highlights)

• Proposals older than 24h, or with created_at far in the future
• Short approval hashes, profile/account/network mismatches, or changed profile/policy digests
• Envelope/account/action mismatch, or orientation (buy/sell) not matching the actual TakerPays/TakerGets
• Any transaction type outside the policy's allowed_tx_types (defaults: OfferCreate/OfferCancel/TrustSet/Payment, plus NFTokenMint/NFTokenCreateOffer/NFTokenAcceptOffer once you opt into NFTs)
• Smuggled fields: Paths, SendMax, DeliverMin, Memos, partial-payment flags, TxnSignature/SigningPubKey in proposals
• NaN/Infinity amounts, fees, or sequences
• Pairs not in ~/.xrpl/approved.json, or issuers that don't match
• Assets with no spend_limits entry (blocked, not defaulted)
• Limit prices > max_deviation_bps from the depth-weighted book reference
• Books that are one-sided, thinner than min_book_depth, or wider than max_spread_bps
• Payments to non-allowlisted destinations; tag conflicts; tag-required destinations without a tag (fails closed even on lookup errors)
• Offers living longer than max_offer_lifetime_seconds
• Seed that is not an enabled master key or validated RegularKey for the proposal account
• Unauthorized master/RegularKey according to the validated ledger
• Mainnet local credentials, mainnet wallet seed creation, and seed backup
• Corrupt accounting, incomplete history coverage, or ambiguous submission
• Policy/state files not owner-only 0600