Escrow System

The escrow system provides trustless payment guarantees via a deployed Anchor program on Solana mainnet. Instead of paying the gateway directly, the agent deposits USDC into a PDA vault. The gateway claims only the actual cost after the request succeeds. If the gateway fails, the agent reclaims their deposit.

Deployed program: 9neDHouXgEgHZDde5SpmqqEZ9Uv35hFcjtFEPxomtHLU

Escrow vs direct payment

How it works

PDA account structure

The escrow vault PDA is derived using:

seeds = [b"escrow", agent_pubkey_bytes, service_id_bytes]
program_id = 9neDHouXgEgHZDde5SpmqqEZ9Uv35hFcjtFEPxomtHLU

The service_id is a 32-byte request correlation ID (base64-encoded) that the agent generates per request. It is used both as a PDA seed and to correlate the deposit with the gateway request.

The PDA holds a USDC-SPL token account (Associated Token Account). The vault is owned by the program — neither the agent nor the gateway can withdraw unilaterally.

Escrow payment payload

When choosing the escrow scheme, the payment-signature header contains a PaymentPayload with an EscrowPayload:

{
  "x402_version": 2,
  "resource": { "url": "/v1/chat/completions", "method": "POST" },
  "accepted": {
    "scheme": "escrow",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "2625",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "pay_to": "<gateway-wallet>",
    "max_timeout_seconds": 300,
    "escrow_program_id": "9neDHouXgEgHZDde5SpmqqEZ9Uv35hFcjtFEPxomtHLU"
  },
  "payload": {
    "deposit_tx": "<base64-encoded-signed-deposit-tx>",
    "service_id": "<base64-encoded-32-byte-service-id>",
    "agent_pubkey": "<base58-agent-wallet-pubkey>"
  }
}

Client-initiated settle (F4)

By default the gateway claims escrow at request end. For streaming responses, clients can drop reconciliation latency from minutes (auto-timeout) to milliseconds by calling POST /v1/escrow/settle once the stream completes — the gateway computes the actual cost from the reported token counts and fires the claim immediately.

This endpoint is what @solvela/openclaw-provider's wrapStreamForF4 wrapper calls after each wrapStreamFn invocation finishes.

{
  "service_id":           "<base64 32-byte service id, same value used in the deposit>",
  "agent_pubkey":         "<base58 Solana pubkey of the depositor>",
  "model":                "openai/gpt-4o",
  "status":               "completed",
  "actual_prompt_tokens":     128,
  "actual_completion_tokens": 256
}

Behavior:

• status: "completed" with both actual_*_tokens fields → gateway looks up the model in the registry, computes the actual atomic-USDC cost, and enqueues a claim. The escrow program rejects over-claims on-chain, so the cost is bounded by the deposit regardless of what the client reports.
• status: "error" → gateway logs the error and fires no claim. The deposit is reconciled by the escrow program's on-chain auto-timeout refund path (same as the pre-F4 flow). No actual_*_tokens fields are needed.
• Missing tokens with status: "completed", unknown model, or non-finite pricing → 400.

Idempotency: when PostgreSQL is configured, the durable claim queue dedupes by (service_id, agent). Without a database, a duplicate settle call can produce a second on-chain claim attempt; the escrow program rejects the second because the deposit account is already drained.

Auth (v1): the endpoint is fire-and-forget. The on-chain escrow program is the source of truth — a misrouted settle (wrong agent_pubkey or service_id) fails at the chain layer, logged but not surfaced to the client. Future hardening (HMAC over the body, or an agent signature over (service_id, model, status, tokens)) is tracked but not yet shipped.

Refund behavior

If the gateway fails to claim within max_timeout_seconds, the agent can invoke the refund instruction on the escrow program to reclaim their deposit. The refund path is enforced on-chain by the Anchor program — no trust in the gateway is required.

When to use escrow

Use escrow when:

• You are building autonomous agents that require trustless guarantees
• You want protection against gateway downtime after payment
• You are handling large request batches and want per-request accountability

Use exact (direct) payment when:

• You want the simplest possible integration
• You are running in a trusted environment
• Your SDK handles payment automatically and you don't need custom logic

See x402 Protocol for the full payment flow.