Skip to main content

​
Base URL

​
Authentication

Convallax uses two credentials depending on what you are doing:
  • Maker API key (X-API-Key) — authorizes market-maker traffic across the three-channel transport. The SSE quote-request stream and the REST quote endpoints use the X-API-Key header (or ?apiKey=); the post-trade WebSocket uses ?apiKey= on the URL or an auth message. Keys are self-serve: any signed-in user generates one from the dashboard (Settings → API Keys), and it maps to a stable makerId.
  • Privy access token (Authorization: Bearer <jwt>) — authorizes the account endpoints under /v1/user/* (profile and API-key management).
  • Takers need neither. The REST trading endpoints (/quote-requests, /quote-requests/:id/quotes, /quote-requests/:id/stream, /quote-requests/:id/commit) are open. A taker’s authorization is the on-chain fill() call signed by their own wallet — only the wallet named as taker in the signed order can settle.
See the Authentication guide for full details. The three maker channels are:

​
Response Envelope

Successful responses are wrapped:
Failed responses return:

​
Endpoint Groups

Authentication

How market makers obtain and use per-MM API keys — and why takers need none.

Trading

Open live quote requests, poll for market maker quotes, and commit to the best price.

Market Maker

Subscribe to the SSE quote-request stream, submit quotes over REST, and receive post-trade events over the WebSocket.

User

Manage your account profile and generate or revoke self-serve API keys.

Settlement

Compute VWAP resolution prices and generate signed settlement attestations.

On-Chain Contracts

Call smart contract functions directly: fill orders, claim payouts, and settle options.

​
On-Chain Settlement

After committing to a quote via POST /quote-requests/:id/commit, the taker receives a signed Order struct and interacts directly with the Polygon smart contracts. The taker makes the single USDC approval indicated by takerApproval, then calls fill() on ConvallaxRFQSettlement to atomically lock collateral, pay premium, and mint the option. No further API calls are needed for settlement.

​
Rate Limits

API endpoints are not rate-limited. The only exception is the testnet faucet, which is capped per wallet (default once per 24h) and returns 429 within the cooldown. Be a good citizen: hold a single quote-request SSE stream and update your quotes only when your price meaningfully changes.