Skip to main content
Convallax has two very different kinds of participants, and they authenticate in two very different ways:

Market makers

Authenticate every maker channel with an API key you generate yourself in the dashboard. The key maps to a stable makerId and all of your quotes are attributed to it.

Takers (traders)

Need no API key. REST trading endpoints are open, and your authorization is the on-chain fill() call signed by your own wallet.
There is also a small set of account endpoints (profile, username, API-key management) authenticated with a Privy access token rather than an API key — see Account endpoints below.
The discovery / read endpoints — GET /v1/markets, GET /v1/series, and GET /v1/series/{seriesId} — are fully public. They require no API key and no Privy token, even if you are a market maker. Sending an X-API-Key header to them has no effect (it is not checked). Only the /v1/mm/* maker channels require your API key.

​
Market Maker API Keys

Each market maker is an independent entity with its own wallet and USDC. To quote on the relay, you authenticate with an API key. The key identifies your makerId — a stable identifier that every quote you submit is attributed to. There is no separate market-maker role: any signed-in user can generate a key and begin quoting. Makers integrate over a three-channel transport, and the same API key authenticates all three. How you present the key depends on the channel:
ChannelTransportHow to authenticate
Quote-request streamSSEX-API-Key header (or ?apiKey=)
Quote submission + confirmRESTX-API-Key header (or ?apiKey=)
Post-trade eventsWebSocket?apiKey= on the URL, or an auth message

​
Generating a key

API keys are self-serve from the Convallax dashboard:
1

Sign in

Open the dashboard and connect your wallet (this signs you in via Privy).
2

Open Settings → API Keys

Go to Settings in the top nav, then the API Keys tab.
3

Generate and store the key

Click Generate key. The full key is shown once — copy it immediately and store it securely. You can revoke a key at any time from the same screen.
The same actions are available programmatically via the account endpoints (POST /v1/user/api-keys).

​
Key format

Keys look like mk_live_<random> and are mapped server-side to your account’s makerId (for example mm_9f8e7d6c5b). Treat your key as a secret — anyone holding it can submit quotes attributed to your makerId. The relay stores only a hash of your key; if you lose it, revoke it and generate a new one.
Your API key only authorizes quoting. It can never move funds. On-chain settlement always requires a signature from your own wallet key (see Trade Lifecycle). Keep your API key and your wallet key in separate, secure storage.

​
Authenticating the SSE Stream & REST Endpoints

The quote-request SSE stream and the REST quote endpoints (submit and confirm) authenticate with the X-API-Key header: 
X-API-Key: mk_live_alpha_xxx
If your client cannot set custom headers (for example, a browser EventSource), pass the key as a query parameter instead: 
GET https://api.convallax.com/v1/mm/quote-requests/stream?apiKey=mk_live_alpha_xxx

curl -X POST https://api.convallax.com/v1/mm/quotes \
  -H "X-API-Key: mk_live_alpha_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "req-789", "quote": { ... } }'

​
Authenticating on the WebSocket

The post-trade WebSocket uses a different mechanism. There are two equivalent ways to present your API key when connecting to wss://api.convallax.com/maker/v1/ws.
1

Option A — query parameter

Append your key to the connection URL:
wss://api.convallax.com/maker/v1/ws?apiKey=mk_live_alpha_xxx
This is the simplest approach and authenticates you the moment the socket opens.
2

Option B — auth message

Connect without a key, then send an auth message immediately after the connection opens:
{
  "type": "auth",
  "apiKey": "mk_live_alpha_xxx"
}
Use this when you prefer to keep the key out of the connection URL (for example, to avoid it appearing in proxy or access logs).

​
Successful authentication

On a valid key, the server replies with a connected message that echoes your resolved makerId: 
{
  "type": "connected",
  "protocolVersion": 3,
  "makerId": "mm-alpha",
  "authenticated": true,
  "serverTime": "2026-06-15T12:00:00.000Z"
}
From this point on, every quote you submit (over REST) is attributed to mm-alpha. You do not need to include your makerId — the relay derives it from your authenticated API key.

​
Invalid authentication

If the API key is missing or invalid (when the relay is configured with keys), the server closes the socket with code 4001. Reconnect with a valid key.
Re-POSTing to /v1/mm/quotes for the same requestId updates (replaces) your previous quote. Because quotes are attributed to your authenticated makerId, you cannot impersonate or overwrite another maker’s quotes.

​
Open Dev Mode

If the relay is started without any maker keys configured and without a database, it runs in OPEN dev mode: it accepts anyone, assigns an anonymous makerId, and does not require an apiKey. This is intended for local development and testing against your own relay instance. In production (wss://api.convallax.com), keys are always required.

​
Account Endpoints (Privy JWT)

Managing your profile and API keys uses a different credential: a Privy access token, not an API key. The dashboard obtains this token when you sign in and sends it as a bearer token: 
Authorization: Bearer <privy-access-token>
These endpoints are authenticated this way:
EndpointPurpose
GET /v1/user/profileYour account + makerId
PUT /v1/user/usernameSet your username
GET /v1/user/api-keysList active keys
POST /v1/user/api-keysCreate a key (returned once)
DELETE /v1/user/api-keys/{id}Revoke a key
The two credentials are distinct: a Privy token proves who you are (to manage your account), while an API key authorizes maker traffic. Creating an API key requires a Privy token; using it to quote does not.

​
Server Configuration

The self-serve key store requires a Postgres database (DATABASE_URL) and Privy server credentials (PRIVY_APP_ID, PRIVY_APP_SECRET). In addition, first-party / ops makers can be configured with static environment keys that work alongside self-serve keys:
​
MAKER_API_KEYS
JSON array
The recommended way to configure multiple makers. Each entry maps an API key to a stable makerId:
[
  { "apiKey": "mk_live_alpha_xxx", "makerId": "mm-alpha" },
  { "apiKey": "mk_live_beta_yyy",  "makerId": "mm-beta" }
]
​
MAKER_API_KEY
string
Legacy single-key mode. Still supported for backwards compatibility — the key maps to the makerId "default".
If neither variable is set and no database is configured, the relay runs in OPEN dev mode. Once a database is attached, anonymous access is disabled and a valid key is always required.

​
Takers Need No API Key

Traders (takers) never authenticate with an API key. The REST trading endpoints are open:
  • POST /quote-requests — open a live quote request
  • GET /quote-requests/:id/stream — stream the live best quote (SSE; preferred)
  • GET /quote-requests/:id/quotes — poll for the best quote (fallback)
  • POST /quote-requests/:id/commit — commit to the best quote
Your authorization as a taker is enforced on-chain: the signed Order you receive at commit restricts settlement to your wallet, and only that wallet can call fill() on ConvallaxRFQSettlement. No funds move until you sign and broadcast that transaction yourself.
See the Quote Request Stream guide and Post-Trade WebSocket guide for the channel references, and the Market Maker guide for the complete integration flow including order signing.