Escrow monitoring
Escrow is the balance that makes a seller's promises enforceable. It builds from settlements, holds against open disputes, and constrains the agent when coverage runs short. Your platform does not manage it — but it is the only party positioned to warn a principal before it bites.
Escrow wallets are Operator-custodied, segregated per agent, and movable only on protocol events — contributions in, dispute outcomes and releases out. The balance belongs to the principal throughout. The seller’s operational wallet is a different account entirely, with keys the principal holds and Nustro cannot sign for.
Which agents carry escrow
| Agent | Escrow | Why |
|---|---|---|
| Personal | None | It only spends its principal’s own funds under declared limits. There is no counterparty to make whole. |
| Business that only buys | None | The same — a fault it commits as a buyer runs to its principal through the delegation chain, not to escrow. |
| Business that sells | MUST maintain | It takes payment before delivering, and escrow is what a dispute outcome is paid from. If it also buys, its escrow still covers only its sales. |
The threshold is dynamic
An agent’s required coverage is not a fixed number. It is derived from what the agent actually transacts and adjusted by how well it performs.
| Input | Effect on the threshold |
|---|---|
| Sell volume, net of refunds | Raises it. An agent selling more value needs to back more of it. What it buys does not count, and a refund lowers the basis. |
| Agent rating | Lowers it. A strongly rated agent carries materially less required coverage — good performance costs less to underwrite. |
| Dispute outcomes | Losses draw the balance down, which can put a previously covered agent back below threshold. |
The funding rate and threshold formula are Operator-held configuration. Neither your platform nor the principal can set them — a seller that chose its own rate could carry no coverage at all, which would make the whole guarantee decorative.
Two ways to fund
| Route | How it works | When it suits |
|---|---|---|
| From settlements | A configured share of each settlement is routed to escrow until the balance reaches threshold, then contributions stop. | The default. The agent earns its coverage as it works. |
| Pre-funding | The principal funds the escrow wallet directly, before or alongside trading. | An agent that needs full coverage on day one, or one whose volume grew faster than its contributions. |
The two combine: a partially pre-funded agent still contributes from settlements until it reaches threshold. Above threshold, settlements credit in full to the operational wallet.
Principals often want coverage before revenue exists. Financing that pre-funding, or advancing it against expected settlement flow, is a legitimate revenue line for your platform — and escrow state plus settlement history give you the underwriting data.
Escrow states
| State | Meaning | Agent can transact? |
|---|---|---|
FUNDING | Below threshold and building. Contributions are being taken from settlements. | Yes — subject to coverage |
ACTIVE | At or above threshold. Settlements credit in full. | Yes |
DISPUTE_HOLD | A contested amount is reserved against an open case. Available balance is reduced. | Yes, unless the remainder falls short |
CONSTRAINED | Open dispute exposure — disputed amounts plus bounties — exceeds the balance. The whole balance is held. | No — the whole agent is suspended, buying included |
RELEASED | Escrow returned to the principal after the agent was revoked and obligations closed. | No — terminal |
CONSTRAINED suspends the agent automatically. It is not a warning state — by
the time an agent reaches it, it has already stopped being able to transact, and
its counterparties see a suspended agent rather than a struggling one. A business
agent that also buys cannot open payment intents either until its escrow recovers;
its dispute obligations and refunds of its own sales stay available.
What to monitor, and when to speak up
Suspension is abrupt. Everything useful your platform does here happens before it.
agent.status_changed. If an agent is suspended for coverage, stop routing work to it immediately — every match after that point is a wasted round trip and a bad experience for the buyer.Reading escrow state
| Source | Gives you |
|---|---|
GET /v1/agents/{did}/status | Live escrow_state — what counterparties see when they verify |
GET /v1/agents/{did}/overview | Balance, threshold, and recent movement in one call |
agent.status_changed webhook | Suspension and reinstatement as they happen |
| The chain | Every contribution, hold, and payout as public transactions |
Release and closure
Escrow is returned to the principal when the agent stops trading and its obligations are closed.
| Condition | Effect |
|---|---|
| Agent revoked, no open disputes | Balance is released to the principal; state becomes RELEASED. |
| Agent revoked, disputes open | Cases continue to resolution. Release follows once they close. |
| Agent transferred | Escrow follows the agent to the new principal, along with its rating and history. |
| Platform account closed | Escrow balances are released to their principals before closure completes — closure is blocked until they are. |