Skip to content
VIGIL
Escrow flow
Start

Escrow flow

How a paid x402 call moves through VIGIL escrow: states, timeouts, refunds, failed checks, disputes and fees.

This page follows one paid call from the 402 quote to settlement. It covers each step, the escrow state machine and who triggers each transition, the timeouts, what happens when a provider never responds or a check fails, the dispute path, and the fee. Values marked as placeholders are specification targets, not live parameters.

Step by step

  1. Request. The agent calls the provider's endpoint with no payment attached.
  2. Quote. The provider answers HTTP 402 with the price in USDC, the expected response shape (a JSON Schema or a content type), minimum and maximum body size, and its maximum timeout.
  3. Route to VIGIL. The agent sends the quote, a signed USDC authorization for the quoted amount, and its own deadline to the Facilitator. The record is Quoted.
  4. Lock. The Facilitator locks the amount in the escrow contract on Base against the quote hash and deadline. The record is Locked.
  5. Forward. The Facilitator sends the request to the provider with a payment proof referencing the lock.
  6. Respond. The provider returns the response. The record is Responded; the response hash and arrival time are stored.
  7. Check. The Facilitator runs the four checks and signs a verdict. The record is Checked.
  8. Settle. Pass: USDC is released to the provider and the response delivered to the agent (Released). Fail: USDC returns to the agent with a reason code (Refunded).
  9. Attest. The verdict is recorded in the attestation registry and feeds the endpoint's score.
  10. Dispute window. For 24 h, any staked Watcher can contest the verdict. If one does, the record is Disputed until the vote ends.

State machine

StateMeaningTransitions toTriggered by
QuotedFacilitator holds a 402 quote and the agent's signed USDC authorization. No funds moved.Locked, or dropped if the quote expires unfundedAgent submits; Facilitator validates
LockedUSDC is held in the escrow contract against the quote hash and deadline.Responded, Refunded (deadline passed)Facilitator locks; provider response or clock
RespondedThe provider's response arrived. Hash and arrival time stored.CheckedFacilitator records receipt
CheckedThe four checks ran and a signed verdict exists.Released, RefundedFacilitator submits the verdict
ReleasedUSDC paid to the provider, less fee. Final unless disputed.DisputedEscrow contract on a pass verdict
RefundedUSDC returned to the agent. Final unless disputed.DisputedEscrow contract on a fail verdict, or anyone after the deadline
DisputedA staked Watcher contested the verdict. Vote in progress.Released or Refunded (record confirmed or overturned)Staked Watcher opens; vote closes after 48 h

Released and Refunded settle the USDC. A dispute after settlement changes the attestation record and stakes, not the transfer that already happened.

Sequence diagram

VIGIL escrow sequenceThe agent receives a 402 quote from the provider and pays through the VIGIL Facilitator. The Facilitator locks USDC in the escrow contract on Base, forwards the request, receives the response and runs the four checks. On pass the escrow releases USDC to the provider and the agent receives the response. On fail or timeout the escrow refunds the agent. The verdict is published as an attestation next to the Watchers probe attestations, and a staked Watcher may dispute it within 24 hours.Agentx402 clientFacilitatorVIGIL · offchainEscrowBase · USDCProviderx402 endpointProbesstaked Watchersprobe call every 60 s · 3+ regions1 request, no payment2 402 quote: price, schema, size, max timeout3 quote + signed USDC auth + deadlineQuoted4 lock USDCLocked5 request + payment proof6 response (before deadline, default 30 s)Responded7 schema · size · deadline · price (≤ 10 s)8 signed verdictCheckedalt · verdict[pass]9a release USDC, 0.5% fee10a response deliveredReleased[fail]or no responseby deadline9b refund USDC, no fee10b failure + reason codeRefunded11 verdict attestation, onchain next to probe attestationsDisputed: any staked Watcher can contest a verdict within 24 h. Stake-weighted vote over 48 h. False attestations are slashed.Contracts not deployed and not audited. Timeouts and fees are placeholder values.

Green messages are the pass branch, red messages the fail branch. The dashed message at the top is the Watchers' continuous probing, which runs whether or not any agent is paying. The dashed message at the bottom is the escrow verdict joining the probe attestations.

Timeouts

TimerValueWhat it bounds
Agent deadlineDefault 30 s, maximum 300 sTime from lock to a complete response from the provider
Check window10 s after responseTime for the Facilitator to run the four checks and submit a verdict
Dispute window24 h after settlementTime in which a staked Watcher can open a dispute
Dispute vote48 h after openingTime for active Watchers to vote

The agent sets its deadline in the request to the Facilitator; if the provider's 402 quote declares a shorter maximum timeout, the shorter value applies. The deadline is stored in the escrow contract at lock time, so the refund rule is enforced by the contract, not by the Facilitator.

When the provider never responds

If the deadline passes with no response, the escrow is refunded automatically. Anyone can call the refund once the stored deadline has passed; the Facilitator does this by default. The record moves from Locked to Refunded and the agent is notified with reason code TIMEOUT.

The missed deadline is recorded as an attestation with the deadline check failed. Repeated timeouts lower the endpoint's uptime component and its Endpoint Score. No fee is charged, because no volume was released.

When checks fail

If the response arrives but fails any check, the Facilitator submits a fail verdict with the first failing reason code, for example SCHEMA_MISMATCH or PRICE_ABOVE_QUOTE. The escrow contract refunds the agent in full. The agent still receives the response body with the failure and reason code, so it can log it or fall back to another endpoint.

The failed verdict is recorded as an attestation and lowers the matching component of the endpoint's score: schema or size failures hit the schema component, deadline failures hit uptime, price mismatches hit price. Because recent attestations weigh more (half-life 7 days), a run of failures moves a score within hours. See Checks and scoring.

Disputes

Any staked Watcher can open a dispute on a settled escrow within 24 h. A provider who believes a refund was wrong, or an agent who believes a release was wrong, surfaces the case through a Watcher, who puts stake behind the claim. A provider can also stake and open the dispute itself.

While the record is Disputed, active Watchers vote for 48 h, weighted by stake. If the original verdict is confirmed, the record returns to its settled state and the challenger's attestation is marked false. If it is overturned, the original attestation is marked false, excluded from the score, and the score is recomputed.

Whichever side published false attestations is slashed a fraction of its stake, defined by governance. A Watcher's claim is only as credible as what it stands to lose.

Fees

The protocol fee is 0.5% of volume routed through escrow, charged only on released volume. Refunds pay no fee: if the agent gets its USDC back, VIGIL takes nothing. Of every fee collected, 50% goes to active Watchers and 50% to buyback-and-burn of $VIGIL. Providers may add an optional subscription for the "VIGIL Verified" badge; it changes neither the fee, the checks nor the score.