FurlPay Docs
Open App
  • Services & Availability
  • Quickstart
  • For AI Agents
  • FurlPay CLInew
  • Installationnew
  • CLI Quickstartnew
  • MCP Server & Agent Securitynew
  • Tradingnew
  • Escrow & Verificationnew
  • Monorepo
  • API Routes
  • Authenticationupdated
  • Webhook Eventsupdated
  • Error Codesupdated
  • Rate Limitsnew
  • Configuration & Setupnew
  • Merchant Paymentsnew
  • Payroll & Payoutsnew
  • Agentic Payments (x402)updated
  • Agent Trust & Mandates (TAP)updated
  • CCTP Cross-Chainupdated
  • LI.FI Swapsupdated
  • FurlPay Travels (Travel MCP)updated
  • Solana Actions & Blinks
  • Settlement Workspacenew
  • FURL Tokennew
  • Claude Connectorupdated
  • AI Assistants
  • Circlenew
  • Ramp Providersnew
  • Telegram Mini Appnew
  • Stripe Crypto
  • Persona KYC
  • Regulatory status
  • Screening & Casesnew
  • Security Postureupdated
  • Signing & WebAuthnupdated
  • Help Center
  • Getting Started
  • KYC Verification
  • Passkeys & Biometrics
  • Privacy & Data Protection
  • Transaction Statuses
  • Gasless Transfers
  • Deposits & Withdrawals
  • Managing Virtual Cards
  • Freezing & Unfreezing Cards
  • Declined Transactions
  • SDK & API Support
  • x402 Monetization Basics
  • Booking Travel
  • Travel Refunds & Cancellations

Resources

  • Changelog
  • System Status
  • OpenAPI Spec
  • Community
  • GitHub
Docs/CLI/Escrow & Verification

CLI

Escrow & transaction verification

The CLI's escrow is a durable local ledger — not an on-chain contract — and its verification commands report exactly what a lookup proves and what it does not. This page is the honest contract for both.

Escrow — a local state machine

LOCAL LEDGER

A deterministic escrow state machine persisted across invocations in ~/.furlpay/escrows.json (atomic writes, 0600 on POSIX, symlink refusal). States: CREATED → FUNDED → PROOF_SUBMITTED → RELEASED, with DISPUTED and refund paths. Every transition is appended to an immutable audit log (furlpay escrow status --verbose).

bash
# Create with a pre-agreed SHA-256 delivery proof commitment
furlpay escrow create \
  --seller 0x... --arbiter 0x... \
  --amount 5000 --timeout-days 7 \
  --proof-hash 0x<sha256 of the deliverable>

# Fund — requires the REAL funding transaction hash; the CLI never fabricates one
furlpay escrow fund --escrow-id escrow_<id> --tx-hash 0x<your funding tx>

# Seller submits the cryptographic delivery proof
furlpay escrow proof --escrow-id escrow_<id> --hash 0x<sha256> --signature <sig>

# Release (buyer approval; auto-release timer also supported)
furlpay escrow release --escrow-id escrow_<id> --tx-hash 0x<settlement tx>

# Dispute for arbiter resolution
furlpay escrow dispute --escrow-id escrow_<id> --reason "delivery did not match spec"
  • No on-chain escrow contract is deployed and no funds move except the transactions you reference via --tx-hash — which are never fabricated by the CLI.
  • Unauthorized actors, malformed proof hashes and tx-hash-less fund/release attempts fail closed.
  • The escrow ledger lives in ~/.furlpay; deleting that directory deletes every escrow record irreversibly.

Transaction verification — what a lookup proves

LIVE (LOOKUP)
bash
furlpay tx verify <64-hex-hash> [--network mainnet|testnet] [--output json]

Performs GET /transactions/{hash} against the documented Horizon endpoint for the selected network and reports one of five outcomes:

OutcomeExitMeaning
CONFIRMED_SUCCESS0Real transaction, found in finalized ledger history, successful on-chain.
CONFIRMED_FAILED1Real transaction, found, but it failed on-chain. This is evidence about the past, not a promise about a retry.
NOT_FOUND1No transaction at that hash. Explicitly NOT proof that a transaction never existed.
INVALID_HASH1The argument is not a valid 64-character hash.
UNAVAILABLE1Horizon could not be reached. An outage is never evidence about the transaction.

An API lookup is not cryptographic re-verification

The command queries finalized ledger history; it does not re-execute signature checks itself, and a 404 is explicitly not reported as "does not exist". Treat CONFIRMED_SUCCESS as strong evidence from the network's own history API — and treat everything else as "unknown", not as a negative proof.

Testnet faucet — real funding, mainnet refused

LIVE
bash
furlpay faucet --address G... --network testnet    # or --network futurenet

Uses the official Stellar Friendbot on testnet/futurenet only; mainnet is refused outright because real XLM cannot be fabricated. FUNDED is reported only on the Friendbot's own successful response, together with the funding transaction hash and an independent Horizon balance check.

Diagnostics — validate config, check the doctor

bash
furlpay config validate [--output json]
furlpay doctor [--output json]
  • config validate LOCAL checks the local config structurally: canonical network passphrases, https endpoints, slippage/risk bounds, and agent-trust cap consistency. No network calls; non-zero exit on any error.
  • doctor LIVE runs real install-method, registry and connectivity checks. In JSON mode it exits non-zero when the API connectivity check fails, so scripts can rely on the exit code.

Distribution security

  • npm installs are integrity-checked by the registry; the package publishes with npm provenance (sigstore, OIDC-bound to the release repo and workflow).
  • GitHub release assets (tarball, checksums.txt, CycloneDX SBOM) carry build-provenance attestations: gh attestation verify --repo FurlPay/furlpay-cli <file>.
  • Release builds are gated on tag/version consistency, full typecheck and tests, and a three-OS smoke install (CLI boot + MCP stdio handshake) of the packed tarball before anything is published.
  • No postinstall scripts; no secrets in the package; CI actions are SHA-pinned.
Did this page help?
Edit this page on GitHub

← Previous

Trading

Next →

Monorepo