CLI
FurlPay CLI
@furlpay/cli is the terminal execution layer for FurlPay: multi-chain wallet connectivity, Hyperliquid perpetuals, Stellar tokenized-equity tooling, x402 micropayments, escrow and an MCP server for AI agents. Every execution surface is labeled at runtime — this documentation carries the same labels.
Read the status label before the command
The CLI is honest by construction: surfaces that move real value say
LIVE (SIGNED) and fail closed without credentials; surfaces that only run locally say SIMULATED or LOCAL LEDGER in their output. The matrix below is the web documentation's copy of that registry — when the CLI changes, this registry changes with it or the docs fail CI.Install
bash
npm install -g @furlpay/cli
furlpay --versionRequires Node.js ≥ 22.19.0. All installation methods — including the macOS/Linux and Windows scripts, npx, other package managers and offline installs from the signed release tarball — are documented on the installation page.
Capability matrix
Statuses are transcribed from the CLI's honesty matrix for release 0.4.0 and cross-checked against the release source. Do not treat a simulated surface as a dry run of a live one: it does not touch the network.
| Surface | Command | Status | What that means |
|---|---|---|---|
| Hyperliquid market data | furlpay market | LIVE | Real /info responses from Hyperliquid validators: mark price, funding, open interest, L2 order book, depth bands, OFI, micro-price. |
| Hyperliquid perpetual execution | furlpay hyperliquid trade | LIVE (SIGNED) | Real EIP-712 Phantom-Agent L1 orders. Requires HYPERLIQUID_PRIVATE_KEY (or ETH_PRIVATE_KEY) from the environment — never argv — and fails closed without one. Pre-trade risk engine enforced. |
| HLP vault statistics | furlpay earn hlp stats | LIVE | Equity, APY and all-time PnL derived from the live vaultDetails response. Fields the public API does not report (share price, position count) are shown as unavailable — never fabricated. |
| HLP deposit / withdraw | furlpay earn hlp deposit | LIVE (SIGNED) | Real signed L1 vaultTransfer actions; fail closed without a configured signer. Deposits and withdrawals carry a 4-day lockup. |
| Stellar transaction verification | furlpay tx verify <64-hex-hash> | LIVE (LOOKUP) | GET /transactions/{hash} against a real Horizon instance. Distinguishes CONFIRMED_SUCCESS, CONFIRMED_FAILED, NOT_FOUND, INVALID_HASH, UNAVAILABLE. It is an API lookup of finalized history — never claimed as cryptographic re-verification, and a 404 is explicitly not proof a transaction never existed. |
| Testnet faucet | furlpay faucet --address <G...> [--network testnet|futurenet] | LIVE | Real Friendbot funding on testnet/futurenet only; mainnet is refused outright — real XLM cannot be fabricated. FUNDED requires the Friendbot's own success response plus an independent Horizon balance check. |
| Configuration validation | furlpay config validate | LOCAL | Structural checks on the local config: canonical network passphrases, https endpoints, slippage/risk bounds, agent-trust cap consistency (single-tx cap may not exceed the daily cap). No network calls; non-zero exit on any error. |
| Diagnostics | furlpay doctor [--output json] | LIVE | Real install-method, registry and connectivity checks. --output json is machine-readable; exits non-zero when the API connectivity check fails so scripts can rely on it. |
| Escrow settlement | furlpay escrow create | LOCAL LEDGER | A deterministic state machine (CREATED → FUNDED → PROOF_SUBMITTED → RELEASED, with DISPUTED and refund paths) persisted at ~/.furlpay/escrows.json (atomic writes, 0600 on POSIX, symlink refusal). No on-chain escrow contract is deployed and no funds move except the transactions you reference via --tx-hash — which are never fabricated. Unauthorized actors, malformed proof hashes and tx-hash-less fund/release attempts fail closed. |
| x402 settlement | furlpay x402 pay | SIMULATED | No live TigerBeetle facilitator in this build. Responses are explicitly labeled SIMULATED / LOCAL_SIMULATION — an HTTP 402 challenge resolved here does not move real value. |
| Stellar SDEX order flow · Soroban swaps | furlpay trade limit | SIMULATED | Deterministic local simulation of Horizon/Soroban submission — no network transactions are broadcast in this build. Regulated-asset trade results carry sep8Status: not_performed; compliance is never claimed. |
| SEP-8 issuer authorization | furlpay rwa kyc | NOT IMPLEMENTED | NOT implemented in this build: prints what must be verified with the issuer and exits non-zero. It never reports an approval, and the registry carries no hardcoded APY or invented approval-server URLs. |
| FOBXX treasury sweep | MCP furlpay_sweep_treasury --target FOBXX | SIMULATED | No Stellar Benji contract call in this build; shares in the response are sample data, not a deposit record, and no APY is reported. The HLP target of the same tool is real and signed. |
| MCP balance (unauthenticated) | MCP furlpay_balance | SIMULATED | Sample fixture balances flagged simulated: true in unauthenticated mode. |
Where to go next
- Installation — npm, install scripts, offline tarball, updates and rollback.
- Quickstart — a first session end to end, on testnet where it matters.
- MCP server & agent security — connect Claude, Cursor or any MCP client; delegated agent keys and spend policies.
- Trading — live Hyperliquid execution vs simulated Stellar order flow, risk controls and the kill switch.
- Escrow & verification — the local escrow ledger, honest transaction verification, the testnet faucet and diagnostics.
CLI vs the hosted FurlPay API
The CLI is a local tool: Hyperliquid execution and market data run against those networks directly from your machine, and its Stellar order flow is a local simulation. The hosted FurlPay API (payment links, checkout, rails) is a separate product surface with its own availability registry — a capability existing in the CLI does not mean the hosted API offers it, and vice versa.
Never place private keys in command-line arguments
Execution surfaces read signers from the environment (
HYPERLIQUID_PRIVATE_KEY or ETH_PRIVATE_KEY) and wallet imports from stdin only. No FurlPay surface accepts a key as an argument, and no documentation example contains a real secret. See the trading guide for the exact fail-closed behavior.Did this page help?
Edit this page on GitHub