reapp-protocol-cli

Run the REAPP payment flow from a terminal: scaffold config, create testnet accounts, authorize an AP2 mandate, and make agent-signed payments through the live MandateRegistry contract on Stellar.

reapp-protocol-cli is the command-line entry point for REAPP, a protocol for agent-driven payments where the spending limit lives inside a Soroban smart contract instead of the application. The CLI is deliberately thin: it prepares inputs, signs with the correct testnet key, and sends transactions, but the contract is the source of truth for scope, budget, expiry, replay protection, and settlement.

Testnet only. Keys generated by the CLI are throwaway testnet burners, stored outside your repo, and must never be reused on mainnet.

Package version: [email protected]. Installed command: reapp.

Install

npx [email protected] --help

For repeated use, install the package globally. The installed command is reapp.

npm install -g [email protected]
reapp --help

Quick start

The fastest way to see the full flow is one command:

npx [email protected] demo research-agent

The demo starts cold, creates three ephemeral testnet accounts, registers a real mandate, approves the contract allowance, and has an agent buy research sources one at a time. Each purchase is a real on-chain execute_payment. The mandate budget covers three purchases; the fourth is rejected by the contract.

The command exits successfully only after it independently reads sequence 3, 3 XLM spent, a 3 XLM merchant balance increase, and the fourth contract rejection.

No LLM key is required. The research framing is scripted so the payment path is the thing under test.

Project flow

Use the step-by-step commands when you want a reusable local project instead of an ephemeral demo run.

reapp init
reapp setup
reapp mandate create
reapp pay
reapp settlement reconcile
reapp settlement acknowledge <TX_HASH>
reapp pay 10.00

reapp init writes a committable reapp.config.json with the network, contract id, explorer, demo price, and budget. reapp setup writes testnet burner secrets to ~/.reapp/credentials.json using restrictive file permissions. reapp mandate create stores the active mandate in ~/.reapp/mandate.json so reapp pay can rebuild the same mandate id.

Before any payment broadcast, the CLI signs the transaction, derives its exact hash and validity deadline, and fsyncs a private journal under REAPP_HOME. Concurrent processes race one atomic directory claim, so only one can submit. If RPC cannot confirm the result, every later pay or demo fails closed until reapp settlement reconcile queries that same hash. A confirmed success becomes a durable completed record and still blocks payment; only the human/application's exact reapp settlement acknowledge <TX_HASH> removes it. A confirmed failure, or an expired transaction whose complete validity window remains inside retained RPC history, can be cleared without acknowledgment because no payment landed.

The final reapp pay 10.00 is expected to fail after a default 3 XLM budget. The CLI surfaces that contract rejection as BudgetExceeded; it does not simulate the failure locally.

Commands

| Command | What it does | |---|---| | reapp init [-f] | Writes reapp.config.json in the current directory. | | reapp setup [-f] | Generates user, agent, and merchant testnet keys, then funds them through friendbot. | | reapp mandate create [-b <xlm>] [-e <seconds>] [-f] | Registers an AP2 mandate on-chain and approves the SEP-41 allowance to the contract. | | reapp pay [amount] | Makes an agent-signed payment against the active mandate. | | reapp settlement reconcile | Resolves the exact durable transaction hash before another payment is allowed. | | reapp settlement acknowledge <tx-hash> | Explicitly accepts one exact durably recorded success and reopens the payment path. | | reapp demo research-agent | Runs the complete budget-capped research-agent flow on testnet. |

How it works

The flow has three accounts and one contract.

1. The user owns the funds and authorizes the mandate.
2. The agent can request payment, but only by calling the contract.
3. The merchant is the single allowed payee.
4. The MandateRegistry validates the payment and transfers funds atomically.

The allowance goes to the contract, never to the agent or the CLI. If the agent key is compromised, if the CLI has a bug, or if a developer tries to skip a step, the contract still refuses out-of-scope payments, expired mandates, overspending, revoked mandates, invalid amounts, and replayed sequence numbers.

Files written by the CLI

| File | Safe to commit? | Purpose | |---|---:|---| | reapp.config.json | Yes | Network, contract id, explorer, demo price, and default budget. | | ~/.reapp/credentials.json | No | Testnet burner secrets for the user, agent, and merchant accounts. | | ~/.reapp/mandate.json | No | The active mandate inputs and transaction hashes for local reuse. | | ~/.reapp/pending-settlement/state.json | No | Crash-safe signed hash, sequence, and validity window retained until reconciliation. |

Set REAPP_HOME to relocate the private CLI state:

REAPP_HOME=/tmp/reapp-demo reapp setup

Network

The CLI defaults to Stellar testnet and reads the live MandateRegistry id from @reapp-sdk/stellar.

reapp init
cat reapp.config.json

The current config points at the upgradeable simple MandateRegistry:

CC6JMPDHRPBR2HBLJKRCIKV54HXDV2RFXDKW6MALQKWM6JEAJQHICRWE

You can edit reapp.config.json to point at a different compatible MandateRegistry contract without changing the CLI.

Relationship to the SDK

reapp-protocol-cli ships as a self-contained command bundle built on @reapp-sdk/core and @reapp-sdk/stellar. Use the CLI when you want to prove the protocol path from a terminal. Use the SDK packages when you are building the same flow into an app, agent, or service.

See the browser demo at reapp.live/cli.

License

Apache-2.0.