Skip to main content
The Convallax API provides programmatic access to the options trading system. Use it to request indicative quotes, submit RFQs, execute trades, and prepare settlement attestations.

​
Base URL

The API is served by the Convallax relay (Node.js backend). The base URL depends on your deployment: 
# Local development
http://localhost:3001

# Production (configure via environment)
https://your-relay.example.com

​
Authentication

Most endpoints are currently open. The WebSocket maker endpoint optionally requires an API key: 
WS /maker/v1/ws?apiKey=<your-key>
API key authentication is enabled when the relay’s MAKER_API_KEY environment variable is set.

​
REST Endpoints

​
Health & Status

GET /

Health check. Returns "Server is running".

GET /maker/v1/status

Relay status: protocol version, connected maker count, and WebSocket path.

​
Trading

​
POST /quote/indicative

Get a model-based indicative bid/ask quote. No wallet signature required.
​
conditionId
string
required
Polymarket market condition ID.
​
yesClobTokenId
string
required
Polymarket YES CLOB token ID.
​
strikeBps
number
required
Strike price in basis points (5–95).
​
optionType
number
required
0 = Call, 1 = Put.
​
expiryUnix
number
required
Option expiry as Unix timestamp.
​
side
string
required
"buy" or "sell".
​
size
number
required
Number of whole options.
Response: 
{
  "success": true,
  "quote": {
    "bid": 0.10,
    "ask": 0.14,
    "fairValue": 0.12,
    "spread_bps": 200
  }
}

​
POST /rfq

Submit a signed request for quote. The relay verifies the EIP-712 signature, broadcasts to market makers, collects quotes, and returns the best one.
​
payload
object
required
The EIP-712 typed data payload (ConvallaxRFQV1 message fields).
​
signature
string
required
EIP-712 signature from the taker wallet.
​
signatureEncoding
string
required
Must be "eip712".
Response: 
{
  "success": true,
  "quote": {
    "rfq_id": "abc-123",
    "side": "sell",
    "price": 0.12,
    "size": 10,
    "makerId": "mm-1"
  },
  "meta": {
    "quotesReceived": 3,
    "timeMs": 802
  }
}

​
POST /execute

Accept the winning quote and receive a signed on-chain order. The relay resolves the series, ensures market maker inventory, and signs the EIP-712 Order struct.
​
rfq
object
required
The original RFQ payload.
​
quote
object
required
The winning quote to execute.
Response: 
{
  "success": true,
  "onchain": {
    "order": {
      "maker": "0xMM...",
      "seriesId": "123...",
      "optionAmount": "10000000",
      "premiumAmount": "1200000",
      "makerSelling": true,
      "taker": "0x0000000000000000000000000000000000000000",
      "validUntil": 1717189320,
      "nonce": 42
    },
    "makerSignature": "0x...",
    "settlementAddress": "0xC6Eb814Cc01189e20B2DB2D2a22Ed2DcAC404992",
    "domain": {
      "name": "ConvallaxRFQSettlement",
      "version": "1",
      "chainId": 80002,
      "verifyingContract": "0xC6Eb814Cc01189e20B2DB2D2a22Ed2DcAC404992"
    }
  }
}
The taker uses the order and makerSignature to call ConvallaxRFQSettlement.fill() on-chain.

​
Settlement

​
POST /settlement/prepare

Compute the VWAP resolution price and return a signed settlement attestation.
This endpoint should be restricted in production — it is intended for cron jobs and internal automation, not public access.
​
seriesId
string
required
The series ID to settle (hex or decimal).
Response: 
{
  "success": true,
  "seriesId": "123...",
  "resolutionBps": 59,
  "validUntil": 1717189200,
  "signature": "0x...",
  "meta": {
    "vwap": 0.592341,
    "tradeCount": 142,
    "windowStart": 1717187400,
    "windowEnd": 1717189200
  }
}
Use the returned seriesId, resolutionBps, validUntil, and signature to call ConvallaxCore.settleWithAttestation() on-chain.

​
Faucet

​
POST /faucet

Request testnet USDC (Amoy only). Rate-limited per wallet.
​
wallet
string
required
Wallet address to receive testnet USDC.
Response: 
{
  "success": true,
  "amount": "1000",
  "txHash": "0x..."
}

​
GET /faucet/status

Returns faucet configuration and remaining pool balance.

​
WebSocket

​
WS /maker/v1/ws

Real-time RFQ distribution for market makers. See the full WebSocket reference for message schemas, validation rules, and connection lifecycle.
DirectionMessage typeDescription
Server → MakerconnectedConnection confirmation with protocol version
Server → MakerrfqNew RFQ broadcast with trade envelope
Maker → ServerquoteQuote submission for an active RFQ

​
On-Chain Contracts

After receiving a signed order from /execute, the taker interacts directly with the smart contracts:
ContractMethodPurpose
ConvallaxRFQSettlementfill(order, signature)Execute atomic option ↔ USDC swap
ConvallaxCoresettleWithAttestation(...)Submit resolution attestation
ConvallaxCoreclaimHolderPayout(seriesId, amount)Claim holder payout after settlement
ConvallaxCoreclaimWriterCollateral(seriesId)Claim writer’s remaining collateral
ConvallaxRFQSettlementcancelNonce(nonce)Pre-burn an unused nonce
See Settlement & Resolution for the full claim flow.