Guides · Trust thresholds
Every receiver sets one number: how much unpaid balance to carry before forcing an on-chain settlement. Set it high and gas costs vanish into the volume. Set it low and no counterparty can ever owe you much. This guide is about picking that number deliberately instead of copying it from a quickstart.
Receipts are signed IOUs. Until you redeem a RAV, the tally on your receiver is money the payer owes you and hasn't yet been forced to pay. The threshold is therefore the maximum credit you extend to a counterparty — not a tuning parameter, a credit line. Every argument in this guide follows from that framing.
import { Receiver } from "@velapay/sdk" const receiver = new Receiver({ threshold: "$500" // max unpaid balance you'll carry })
Each RAV redemption is one on-chain transaction, and its gas cost is flat no matter how many receipts it collapses. Settle too often and fees eat your margin on exactly the small, frequent work velapay exists to make viable. Run the arithmetic for your own volume before touching the default.
// volume: $2,000/day of receipts · gas: ~$1.40 per RAV // // threshold settlements/day gas/day gas as % of flow // $50 40 $56.00 2.80% // $500 4 $5.60 0.28% // $2,000 1 $1.40 0.07% // // higher thresholds amortize gas — and raise your exposure
The risk model is mercifully simple. If the counterparty vanishes — key rotated, service killed, company gone — your loss is the unpaid balance at that moment, and its worst case is the threshold itself. Nothing subtler than that: no clawbacks on a plain channel, no collections department for an agent that no longer exists. A $2,000 threshold means you are comfortable writing off $2,000 the day a payer stops answering. If reading that sentence made you flinch, your threshold is too high.
Start from the loss you could absorb without caring — not without dying, without caring — and scale it by how much history you have with the counterparty. New counterparties start low even when the gas math argues otherwise; thresholds are grown with clean settlement history, never granted up front.
// threshold ≈ affordable loss × trust factor // // affordable loss: $1,000 (a shrug, not a scramble) // // brand-new counterparty: $1,000 × 0.05 → $50 // 30 days clean history: $1,000 × 0.25 → $250 // long-standing partner: $1,000 × 1.00 → $1,000
One number for every payer wastes the heuristic. Set a conservative default for strangers, then override per counterparty as history accumulates. The receiver keys overrides by the payer identity on each verified receipt, so the right credit line applies automatically.
const receiver = new Receiver({ threshold: "$50", // default for unknown payers thresholds: { "agent:orchestrator.prod": "$2,000", // long history "agent:research-swarm.v1": "$500", "agent:new-buyer.trial": "$25" // earn it first } })
A threshold you set once and never watch is just a number in a config file. Alert when a balance approaches its threshold — a payer camping at 95% without crossing is either perfectly tuned or probing you — and review the overrides monthly: promote counterparties that settle cleanly, cut the ones that make you nervous. Raising a threshold should feel like raising a credit limit, because it is one.
receiver.on("threshold:near", ({ payer, balance, threshold }) => { // fires at 80% by default pager.warn(`${payer} at ${balance} of ${threshold}`) }) receiver.on("settled", ({ payer, tx }) => { metrics.count("rav.redeemed", { payer }) // clean history })
Thresholds matter most the day you leave testnet — the going to mainnet guide starts every production rollout at $25 for a reason. The quickstart shows the tally-and-redeem loop these numbers govern, and the API reference documents every threshold and event option.