Escrow — Reserve-Before-Execute

Escrow reserves the worst-case cost before forwarding a request, preventing overspend from concurrent requests.

The Problem

Without escrow, concurrent requests can overspend the wallet:

1. Request A checks balance: $10.00 available
2. Request B checks balance: $10.00 available (same cached balance)
3. Request A costs $6.00 → balance $4.00
4. Request B costs $6.00 → balance -$2.00 (overspend!)

The Solution

With escrow enabled, the gateway reserves the worst-case cost before forwarding:

1. Request A reserves $6.00 → balance $4.00, escrow $6.00
2. Request B tries to reserve $6.00 → only $4.00 available → blocked with 402
3. Request A completes, actual cost $5.00 → escrow released, $1.00 returned → balance $5.00

When It Matters

Escrow is critical when:

• You have concurrent requests (any production app)
• You use PTB billing (pay-the-blanket)
• You have tight budget constraints

What Changes When Enabled

• Cache is honored, escrow is released on hit: The request cache is still consulted after the escrow reservation. On a cache hit, the escrow hold is cancelled (a cached response incurs no PTB cost), so the user isn't charged for a cached answer.
• 402 on insufficient funds: When the wallet can't cover the estimate, the gateway returns 402 instead of forwarding
• Atomic finalization: After the request completes, the actual cost is deducted and the difference is returned to the wallet

Enabling Escrow

1. Set ESCROW_ENABLED=true in your gateway environment
2. Monitor 402 responses (indicates concurrent overspend attempts)
3. Verify Cova-Credits-Remaining reflects post-settlement balance