WebSockets & pubsub

Live RFQ traffic uses Phoenix Channels on /socket.

Register

Maker (recommended)

POST /api/pubsub/premium — requires auth and maker rights.

{ "chain_id": 31337 }

Example response:

{
  "status": "registered",
  "tier": "premium",
  "chain_id": 31337,
  "socket_path": "/socket",
  "quotes_requests_topic": "quotes:31337:requests",
  "rfq_maker_stream_topic": "rfq_maker:0x..."
}

When Borrow is live, the same registration is expected to also return margin_requests_topic and margin_lender_stream_topic. Those feeds are coming soon — do not depend on them in production.

Freemium

POST /api/pubsub/freemium — authenticated, no maker requirement. Same topic shape; private maker streams are only useful if you have maker rights / keys.

Connect

1. Open a Phoenix Socket to {api_origin}/socket (this docs build: DOCS_API_URL, then /socket/websocket).
2. Join the topics returned by registration (or the stream topic returned when creating a quote).

In browser clients, the trading app proxies /socket to the API in Vite. Bot integrations usually connect to the API host directly.

Topic cheat sheet

Topic	Who	Events
quotes:<chain_id>:requests	Makers (filler feed)	rfq_request — new options RFQ (no raw taker address)
rfq_maker:<address>	That maker	Requests you care about, your offers, results (api_key for bots)
rfq_stream:<stream_token>	Taker	rfq_request, rfq_offer, rfq_result

Coming soon (Borrow)

Topic	Who	Events
margin:<chain_id>:requests	Lenders (filler feed)	margin_rfq_request
margin_lender:<address>	That lender	Borrow request / offer / result
margin_rfq_stream:<stream_token>	Borrower	margin_rfq_request, margin_rfq_offer, margin_rfq_result

Typical maker loop

SIWE or API key
  → POST /api/pubsub/premium
  → join quotes:<chain_id>:requests
  → on rfq_request: build + EIP-712-sign offer
  → POST /api/quote/:id
  → optionally join rfq_maker:<your_address> for outcomes

Notes

• Quote processes are short-lived (expires_in, typically ≤ 300s). Join the stream before or immediately after creating a quote so you do not miss early offers.
• Filler feeds intentionally omit taker identity; the signed offer binds via taker_address_hash.
• Private maker channels expect your maker api_key when joining as a bot.