The x402 model is simple: a client calls an API, gets 402 Payment Required, signs payment, retries, and receives the result.
This flow works well over HTTP, but modern use cases exposed real limitations.
That is why we introduced WebSocket transport to Relay.
1) What problems we had before WebSocket - Too much overhead for many short requests
In agent loops, chat sessions, iterative workflows, or fast polling, clients often send many short requests in sequence. With HTTP-only transport, each call has its own request cycle, adding latency and transport overhead. WebSocket lets us keep one active connection and send multiple requests over it.2) Weak ergonomics for parallel requests
When many calls are in flight at once, clients must reliably match each response to its request. In the WS model, this is explicit through envelopeid, so clients can safely multiplex traffic.
3) Pressure on API providers to run their own WS backend
This was a key product problem. We did not want every seller to build and maintain a separate WebSocket server, queueing layer, and payment logic. In our architecture, providers keep their existing HTTP relay integration. WebSocket is a shared gateway on the RelAI side that forwards to the same relay and payment middleware stack.4) Risk of payment regressions with a new transport
A new transport could not change x402 semantics. We preserved the same handshake:- Request without
payment - Receive
402withpaymentRequired - Sign and attach
payment - Retry the same call
- Get result plus optional
paymentResponse
5) Production resilience
In real environments, WebSocket can be blocked or unstable. So WS could not be an all-or-nothing path. If WS fails, the client falls back to HTTP automatically and payment flow still completes.What WebSocket changes in Relay
- One shared WS endpoint for relay calls
relay.callenvelope withapiId,path,requestMethod,requestHeaders, optional body- Response correlation by
id - Same x402 payment semantics as HTTP
- No custom WS server required for API providers
- Built-in HTTP fallback when WS is unavailable
Why this matters for the business
In practice, this gives us:- Faster user experience for apps that make many paid calls in one session
- Lower integration complexity for API providers
- Safer rollout without breaking existing x402 behavior
When to use WS vs HTTP
Use WebSocket when:- You make many requests in a single session
- You build agentic or chat-heavy workflows
- You need lower latency and less transport overhead
- A reliable fallback
- A simple path for infrequent one-off requests
- A resilience option in environments with WS constraints
