Docs

Buying with escrow

When a plan includes paid items, they go into one escrow order. Your money is held by an escrow agent, not paid to sellers, until you accept the delivery or the acceptance window ends. If a seller does not deliver by the deadline, you are refunded in full. Everything on this page runs in test mode: no real money is held, paid or refunded.

How an order works

1. Quote. You create an order from the plan's paid items. The signed order records the items and prices, the rail, the fee rate, the arbiter and both deadlines. They cannot change afterwards.
2. Deposit. You pay the total to the escrow address for your rail. The escrow agent checks the deposit matches the order total and marks the order funded.
3. Delivery. Each seller marks their own item delivered, with an access link and the content hash of what they delivered. When every item is delivered, the acceptance window starts.
4. Decision. You accept, or you do nothing until the window ends, or you dispute.
5. Settlement. On release, each seller receives the price minus the network fee. On refund, you receive the whole total back.

Free items and build steps never enter an order. If a plan has nothing to buy, there is no escrow.

Order states

Who can do what

These limits are enforced when the log is read, so every node applies them the same way. A step signed by the wrong party is ignored.

Acceptance window and deadlines

• Acceptance window. Starts when the last item is delivered. Default 7 days. The buyer can choose another length when creating the order (accept_window_days), from 1 hour to 90 days. If the window ends in silence, the order is released. This protects sellers from a buyer who simply never answers.
• Delivery deadline. Starts when the order is funded. Default 7 days. If any item is still undelivered when it ends, the order is refunded.

Disputes and refunds

The arbiter's decision is all or nothing. There is no partial refund and no per-item split. Say exactly what you ran, what you expected and what failed. There is no fixed rubric yet.

Fees

A released order pays a network fee. The default on a self-hosted node is 1% of each item's price, set by the operator with REPOBLOCK_FEE_BPS. The rate is written into the order when you create it. The fee is deducted from the seller's side: the buyer deposits exactly the sum of the listed prices. Each seller's net is rounded down to the cent, and the fee is the rest. Refunds carry no fee. Free items have no order and so no fee. The amounts in this section are test-mode examples.

How far the fee can go depends on where the order runs. A self-hosted node starts only with a rate from 0 to 1000 basis points (10%) and rejects any order that carries a higher one. Within that bound, whoever runs the node sets REPOBLOCK_FEE_BPS, and the order shows the rate before you deposit. The escrow contract specified in docs/PAYMENTS.md caps the fee at 500 basis points (5%), records the rate when an order is funded, and applies a later change to new orders only. That contract is not deployed, and only its interface (contracts/src/interfaces/IRepoEscrow.sol) is in the repository. For fees on the hosted app, see Pricing.

Payment rails and test mode

The escrow rules do not depend on the rail. A rail only decides how a deposit is described, checked and paid out. Choose one with --rail when you start the node.

On the non-mock rails, creating an order fails unless every seller has a payout address for that rail. Payouts are meant to be made by an escrow contract for USDC and USDT, specified in docs/PAYMENTS.md. It settles each item on its own and pays out by credit that sellers claim, so one blocked payee cannot hold up the others. Its source is not in the repository yet, it is unaudited and nothing is deployed. Until it is, a stablecoin deposit would sit with whoever runs the escrow agent, and you would be trusting them with it.

Run an order from the command line

Against a local node (setup) on the default simulated rail, so no real money moves, with jq installed:

NODE=http://127.0.0.1:8420
curl -s -X POST $NODE/api/plan -d '{"goal":"RAG chatbot over my PDF invoices with a dashboard and crypto checkout","budget_usd":50}' > plan.json

# 1. quote: send the plan's paid items, with a 3 day acceptance window
OID=$(jq '{paid_items: .recommended.paid_items, accept_window_days: 3}' plan.json \
  | curl -s -X POST $NODE/api/orders -d @- | jq -r .order.order_id)

curl -s -X POST $NODE/api/orders/$OID/pay     -d '{}' | jq .order.state   # "FUNDED" (simulated deposit)
curl -s -X POST $NODE/api/orders/$OID/deliver -d '{}' | jq .order.state   # "DELIVERED" (as the demo seller)
curl -s -X POST $NODE/api/orders/$OID/accept  -d '{}' | jq .order.payouts # sellers paid, plus the fee line

To dispute instead of accepting, post {"reason": "..."} to /api/orders/$OID/dispute. The node operator resolves it with {"outcome": "release"} or {"outcome": "refund"} posted to /api/orders/$OID/resolve. These are the endpoints of a self-hosted node. The hosted API is described in the API reference.

What escrow does not do

• It does not look inside the delivery. It records the access link and the hash the seller states. Checking the content against the hash is your job.
• It cannot stop a buyer copying code that was delivered. Escrow protects payment, not secrecy.
• It does not guarantee the code works. It gives you a window to find out, and a way to object.
• It does not make an unaudited contract safe. See what is not guaranteed.

Last updated: 2026-11-03