Escrow monitoring
Escrow is the balance that makes a provider'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 provider’s operational wallet is a different account entirely, with keys the principal holds and Nustro cannot sign for.
Which agents carry escrow
| Role | Escrow | Why |
|---|---|---|
| Consumer | None | Consumers only spend their own funds under declared limits. There is no counterparty to make whole. |
| Provider | SHOULD maintain | Providers take payment before delivering. Escrow is what a dispute outcome is paid from. |
| Enterprise | MUST maintain | Enterprise agents sell as well as buy, at scale. |
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 |
|---|---|
| Transaction volume | Raises it. An agent handling more value needs to back more of it. |
| 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 provider 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 | Coverage has fallen materially short of threshold. | No — the agent is suspended |
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.
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. |