@ackrate/cli

Run the Ackrate 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.

@ackrate/cli is the command-line entry point for Ackrate, 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, delegates signing to the selected signer, and sends transactions, but the contract is the source of truth for scope, budget, expiry, replay protection, and settlement.

Testnet is the safe default. Keys generated by ackrate setup are throwaway testnet burners and must never be reused on mainnet. The one-command mainnet flow is separately manifest-gated, uses canonical Circle USDC, and signs through named Stellar CLI identities rather than accepting secrets in arguments.

Package version: @ackrate/[email protected]. Installed command: ackrate.

Install

npm install -g @ackrate/cli
ackrate --help

Quick start

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

ackrate demo research-agent --network testnet

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.

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

ackrate init writes a committable ackrate.config.json with the network, contract id, explorer, demo price, and budget. ackrate setup writes testnet burner secrets to ~/.ackrate/credentials.json using restrictive file permissions. ackrate mandate create stores the active mandate in ~/.ackrate/mandate.json so ackrate 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 ACKRATE_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 ackrate settlement reconcile queries that same hash. A confirmed success becomes a durable completed record and still blocks payment; only the human/application's exact ackrate 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 ackrate 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.

If ackrate pay reports payment blocked by unresolved journal state, a previous session left a settlement unacknowledged in ~/.ackrate. This is the crash-safe lock working, not an error: run ackrate settlement reconcile and then ackrate settlement acknowledge <TX_HASH> to clear it. To evaluate the CLI from a completely clean state, point it at a throwaway home first:

ACKRATE_HOME=$(mktemp -d) ackrate setup

Commands

| Command | What it does | |---|---| | ackrate init [-f] | Writes ackrate.config.json in the current directory. | | ackrate setup [-f] | Generates user, agent, and merchant testnet keys, then funds them through friendbot. | | ackrate mandate create [-b <xlm>] [-e <seconds>] [-f] | Registers an AP2 mandate on-chain and approves the SEP-41 allowance to the contract. | | ackrate pay [amount] | Makes an agent-signed payment against the active mandate. | | ackrate settlement reconcile | Resolves the exact durable transaction hash before another payment is allowed. | | ackrate settlement acknowledge <tx-hash> | Explicitly accepts one exact durably recorded success and reopens the payment path. | | ackrate ops create | Binds one unsigned authority transaction to an immutable, human-readable signing request. | | ackrate ops verify | Independently verifies the request, network, transaction hash, source, and exact contract call. | | ackrate ops combine | Accepts exactly two different valid custodian signatures and emits the ready envelope. | | ackrate demo research-agent | Runs the complete budget-capped research-agent flow on testnet. |

Mainnet real-USDC flow

After the governed deployment manifest is completed and independently verified, the same command can execute a deliberately bounded real-USDC canary:

ackrate demo research-agent \
  --network mainnet \
  --manifest ./mainnet-deployment.json \
  --user-signer ackrate-canary-user \
  --agent-signer ackrate-canary-agent \
  --merchant G... \
  --price 0.01 \
  --budget 0.03 \
  --confirm-real-usdc

The command rejects an incomplete or noncanonical manifest, a non-mainnet RPC, a conflicting USDC issuer/SAC/decimals mapping, a paused registry, missing accounts, insufficient USDC, insufficient XLM fee headroom, reused actor accounts, and a budget that would not admit exactly three prices then reject the fourth. Mainnet never invokes Friendbot or creates a key. The signer identities must already exist in Stellar CLI secure storage or be backed by a connected device. Every prepared payment is pinned to its network and exact RPC in the crash-safe reconciliation journal.

Mainnet 2-of-3 coordination

The ops commands are the secret-free coordination layer for governed operations such as scheduling, cancelling, or executing a timelocked upgrade. They do not accept or store custodian secrets. Start from examples/mainnet-authority-manifest.template.json and replace every placeholder with the public account and signer addresses.

The coordinator creates a request from an already built and simulated unsigned transaction:

ackrate ops create \
  --xdr unsigned.xdr \
  --manifest mainnet-authority.json \
  --out request.json

Each custodian verifies request.json on an independent machine, then signs the unchanged XDR with a local secure identity or hardware wallet:

ackrate ops verify --request request.json
stellar tx sign unsigned.xdr \
  --network-passphrase 'Public Global Stellar Network ; September 2015' \
  --sign-with-key <local-custodian-identity> > signed-a.xdr

The coordinator combines two different valid signatures. A single, duplicate, unknown, wrong-network, changed-payload, or mixed-request signature is rejected:

ackrate ops combine \
  --request request.json \
  --signed signed-a.xdr signed-b.xdr \
  --out ready.xdr

Before submission, both custodians verify the ready envelope hash still equals the request hash. The operator then sends it through the reviewed mainnet RPC:

stellar tx hash ready.xdr \
  --network-passphrase 'Public Global Stellar Network ; September 2015'
stellar tx send ready.xdr \
  --rpc-url <reviewed-mainnet-rpc> \
  --network-passphrase 'Public Global Stellar Network ; September 2015'

The public authority manifest and request JSON contain no secrets and may be retained as evidence. Custodian identity stores and recovery material remain on their independent devices.

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 | |---|---:|---| | ackrate.config.json | Yes | Network, contract id, explorer, demo price, and default budget. | | ~/.ackrate/credentials.json | No | Testnet burner secrets for the user, agent, and merchant accounts. | | ~/.ackrate/mandate.json | No | The active mandate inputs and transaction hashes for local reuse. | | ~/.ackrate/pending-settlement/state.json | No | Crash-safe signed hash, sequence, and validity window retained until reconciliation. |

Set ACKRATE_HOME to relocate the private CLI state:

ACKRATE_HOME=/tmp/ackrate-demo ackrate setup

Network

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

ackrate init
cat ackrate.config.json

The current config points at the upgradeable simple MandateRegistry:

CCHQ5G4Y4YBMY6D3TYYJSVJVCKUM22Q6TMKCCHVAHY4X7K6QELQACZRM

Project commands remain testnet-only. Mainnet is available only through the explicit manifest-gated demo command above; an arbitrary edited contract ID is never treated as a production deployment.

Relationship to the SDK

@ackrate/cli ships as a self-contained command bundle built on @ackrate/core and @ackrate/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 ackrate.live/cli.

License

Apache-2.0.