Acta Maker API Reference
Endpoint
Quote plane:
wss://devnet-api.acta.markets/maker
wss://beta-api.acta.markets/maker
Data plane:
wss://devnet-api.acta.markets/maker/data
wss://beta-api.acta.markets/maker/data
Use /maker for RFQ subscriptions, quote submission, quote replacement, and
quote cancellation. Use /maker/data for private maker reads and recovery
queries such as GetMyQuotes, GetMakerPositions, GetMyTrades, and
GetMmSummary. These reads are also accepted on /maker. Use a separate data
connection to keep read requests off the quote connection.
GetMmSummary is for dashboard bootstrap and recovery on /maker/data. Do not
call it from a timer loop. Use it after connect/auth, reconnect, explicit manual
refresh, detected drift, or post-transaction reconciliation when no owner-direct
push is expected.
Wire rules
The wire is closed.
- Every field is present on every frame. A fact that can be absent is a tagged union;
nullappears only asnext_cursoron the last page. A missing key is a decode error. - A shape that depends on state is a tagged union, for example
terms,state,scope,cursor,verdictandrole. - Unknown message types, error codes, enum values and fields are rejected.
- Requests have no defaults. Filters, limits and cursors are required fields.
Connection flow
Connect -> Hello -> Welcome -> AuthRequest -> AuthChallenge -> AuthSuccess -> Snapshot -> Subscribe -> ...
Makers are auto-challenged on a fresh connection. The server sends AuthRequest
immediately after Welcome; StartAuth is unnecessary and ignored on maker
endpoints. A reconnect may instead send ResumeAuth with the previous maker
session ID. Resume credentials are endpoint-role bound: a maker credential is
rejected on the taker endpoint.
AuthSuccess.expires_at is the Unix-second deadline for starting another
connection with that maker resume credential. An already-authenticated
connection remains live until disconnect, replacement, logout, blacklist, or
server shutdown.
Data connection
/maker/data has the same handshake as /maker: Hello, Welcome, an automatic AuthRequest, AuthChallenge, AuthSuccess, Snapshot. Sign with quote_signing and send the maker_owner pubkey, as on /maker. Send the same Hello. on_disconnect is required, but a data session owns no quotes.
After Snapshot, do not send Subscribe: it is rejected with WrongEndpoint. Send GetMmSummary. Owner pushes start after it is answered. A data session never replaces the /maker session; the limit is under owner-direct delivery.
Resume
ResumeAuth reconnects without a new signature, on /maker and on /maker/data. Send it after Welcome with session_id from the last AuthSuccess:
{ "type": "ResumeAuth", "data": { "session_id": "3a5c7e9b-1d2f-4e60-8a4c-6b8d0f2a4c71" } }
The server has already sent AuthRequest. Keep that challenge, and do not answer it while the resume is pending.
- On success you get
AuthSuccesswith the samesession_id, thenSnapshot. The session's server-side subscriptions are restored, and the pending challenge no longer applies. - On
AuthErrorwith reasonsession_expired, the connection stays open and the pending challenge is still valid. Sign it and sendAuthChallengebefore the auth deadline. - Any other
AuthErrorreason is in the WS error code catalog.
A failed resume counts as a failed auth attempt.
Hello (first message)
Protocol constraints:
HelloMUST be the first client message.Hellotimeout:5000ms.protocol_versionmust equal the server's1.0.0exactly. There is no range check.- All four fields are required. Extra fields are rejected.
{
"type": "Hello",
"data": {
"protocol_version": "1.0.0",
"on_disconnect": "cancel_quotes",
"client_name": "maker-bot",
"client_version": "0.1.0"
}
}
on_disconnect sets what the server does with the quotes this connection owns when it ends:
| Value | Effect |
|---|---|
cancel_quotes | On an actual disconnect (socket close or liveness timeout), the server removes active and retained non-winning quotes still owned by that physical session, including retained quotes in locked RFQs. Ownership takeover preserves quotes; late cleanup of the replaced connection cannot cancel the new owner's book. Quotes a taker has already accepted (QuoteSelected) stay locked and settle or expire on their own timers. Session resume does not restore cancelled quotes; re-quote after reconnecting. |
keep_quotes | Resting quotes survive a disconnect and can be filled while the maker is offline. |
QuoteExpired is always sent. There is no feature negotiation.
A different protocol_version gets an Error frame and a WebSocket close with code 4006:
{
"type": "Error",
"data": {
"type": "Generic",
"data": {
"code": "unsupported_protocol_version",
"message": "Protocol 0.9.0 is not supported; expected 1.0.0"
}
}
}
Welcome (server -> client)
{
"type": "Welcome",
"data": {
"protocol_version": "1.0.0",
"server_version": "0.1.0",
"min_supported_version": "1.0.0",
"server_now_at_ms": 1710000000000,
"min_quote_validity_seconds": 60,
"settlement_buffer_seconds": 50,
"rate_limits": {
"connection": { "type": "bucket", "per_second": 30, "burst": 60 },
"wallet": { "type": "unlimited" },
"rfqs": { "type": "unlimited" },
"queries": { "type": "bucket", "per_second": 20, "burst": 40 },
"liquidity_provider": { "type": "shared", "per_second": 1000, "burst": 2000 }
}
}
}
server_now_at_ms is required. Use it for clock skew estimation (see WS common conventions).
min_quote_validity_seconds and settlement_buffer_seconds are the venue quote window, the same values as GET /api/v1/venue: valid_until must be at least now + min_quote_validity_seconds, and a quote stays executable only while valid_until - settlement_buffer_seconds > now. The Rust QuoteBuilder::welcome(&welcome) applies both.
Subscribe
{
"type": "Subscribe",
"data": {
"request_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"products": ["covered_call", "cash_secured_put", "call_spread", "put_spread", "cash_put"],
"channels": ["rfqs", "chain_events"],
"underlying_mints": [],
"quote_mints": []
}
}
All fields are required. The server answers with SubscribeAck echoing request_id and the channels that were newly added.
productsis a nonempty list of unique product names:covered_call,cash_secured_put,call_spread,put_spread,cash_put. An empty list is rejected withinvalid_products. RFQ fan-out follows this selection. Position, history and recovery reads include every product regardless of it.underlying_mintsandquote_mintsfilter market broadcasts.[]means every mint.- Each
Subscribereplaces the product selection and both mint lists. Channels are additive.
The two mint lists may contain at most 1024 entries in total after each list is deduplicated. A mint present in both lists counts twice. An oversized Subscribe or AddMints returns a correlated RequestError with code subscription_scope_too_large; the existing scope and channels stay unchanged.
Connection policy defaults
- Auth deadline (after challenge issued):
15s - Idle timeout:
90s - Server WS ping interval:
30s - Max consecutive parse errors before close:
3 - Inbound message size:
32 KiB - Rate limits: Rate limits and admission.
Snapshot (server -> maker)
{
"type": "Snapshot",
"data": {
"markets": [
{
"pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"products": [
"covered_call",
"call_spread"
],
"status": "active",
"settlement": {
"type": "pending"
}
}
]
}
}
Snapshot.markets lists the active markets as compact MarketInfo. settlement is { "type": "pending" } until the market settles, then { "type": "fixed", "price" }. products is described under Market products. This is a different DTO from the MarketDescriptor in RfqBroadcast, which has additional fields (chain_id, program_id, market_pda, underlying_mint, quote_mint, collateral_mint, settlement_mint). Use GetMarketDescriptors for the full market descriptor.
Message index
Client -> Server
Hello,AuthChallenge,ResumeAuth,LogoutSubscribe,Unsubscribe,PingAddMints,RemoveMints,AddChannels,RemoveChannelsQuote,ReplaceQuote,BatchQuotes,CancelQuote,CancelAllQuotesIndicativePricesResponseGetOrderStatus,GetMyQuotes,GetMakerPositions,GetMarketsForMaker,GetMmSummary,GetMyTrades,GetTokenCaps,GetMyCaps,CheckQuote,GetSubscriptionsGetActiveRfqs,GetMarkets,GetMarketDescriptors,GetExpiries,GetTokens
Server -> Maker (direct)
Welcome,LogoutSuccessAuthRequest,AuthSuccess,AuthErrorSnapshot,ReferenceChangedRfqBroadcast,RfqSkippedQuoteRefreshRequested,QuoteAcknowledged,QuoteBestStatus,QuoteOutbid,QuoteSelectedQuoteRejected,QuoteFilled,QuoteCancelled,QuoteExpired,RfqLocked,RfqAvailableAgain,RfqClosedCancelQuoteAck,CancelAllQuotesAck,BatchQuotesAckIndicativePricesRequestSubscriptionUpdatedError,RequestError,PongSubscribeAck,UnsubscribeAck
Server -> Maker (responses / query results)
OrderStatus,MyQuotes,MakerPositions,MakerMarkets,MmSummary,MyTrades,TokenCaps,MyCaps,QuoteCheck,SubscriptionsActiveRfqs,Markets,MarketDescriptors,Expiries,Tokens
Server -> Maker (owner-direct, no subscription)
PositionUpdated,MakerCapsUpdated,TradeExecuted
Delivered to the owner's quote session and ready /maker/data sessions. Data
sessions become eligible after a successful GetMmSummary response; authentication
alone does not enable pushes. No subscription is needed. Up to four authenticated
data sessions per owner are allowed; the fifth receives AuthError with
reason = "session_limit_exceeded". Disconnect or logout releases its slot.
A full data queue closes only that session (4002 slow_consumer). Reconcile on
restart/reconnect: these pushes are not replayed.
Server -> Maker (broadcast if subscribed)
StatsUpdate,ChainEventMarketCreated,MarketFinalizedVaultCatalogChanged,VaultProjectionAdvanced(vaultschannel; see ws-common)
Delivery by endpoint
Pushes reach a session in one of three ways: a channel the session subscribed
to (Subscribe is accepted on /maker and /vault, not on /maker/data),
the session that sent the quote, or the maker owner's /maker and ready
/maker/data sessions regardless of subscriptions. Query responses (MyQuotes, MakerPositions,
MmSummary, ...) return on the connection that asked.
| Message | /maker | /maker/data | /vault |
|---|---|---|---|
RfqBroadcast | rfqs channel, within the product and mint scope | no | sessions with sign_maker_quotes, no subscription |
RfqSkipped | rfqs channel, makers the caps prefilter skipped | no | sessions with sign_maker_quotes the prefilter skipped |
IndicativePricesRequest | side: "sell" on the rfqs channel, side: "buy" on taker_buy_rfqs | no | no |
RfqLocked | every session that quoted the RFQ except the accepted one | no | every session that quoted the RFQ except the accepted one |
QuoteAcknowledged, QuoteRejected, QuoteBestStatus, QuoteOutbid, QuoteSelected, QuoteRefreshRequested, QuoteExpired, QuoteCancelled | the session that sent the quote | no | the session that sent the quote |
QuoteFilled | the session that sent the winning quote | no | the session that sent the winning quote |
RfqClosed, RfqAvailableAgain | every session that quoted the RFQ | no | every session that quoted the RFQ, and the taker session |
OrderAccepted, SponsoredTxToSign, OrderSubmitted, OrderConfirmed, OrderFailed | never: these go to the taker | no | only as the taker of its own RFQ |
TradeExecuted | owner's session, no subscription | owner's ready sessions, no subscription | no |
PositionUpdated, MakerCapsUpdated | owner's session, no subscription | owner's ready sessions, no subscription | no |
ReferenceChanged | every session | every ready session | every session |
MarketCreated, MarketFinalized | markets channel | no | no |
StatsUpdate / ChainEvent | stats / chain_events channel | no | no |
VaultCatalogChanged | vaults channel | no | no |
VaultProjectionAdvanced | vaults channel | no | vaults channel, own vault only |
A maker learns of its fill from QuoteFilled (and TradeExecuted), never from
OrderConfirmed. PositionUpdated and MakerCapsUpdated reach the owner's
/maker session and its ready /maker/data sessions; a client with neither
recovers them with GetMakerPositions, GetMyCaps or GetMmSummary.
Products and terms
Every RFQ, quote, position and trade carries two required fields: terms and side.
terms is a tagged union. Each variant carries exactly its own fields.
terms.type | Fields | Settlement |
|---|---|---|
covered_call | strike | physical |
cash_secured_put | strike | physical |
call_spread | lower_strike, upper_strike | cash, in the quote mint |
put_spread | lower_strike, upper_strike | cash, in the quote mint |
cash_put | strike | cash, in the quote mint |
{ "type": "covered_call", "strike": "160000000000" }
{ "type": "call_spread", "lower_strike": "100000000000", "upper_strike": "120000000000" }
{ "type": "cash_put", "strike": "150000000000" }
- Strikes are integers scaled by 1e9 per underlying token, independent of mint decimals.
strike_tickfromGetTokensis on the same scale. sidedescribes the taker:sellorbuy. To see and quotebuyRFQs, subscribe totaker_buy_rfqs; without it the RFQ is not delivered and a quote is rejected withunauthorized. Abuyis written from Maker PDA custody (a vault writes from its collateral leg instead): the server refuses a quote when custody is below the collateral, which is the width times quantity for a spread or cash put. Custody is read, not reserved, so overlapping quotes can fail at fill.cash_putis economically a put spread with lower strike 0 and upper strike K. It settles in cash and executes on chain with those legs. It is signed with the put-spread product byte, lower strike0and upper strike K.- Public
call_spreadandput_spreadterms require0 < lower_strike < upper_strike. Both strikes are chosen by the taker. For puts the short strike is the upper strike. - A put with a zero lower leg is a
cash_put. Aput_spreadwithlower_strike0is rejected withspread_invalid_strikes. On chain a position with legs(0, K)reads back ascash_put. - Both strikes of a spread, and the strike of a
cash_put, must be multiples of the underlying mint'sstrike_tick. A mint without a tick is rejected withmissing_tick_for_underlying_mint. order_optionslists complete alternativeterms, never independent legs. A spread RFQ lists exactly its requested pair.
Market products
Each market row (Snapshot, Markets, MarketDescriptors, MakerMarkets, MarketCreated, GET /api/v1/markets) carries a nonempty products list. It holds only the products of the pair's policy that fit the market's side:
| Market | Possible products |
|---|---|
is_put: false | covered_call, call_spread |
is_put: true | cash_secured_put, put_spread, cash_put |
A market with no allowed product is not listed. An RFQ for a product the pair does not allow is rejected with product_not_allowed.
Cash settlement and fees
Spreads and cash_put pay out in the quote mint. Their lifecycle is open then settled. They have no funded state, no liquidation and no early close, so a position of one of these products never produces PositionUpdated with update_type funded or liquidated.
With ud underlying decimals, qd quote decimals and width = upper_strike - lower_strike (width = strike for cash_put):
- Collateral:
C = ceil(width * quantity * 10^qd / (1e9 * 10^ud)), in quote atoms. - Gross premium:
gross = floor(price * quantity * 10^qd / (1e9 * 10^ud)), in quote atoms. - Admission requires
quantity > 0,0 < price < widthand0 < gross < C. - Premium fee:
gross - quote(price - floor(price * protocol_fee_bps_premium / 10000)), wherequote(x)is the same scaled conversion with floor. - Volume fee:
floor(exposure * protocol_fee_bps_volume / 10000).exposureisquote(width)for spreads andcash_put, andquote(strike)for covered calls and cash-secured puts. - Protocol fee:
min(premium fee, volume fee). Net premium:gross - protocol fee. protocol_fee_bps_premiumandprotocol_fee_bps_volumeare the quote token'sprotocol_fees.premium_bpsandvolume_bpsinGET /api/v1/tokens; each quote token has its own.- The writer bears the fee. On a taker sell you pay the gross premium and the taker receives the net. On a taker buy the taker pays the gross
priceand you, the writer, receive the net premium.
Worked example. A call spread 100 to 120 on 1 SOL (quantity 1000000000, ud 9, qd 6) at price 5000000000, with fees of 50 and 10 bps:
| Value | Atoms |
|---|---|
C | 20000000 |
gross | 5000000 |
| premium fee | 25000 |
| volume fee | 20000 |
| protocol fee | 20000 |
| net premium | 4980000 |
A cash-settled position settles at settlement price S:
- Call spread payoff to the maker:
ceil(quantity * min(max(S - lower, 0), width)), scaled to quote atoms. - Put spread payoff:
ceil(quantity * min(max(upper - S, 0), width)), scaled to quote atoms. - Cash put payoff:
ceil(quantity * max(K - S, 0)), scaled to quote atoms and capped atC. - The taker receives the remaining collateral.
The Rust SDK computes these with SpreadTerms::premium (spreads and cash puts) and physical_premium (covered calls and cash-secured puts). Both return the contract's rounding.
Quote flow
RfqBroadcast (server -> maker)
{
"type": "RfqBroadcast",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"market_descriptor": {
"chain_id": 0,
"program_id": "33Ezs5eoa16QyPW8wifnyz2nCyMEcq2crqkVBNjnTE8U",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"collateral_mint": "So11111111111111111111111111111111111111112",
"settlement_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
},
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"quantity": "1000000000",
"expires_at": 1710000050,
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"order_options": [
{ "type": "covered_call", "strike": "150000000000" },
{ "type": "covered_call", "strike": "160000000000" }
],
"sent_at_ms": 1710000000123
}
}
terms is the RFQ's primary terms. order_options is a list of complete alternative terms and may be empty.
- Covered call and cash-secured put: the quote's strike must be the strike of
termsor of anorder_optionsentry. Any other strike is rejected withinvalid_strike. - Spreads and cash puts: the quote's
termsmust equal the RFQ'stermsexactly. Any difference is rejected withquote_identity_mismatch. - The quote's product and
sidemust match the RFQ. Otherwise the quote is rejected withquote_identity_mismatch.
RfqSkipped (server -> maker)
Sent instead of RfqBroadcast when cap limits pre-filter the maker. cap_detail is the failing cap; the full catalog is in CapError.
{
"type": "RfqSkipped",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"quantity": "1000000000",
"cap_detail": {
"token_oi_cap_exceeded": {
"underlying_mint": "So11111111111111111111111111111111111111112",
"current": "1000000000000",
"limit": "1000000000000"
}
}
}
}
The filter runs before broadcast and knows no premium, so maker_insufficient_balance.required is always 0 here.
Quote (maker -> server)
{
"type": "Quote",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"price": "5000000000",
"valid_until": 1710000120,
"nonce": "42",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"signature": "<base58 ed25519 signature of order_id>"
}
}
A spread or cash-put quote uses the same fields with the matching terms:
{
"type": "Quote",
"data": {
"rfq_id": "00000000-0000-0000-0000-000000000001",
"terms": { "type": "call_spread", "lower_strike": "100000000000", "upper_strike": "120000000000" },
"side": "sell",
"price": "5000000000",
"valid_until": 1799999900,
"nonce": "999",
"order_id": "0x0101010101010101010101010101010101010101010101010101010101010101",
"signature": "<base58 ed25519 signature of order_id>"
}
}
price is the gross premium per underlying unit, scaled by 1e9.
Rules:
valid_untilMUST be >=now + min_quote_validity_seconds(fromWelcomeorGET /api/v1/venue). A shorter expiry is rejected withquote_expiry_too_short.valid_untilMUST be <= the market'sexpiry_ts. A later expiry is rejected withmarket_expired.- The server applies a settlement buffer (
settlement_buffer_seconds). Your quote is active for trading untilvalid_untilminus that buffer. Setvalid_untilto at leastrfq.expires_at + min_quote_validity_secondsso the quote stays tradable for the whole auction. order_id = sha256(preimage). The preimage is 182 bytes for covered calls and cash-secured puts and 190 bytes for spreads and cash puts. See Order id preimage.- The maker signs only the 32-byte
order_id. termsandsidemust match the RFQ as described under RfqBroadcast.
Order id preimage
Before building the preimage, derive the market PDA locally using Solana PDA seeds
["market", underlying_mint[32], quote_mint[32], expiry_ts_u64_le[8], is_put_u8[1]]
under the Acta program ID from your deployment configuration. The program ID is the same on devnet and mainnet. GET /api/v1/venue returns it as program_id. Require chain ID
0, that configured program ID, and equality with market_pda. Also check that
the product fits is_put: puts are cash_secured_put, put_spread and cash_put; calls are covered_call and call_spread. Check the mints on the RFQ's market_descriptor: collateral/settlement are underlying/quote for covered
calls, quote/underlying for cash-secured puts, and quote/quote for spreads and cash puts. These pairs apply to RfqBroadcast, whose market_descriptor is built for the RFQ's product. Rows of MarketDescriptors are market-level: they always show the physical pair for the market's side, so on a spread or cash-put RFQ they differ from the broadcast. Do not copy an endpoint-selected program ID
into the derivation. Rust RfqBinding::from_broadcast and TS
buildSignedQuoteFromRfq perform these checks before signing. Strategy mint
allowlists and pricing inputs remain your responsibility; PDA verification does
not certify an endpoint's prices or mint decimals.
All numeric fields use little-endian encoding. The domain tag is ACTA for both layouts.
Physical layout (covered call, cash-secured put), 182 bytes (offset, size):
0,4->domain_tag("ACTA")4,8->chain_id(u64,0for Solana)12,32->program_id44,1->is_taker_buy(u8:0for sidesell,1forbuy)45,1->position_type(u8:0covered_call,1cash_secured_put)46,32->market78,8->strike(u64)86,8->quantity(u64)94,8->gross_price(u64)102,8->valid_until(u64, unix seconds)110,32->maker(themaker_ownerpubkey)142,32->taker174,8->nonce(u64)
Spread layout (call spread, put spread, cash put), 190 bytes. Offsets 0 to 181 are as above, with these differences:
45,1->position_type(u8:2call_spread,3put_spread)78,8->lower_strike(u64)182,8->upper_strike(u64)
A cash put is economically a put spread with lower strike 0. The wire name is cash_put; a strike K uses position_type 3, lower_strike 0 and upper_strike K in the preimage.
gross_price is the same value as price in the Quote message.
maker is the maker_owner pubkey. It is not the maker PDA (AuthSuccess.role.maker_pda) and not the quote_signing key. For a vault operator's quote it is the vault PDA. taker is RfqBroadcast.taker.
Test vectors
These vectors come from the Rust SDK fixture tests/fixtures/order_preimage_vectors.json: physical_covered_call, spread_call and cash_put_zero_lower. Test your builder against them before quoting. All three use chain_id 0, program_id 32 bytes of 0x04, market 32 bytes of 0x01, maker 32 bytes of 0x02, taker 32 bytes of 0x03, side sell, quantity 1000000, gross_price 1000000000, valid_until 123 and nonce 999. order_id here is plain hex; the wire accepts it with or without a 0x prefix.
Covered call, 182 bytes: position_type 0, strike 100000000000.
preimage: 41435441000000000000000004040404040404040404040404040404040404040404040404040404040404040000010101010101010101010101010101010101010101010101010101010101010100e876481700000040420f000000000000ca9a3b000000007b0000000000000002020202020202020202020202020202020202020202020202020202020202020303030303030303030303030303030303030303030303030303030303030303e703000000000000
order_id: 292033726f26752392a0c18ccdc1e09016c0601e3d74b42fc0d5ef98e0190eb6
Call spread, 190 bytes: position_type 2, lower_strike 100000000000, upper_strike 120000000000.
preimage: 41435441000000000000000004040404040404040404040404040404040404040404040404040404040404040002010101010101010101010101010101010101010101010101010101010101010100e876481700000040420f000000000000ca9a3b000000007b0000000000000002020202020202020202020202020202020202020202020202020202020202020303030303030303030303030303030303030303030303030303030303030303e70300000000000000b08ef01b000000
order_id: 37d008c2a5ca5ea9dbf727994e4fdb394cc52bd53b1ed91e74a03bfbdd672c3f
Cash put, 190 bytes: position_type 3, lower_strike 0, upper_strike 120000000000 (terms.strike 120000000000).
preimage: 414354410000000000000000040404040404040404040404040404040404040404040404040404040404040400030101010101010101010101010101010101010101010101010101010101010101000000000000000040420f000000000000ca9a3b000000007b0000000000000002020202020202020202020202020202020202020202020202020202020202020303030303030303030303030303030303030303030303030303030303030303e70300000000000000b08ef01b000000
order_id: 03b50d62e08b00556ccb458945ebfa2570fdd65b50e9753e911584fb4951c52c
ReplaceQuote (maker -> server)
Atomic cancel-and-resubmit for a specific quote. Cancels the quote identified by replaced_order_id and submits a new quote in a single operation. The old quote is removed only if the new quote passes all validation (caps, signature, valid_until). If validation fails, the old quote remains active.
{
"type": "ReplaceQuote",
"data": {
"replaced_order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"price": "5500000000",
"valid_until": 1710000120,
"nonce": "43",
"order_id": "0xb2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
"signature": "<base58 ed25519 signature of order_id>"
}
}
replaced_order_id identifies the specific quote being replaced. Server responds with QuoteAcknowledged (with replaced) on success, or QuoteRejected / Error on failure.
Errors:
QuoteRejectedwith standard reasons (invalid_strike,cap_exceeded, etc.) — new quote failed validation; old quote remains activeError { type: "QuoteLocked", data: { reason } }— the old quote cannot be replaced:reasonisrfq_lockedwhile the taker's signature is pending andorder_submittedonce the signed transaction is queuedError { type: "QuoteNotFound" }—replaced_order_idnot found (race: already cancelled/expired)
BatchQuotes (maker -> server)
Submit multiple quotes in one message. A batch must contain at most max_batch_quotes quotes (GET /api/v1/venue, 50 by default). The server charges one quote-rate-limit token per quote element; an empty batch costs one token. Within an accepted batch, each quote is validated like a standalone Quote. The server responds with one BatchQuotesAck containing results[] — one entry (acknowledged or rejected) per quote that reached quote-level validation. Correlate results by order_id, not by position: a quote rejected at initial validation (bad signature, expired, unregistered maker) is reported as an inline error and may be omitted from results[]. Partial success is allowed. For an implicit same-terms replacement, the aggregated QuoteAcknowledged has replaced: { "type": "none" }; the replaced order id is delivered on the asynchronous per-quote QuoteAcknowledged event.
{
"type": "BatchQuotes",
"data": {
"quotes": [
{
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"terms": { "type": "covered_call", "strike": "150000000000" },
"side": "sell",
"price": "4500000000",
"valid_until": 1710000120,
"nonce": "44",
"order_id": "0xaaaa2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"signature": "<base58 ed25519 signature of order_id>"
},
{
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"price": "5000000000",
"valid_until": 1710000120,
"nonce": "45",
"order_id": "0xbbbb2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"signature": "<base58 ed25519 signature of order_id>"
}
]
}
}
Each entry in quotes has the same schema as a standalone Quote message. Quotes are processed sequentially — a rejection of one quote does not block subsequent quotes.
Each results entry is { "status": "acknowledged", "data": <QuoteAcknowledged> } or { "status": "rejected", "data": <QuoteRejected> }:
{
"type": "BatchQuotesAck",
"data": {
"results": [
{
"status": "acknowledged",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0xaaaa2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"replaced": {
"type": "none"
}
}
},
{
"status": "rejected",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0xbbbb2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"reason": "invalid_strike",
"message": "strike is not offered by the RFQ"
}
}
]
}
}
QuoteRejected (server -> maker)
QuoteRejected is sent for quote-specific validation failures and carries a typed reason for programmatic handling. message is a required string with detail for logs.
{
"type": "QuoteRejected",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"reason": "invalid_strike",
"message": "strike is not offered by the RFQ"
}
}
A cap rejection carries the failing dimension inside the reason instead of a bare string, so it cannot arrive without its detail:
{
"type": "QuoteRejected",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"reason": { "cap_exceeded": { "maker_position_cap_exceeded": { "current": 3, "limit": 3 } } },
"message": "Maker position cap exceeded (3/3)"
}
}
The value under cap_exceeded is a CapError: a bare string for
caps_unavailable, otherwise an object keyed by the cap code (see
Capacity limits for the codes and amounts).
QuoteRejectReason
| Value | Meaning |
|---|---|
product_not_allowed | The pair's product policy does not allow the quoted product |
unauthorized | Session is not an authenticated maker, or a vault maker that may not trade or hold this position (see message) |
invalid_strike | Covered-call or cash-secured-put strike is not offered by the RFQ |
spread_invalid_strikes | Zero, reversed or otherwise invalid spread strikes |
spread_tick_violation | A strike is not a multiple of the underlying mint's strike tick |
spread_premium_invalid | price >= width, zero gross premium, gross >= C, or the amounts are not representable |
quote_identity_mismatch | Product, side or spread terms differ from the RFQ |
market_expired | valid_until is after the market's expiry, or the market has expired |
quote_expiry_too_short | valid_until below now + min_quote_validity_seconds |
invalid_signature | Maker signature verification failed |
maker_not_registered | Maker not found in on-chain registry |
order_id_mismatch | order_id does not match sha256(preimage) |
{ "cap_exceeded": CapError } | Platform or maker cap limit exceeded; the failing dimension with current/limit is the payload |
rfq_not_found | RFQ does not exist |
rfq_not_active | RFQ is no longer accepting quotes |
duplicate_order_id | order_id already submitted |
rate_limited | The liquidity_provider bucket is empty; back off and retry. See Rate limits |
trading_paused | Trading is paused venue-wide; retry after it resumes |
internal_error | Server-side failure; the quote was not accepted, retry is safe |
QuoteRefreshRequested (server -> maker)
{
"type": "QuoteRefreshRequested",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"min_valid_until": 1710000121,
"reason": "expiring_soon"
}
}
The refresh timer fires at valid_until - settlement_buffer_seconds - quote_refresh_lead_seconds. The quote then stays in the book but cannot be accepted until you send a fresh one. min_valid_until is the authoritative lower bound for the replacement. Use the value in the frame; it also accounts for the configured admission minimum.
Identified by (rfq_id, terms), not order_id. If quoting several terms per RFQ, keep a local (rfq_id, terms) -> order_id mapping to know which quote to refresh.
reason is expired or expiring_soon. min_valid_until includes the settlement buffer; the refreshed quote must have valid_until >= min_valid_until.
QuoteSelected (server -> maker)
{
"type": "QuoteSelected",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"price": "5000000000",
"quantity": "1000000000",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"signature_deadline_at": 1710000040
}
}
QuoteFilled (server -> maker)
{
"type": "QuoteFilled",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"expiry_ts": 1710600000,
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"price": "5000000000",
"quantity": "1000000000",
"position_pda": "75NqraLLofiLUpNQg2wUPG6CJpxcaGEZUwuNrnAgvcTP",
"transaction_signature": "<base58 transaction signature>",
"filled_at": 1710000042
}
}
QuoteFilled is the fill-details event for the winning maker. market_pda,
expiry_ts (market expiry, Unix seconds), terms and side identify the
market and product without the RFQ, so a fill can be attributed after a restart. Mint
decimals for the market come from GetMarketDescriptors.
QuoteFilled is the fill fact. It carries price and quantity, and it is sent before any chain event reaches the server, so it has no fee, net premium or collateral fields.
The authoritative net premium is total_premium on the PositionUpdated row, applied by revision. MakerPositions and MmSummary return the same row.
To have the amounts at once, compute them locally with the quote token's rates (protocol_fees in GET /api/v1/tokens): the Rust SDK's physical_premium for covered calls and cash-secured puts, and SpreadTerms::premium for spreads and cash puts. The result is an estimate if the rates changed.
quantity is in underlying atoms and price is 1e9-scaled per underlying token, so the gross
premium (before protocol fees) in quote atoms is floor(price * quantity * 10^quote_decimals / (1e9 * 10^underlying_decimals))
(the contract's rounding; the Rust SDK's total_premium_quote_atoms and the TS
SDK's totalPremiumQuoteAtoms compute it).
RfqClosed is the terminal RFQ event.
Current runtime behavior for successful fills:
- winner maker receives
RfqClosedand thenQuoteFilled; accept fill details after the RFQ has closed - taker receives
OrderConfirmedand thenRfqClosed - close RFQ state only on
RfqClosed; processQuoteFilledas fill-details information
QuoteAcknowledged (server -> maker)
{
"type": "QuoteAcknowledged",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"replaced": {
"type": "none"
}
}
}
replaced is { "type": "replaced", "order_id" } with the displaced order when the new quote replaced a prior quote from the same maker on the same (rfq, terms), and { "type": "none" } otherwise.
QuoteBestStatus (server -> maker)
{
"type": "QuoteBestStatus",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"is_best": true,
"current_best_price": {
"type": "quoted",
"price": "5000000000"
}
}
}
is_best: whether the maker's quote is currently the highest premium.
current_best_price: the best price on the RFQ (may be another maker's price), as { "type": "quoted", "price" }, or { "type": "none" } when there is none.
QuoteOutbid (server -> maker)
{
"type": "QuoteOutbid",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"your_price": "5000000000",
"current_best_price": {
"type": "quoted",
"price": "5500000000"
}
}
}
your_price: the maker's current quote price.
current_best_price: the new best price that outbid the maker, as { "type": "quoted", "price" }, or { "type": "none" } when there is none.
QuoteExpired (server -> maker)
Always sent when a quote expires.
{
"type": "QuoteExpired",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"reason": "expired"
}
}
reason is expired or expiring_soon.
QuoteCancelled (server -> maker)
{
"type": "QuoteCancelled",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_ids": ["0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a"],
"reason": "requested",
"cancelled_at": 1710000025
}
}
reason values: requested (maker requested), risk_check (server-side risk), rfq_accepted (RFQ accepted another quote), maker_disconnected (the session said on_disconnect: "cancel_quotes" and disconnected; sent to the session that is gone, so a reconnecting maker sees the cancellation through GetMyQuotes).
RfqClosed (server -> maker)
{
"type": "RfqClosed",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"rfq_version": 3,
"reason": "filled",
"your_quote": {
"type": "quoted",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"status": "outbid",
"price": "5000000000"
},
"winner": {
"type": "winner",
"maker_owner": "A87ysNWAmmqQHafLSQGbYSLhtcV3BjXctR88EWuSobGP",
"price": "5500000000",
"transaction": {
"type": "sent",
"signature": "<base58 transaction signature>"
}
},
"closed_at": 1710000042
}
}
reason values: expired, taker_cancelled, filled, market_expired, server_shutdown (see RfqCloseReason).
your_quote is { "type": "quoted", "order_id", "status", "price" } with this session's quote on the RFQ, or { "type": "none" } when it has none. your_quote.status values: expired, outbid, cancelled, filled. A session with several quotes gets one of them; a session that won gets the winning quote.
winner is { "type": "winner", "maker_owner", "price", "transaction" } on filled and { "type": "none" } otherwise. transaction is { "type": "sent", "signature" } once the transaction is sent, otherwise { "type": "pending" }.
- On
filled, every recipient getswinner, includingwinner.transaction. The winning session getsyour_quote.statusfilled, a session with another live quote getsoutbid, and a session whose quotes are already gone gets{ "type": "none" }. - On any other reason, a session with a live quote gets it with status
expired(reasonexpired) orcancelled. A session whose quotes are already gone gets{ "type": "none" }.
RfqLocked (server -> maker)
{
"type": "RfqLocked",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"rfq_version": 2,
"locked_at": 1710000030
}
}
Sent to every other maker on the RFQ when the taker accepts a quote; the accepted maker gets QuoteSelected instead. Your quote stays live as a backup and the RFQ takes no new quotes until RfqAvailableAgain or RfqClosed.
RfqAvailableAgain (server -> maker)
{
"type": "RfqAvailableAgain",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"rfq_version": 2,
"reason": "signature_timeout",
"available_again_at": 1710000045
}
}
Sent when a previously locked RFQ becomes available for new quotes (e.g. taker failed to sign in time).
reason values: signature_timeout, tx_failed, tx_build_failed.
Quote management
CancelQuote (maker -> server)
{
"type": "CancelQuote",
"data": {
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
Cancels all of this connection's active quotes on the given RFQ (across all terms). There is no per-order_id cancel — use CancelQuote per rfq_id. The server responds once the cancellation is applied with CancelQuoteAck { request_id, rfq_id, cancelled_order_ids }, or a correlated RequestError (for example RfqNotFound, RfqNotActive, QuoteLocked). QuoteCancelled is a lifecycle notification, not the command receipt.
CancelQuoteAck (server -> maker)
{
"type": "CancelQuoteAck",
"data": {
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"cancelled_order_ids": ["0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a"]
}
}
On an Active RFQ an empty list is an idempotent no-op: the connection has no quote to remove there. While the taker's signature is pending or the signed transaction is queued, single-RFQ cancellation is rejected as a whole with QuoteLocked, even for a non-winning maker.
CancelAllQuotes (maker -> server)
{
"type": "CancelAllQuotes",
"data": {
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"market_pda": { "type": "only", "value": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi" }
}
}
market_pda is a QueryFilter. { "type": "all" } considers all markets; only restricts cancellation to that market. CancelAll removes this connection's active and retained non-winning quotes, including those inside locked RFQs. Removed retained quotes cannot return on rollback. Selected/awaiting-signature and executing orders are preserved. Cancel-on-disconnect (on_disconnect: "cancel_quotes") applies the same cleanup once the server processes the disconnect. Neither operation is an account-wide persistent halt.
The server responds with CancelAllQuotesAck once the cancellation is applied. An invalid market_pda returns RequestError with InvalidMarket; it does not broaden cancellation to all markets.
CancelAllQuotesAck (server -> maker)
{
"type": "CancelAllQuotesAck",
"data": {
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"cancelled_count": 0,
"cancelled_order_ids": []
}
}
cancelled_count equals cancelled_order_ids.length; both report the orders actually removed. An empty list means this command removed no quotes; it does not establish that no selected or executing obligations remain. Lifecycle QuoteCancelled messages are separate from the receipt and must not complete another request's await.
Quote, batch, replacement and cancellation commands from one connection retain FIFO order from the SDK writer through the server's processing. Commands before a cancellation may execute first; commands sent afterward may create new quotes. Cancellation is not a persistent account halt.
If the connection drops before the ACK, retain an unknown outcome and reconcile instead of automatically replaying the command.
Dynamic subscription management
Modify subscriptions incrementally. Every field is required.
{ "type": "AddMints", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000101", "underlying_mints": ["So11111111111111111111111111111111111111112"], "quote_mints": [] } }
{ "type": "RemoveMints", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000102", "underlying_mints": ["So11111111111111111111111111111111111111112"], "quote_mints": [] } }
{ "type": "AddChannels", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000103", "channels": ["trades"] } }
{ "type": "RemoveChannels", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000104", "channels": ["stats"] } }
In AddMints and RemoveMints, [] means no change for that list. All four respond with SubscriptionUpdated containing the full subscription state:
{
"type": "SubscriptionUpdated",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000101",
"channels": ["rfqs", "trades"],
"underlying_mints": ["So11111111111111111111111111111111111111112"],
"quote_mints": []
}
}
In responses, an empty mint list means that dimension is unfiltered.
Unsubscribe (maker -> server)
{
"type": "Unsubscribe",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000105",
"channels": ["trades"]
}
}
Server responds with UnsubscribeAck echoing request_id and the channels that were removed. Use GetSubscriptions to verify the subscription state.
Ping (maker -> server)
{ "type": "Ping" }
Unit variant, no data field. Server responds with Pong.
Discovery
Discovery requests
All discovery requests require request_id (UUID). The server echoes request_id in the corresponding response. Maker-private and recovery reads should be sent on /maker/data; GetSubscriptions stays on /maker because it describes the live quote-plane subscription state.
{
"type": "GetMyQuotes",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000001",
"scope": {
"type": "live"
},
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetOrderStatus",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000002",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a"
}
}
{
"type": "GetMmSummary",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000003",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetSubscriptions",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000004",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetActiveRfqs",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000005",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetTokenCaps",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000006",
"include_markets": true,
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetMyCaps",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000007",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetMarkets",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000008",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetMarketDescriptors",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000009",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetTokens",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-00000000000a",
"limit": 200,
"cursor": {
"type": "start"
}
}
}
{
"type": "GetExpiries",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-00000000000b",
"underlying_mint": {
"type": "all"
},
"quote_mint": {
"type": "all"
},
"is_put": {
"type": "all"
},
"limit": 200,
"cursor": {
"type": "start"
}
}
}
Request notes:
GetMarkets,GetMarketDescriptors,GetExpiriesandGetTokensanswer from the reference snapshot: tradable markets only — non-finalized, non-disabled, and before the pre-expiry trading cutoff. Re-read onReferenceChanged.GetMyQuotestakesscope: { "type": "live" }or{ "type": "history" }, with top-levellimitandcursor. Live reads unfinished owner quotes across connections, including retained and selected quotes. History reads persisted historical rows. Both use common paging.GetMarketsForMakeruses the wider active set (non-finalized, non-disabled,expiry_ts > now), so it still lists a market during its final pre-expiry no-trade window.
Filters and pages
All lists use common paging.
QueryFilter is all or only { value }. TimeBound is unbounded or
bounded { value } in Unix seconds. Required list filters use [] for all values.
Position, quote-history and trade pages run newest first. Unrenderable maker
positions consume page slots and are covered by the returned cursor.
GetMakerPositions
Uses common paging.
{
"type": "GetMakerPositions",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000011",
"market_pda": { "type": "all" },
"underlying_mint": { "type": "only", "value": "So11111111111111111111111111111111111111112" },
"status": ["open", "funded"],
"min_expiry_ts": { "type": "bounded", "value": 1710000000 },
"limit": 100,
"cursor": { "type": "start" }
}
}
status is a list of open, funded, liquidated, settled; [] matches every status. min_expiry_ts keeps positions whose market expiry is at or after the bound. Follow its required nullable next_cursor.
GetMarketsForMaker
Uses common paging.
{
"type": "GetMarketsForMaker",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000012",
"underlying_mints": [
"So11111111111111111111111111111111111111112"
],
"quote_mints": [],
"min_expiry_ts": {
"type": "bounded",
"value": 1710000000
},
"max_expiry_ts": {
"type": "unbounded"
},
"is_put": {
"type": "only",
"value": false
},
"limit": 200,
"cursor": {
"type": "start"
}
}
}
The request has no result cap. Use filters for dashboard views and avoid polling it.
Markets payload
Uses common paging.
{
"type": "Markets",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000008",
"markets": [
{
"pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"products": [
"covered_call",
"call_spread"
],
"status": "active",
"settlement": {
"type": "pending"
}
}
],
"next_cursor": null
}
}
Same compact MarketInfo shape as Snapshot.markets; active markets only. status is active, closed or finalized. settlement is { "type": "pending" } until the market settles.
Expiries payload
Uses common paging.
{
"type": "Expiries",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-00000000000b",
"expiries_ts": [
1710600000,
1711200000
],
"next_cursor": null
}
}
List of distinct market expiry timestamps (Unix seconds) matching the request filters.
Tokens payload
Uses common paging.
{
"type": "Tokens",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-00000000000a",
"tokens": [
{
"mint": "So11111111111111111111111111111111111111112",
"symbol": "SOL",
"decimals": 9,
"oracle_feed_ids": [
"<oracle feed id>"
],
"role": {
"type": "underlying",
"size_rule": {
"min_size": "100000000",
"max_size": "1000000000000",
"step": "100000000"
},
"strike_tick": "500000000",
"quote_mints": [
"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
]
}
},
{
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"decimals": 6,
"oracle_feed_ids": [
"<oracle feed id>"
],
"role": {
"type": "quote"
}
}
],
"next_cursor": null
}
}
Each mint once; see TokenInfo. role is quote or underlying. Underlyings carry size_rule, strike_tick (1e9-scaled, like strikes) and quote_mints.
MarketDescriptorInfo (from MarketDescriptors)
Uses common paging.
Token decimals live here and nowhere in RfqBroadcast: RfqBroadcast.quantity,
QuoteFilled.quantity and size_rule are underlying atoms. Cache
underlying_decimals / quote_decimals by market_descriptor.market_pda (the Rust SDK's
MarketDecimals does this from MarketDescriptors).
type MarketDescriptor = {
chain_id: number;
program_id: string;
market_pda: string;
underlying_mint: string;
quote_mint: string;
expiry_ts: number;
is_put: boolean;
collateral_mint: string;
settlement_mint: string;
};
type MarketDescriptorInfo = {
products: string[];
market: MarketDescriptor;
underlying_oracle_pda: string;
quote_oracle_pda: string;
underlying_decimals: number;
quote_decimals: number;
size_rule: { // decimal strings, underlying atoms
min_size: string;
max_size: string;
step: string;
};
underlying_symbol: string;
quote_symbol: string;
};
MakerPositions payload
Uses common paging.
MakerPositions returns PositionInfo[], the same row takers get, with token symbols:
{
"type": "MakerPositions",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000011",
"positions": [
{
"revision": {
"slot": 250000000,
"transaction_index": 12,
"instruction_index": 1
},
"pda": "75NqraLLofiLUpNQg2wUPG6CJpxcaGEZUwuNrnAgvcTP",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"underlying_symbol": "SOL",
"underlying_decimals": 9,
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"quote_symbol": "USDC",
"quote_decimals": 6,
"terms": {
"type": "covered_call",
"strike": "160000000000"
},
"side": "sell",
"state": "funded",
"quantity": "1000000000",
"price": "5000000000",
"total_premium": "4975000",
"created_at": 1710000042,
"expiry_ts": 1710600000,
"underlying_price": { "type": "available", "price": "151000000000", "published_at": 1710000040 }
},
{
"revision": {
"slot": 250900000,
"transaction_index": 3,
"instruction_index": 0
},
"pda": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
"market_pda": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"underlying_mint": "So11111111111111111111111111111111111111112",
"underlying_symbol": "SOL",
"underlying_decimals": 9,
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"quote_symbol": "USDC",
"quote_decimals": 6,
"terms": {
"type": "call_spread",
"lower_strike": "100000000000",
"upper_strike": "120000000000"
},
"side": "sell",
"state": "settled",
"settlement": {
"type": "cash",
"settlement_price": "110000000000",
"holder_payoff": "10000000",
"writer_return": "10000000"
},
"quantity": "1000000000",
"price": "5000000000",
"total_premium": "4980000",
"created_at": 1709900000,
"expiry_ts": 1710000000,
"underlying_price": { "type": "unavailable" }
}
],
"unrenderable": [],
"next_cursor": null
}
}
Field semantics:
stateis a tag on the row.open,fundedandliquidatedrows carry no settlement fields. Asettledrow carriessettlement, a tagged union:{ "type": "physical", "settlement_price", "is_otm", "holder", "writer" }for covered calls and cash-secured puts, whereholderandwriterare each{ "collateral_atoms", "settlement_atoms" }: what that side received.is_otmis derived from the market settlement price and the strike; a settlement price equal to the strike is out of the money. The collateral mint is the underlying for a covered call and the quote for a cash-secured put; the settlement mint is the other one. Amounts are computed as the program does (the settlement leg of a covered call isfloor(strike * quantity * 10^qd / (1e9 * 10^ud))). In the money the holder receives the collateral and the writer the settlement. Out of the money the writer gets the collateral back, and the holder gets its settlement deposit back if it made one. The program moves the whole balance of the position's accounts, so a transfer is never below these amounts.{ "type": "cash", "settlement_price", "holder_payoff", "writer_return" }for spreads and cash puts, with both amounts in quote atoms.writer_returnincludes any donated collateral.
settlement_priceis 1e9-scaled.- A
terminal_pendingrow,{ "state": "terminal_pending", "slot", "outcome" }, is a position the chain has already settled or liquidated atslotwhile the server has not sealed that slot. It usually lasts under a second.outcomeis{ "type": "settled", "is_otm" }or{ "type": "liquidated" }. Show it, but do not count it: caps and balances follow the sealed state, and the sealed row replaces it. revisionis{ slot, transaction_index, instruction_index }of the last applied lifecycle event. See Position revisions.total_premiumis the net premium in quote atoms after the protocol fee. It is the authoritative money figure for the position. The wirepricealone does not give it.priceis the gross premium per 1 underlying unit (1e9 scale).underlying_symbol/quote_symbol/underlying_decimals/quote_decimalsare pre-resolved token metadata so the maker does not need a separateGetTokenslookup.underlying_price:{ type: "available", price, published_at }or{ type: "unavailable" }, the trusted oracle price of the underlying in the quote token (1e9) that the server prices RFQs with. Assets with trading sessions keep their last price and its timestamp while closed.unrenderablelists stored positions whose market projection is incomplete (a position waiting for its seal isterminal_pending, not unrenderable):{ pda, market, created_at, missing }, wheremissingnames the fields the projection could not supply. They count toward the page limit. Retrying does not repair them.- all amount fields are unsigned
u64decimal strings; timestamps are Unix seconds, as numbers.
Position revisions
Every full position row (PositionInfo in MakerPositions, MmSummary and PositionUpdated) carries revision. Compare (slot, transaction_index, instruction_index) lexicographically. Apply a row only when its revision is greater than the stored revision for the same pda. Rows with equal revisions describe the same state on every read path (PositionUpdated, GetMakerPositions, MmSummary), regardless of filters.
PositionUpdated is coalesced per pda to the newest revision. It is not a log with one message per transition.
Position state by product
| Product | States it can reach |
|---|---|
covered_call, cash_secured_put | open, funded, liquidated, settled (physical) |
call_spread, put_spread, cash_put | open, settled (cash) |
MyQuotes payload
Uses common paging.
{
"type": "MyQuotes",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000001",
"quotes": [
{
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"underlying_symbol": "SOL",
"underlying_decimals": 9,
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"quote_symbol": "USDC",
"quote_decimals": 6,
"terms": {
"type": "covered_call",
"strike": "160000000000"
},
"side": "sell",
"price": "5000000000",
"quantity": "1000000000",
"valid_until": 1710000120,
"state": {
"type": "active",
"rank": "best",
"rfq_version": 1
},
"created_at": 1710000010
}
],
"next_cursor": null
}
}
state.type | Fields | Meaning |
|---|---|---|
active | rank (best or outbid), rfq_version | In the active book. |
retained | rfq_version | Non-selectable quote: a locked non-winner or a frozen refresh quote. It may return on rollback/requote unless removed. |
awaiting_signature | rfq_version | Selected quote awaiting the taker signature. |
executing | rfq_version | Selected quote whose execution is unresolved. |
historical | status | History only; persisted projection, not live authority. |
Historical status is one of submitted, filled, cancelled, replaced, expired, lost. There is no top-level status or selected. Both scopes use the returned next_cursor.
{
"type": "GetMyQuotes",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000013",
"scope": {
"type": "history"
},
"limit": 200,
"cursor": {
"type": "start"
}
}
}
A History row uses the same identity/amount fields with, for example, "state": { "type": "historical", "status": "filled" }. Live and History never mix in one response.
GetOrderStatus / OrderStatus
{ "type": "GetOrderStatus", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000002", "order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a" } }
{ "type": "OrderStatus", "data": { "request_id": "a1b2c3d4-0000-4000-8000-000000000002", "order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a", "state": { "type": "pending" } } }
Available to the authenticated owner on /maker, /maker/data, /taker, and to the operator on /vault. Makers should use /maker/data to keep execution lookups off the quote connection. state is pending, confirmed (with position_pda), or unknown, encoded as a tagged object. See the shared execution lookup contract.
A lost ACK leaves the command outcome unknown. Keep unresolved orders in strategy state across reconnect; neither an empty Live response, a missing position, a timeout nor unknown proves nonexecution. Execution lookup failures return RequestError with the request ID.
MakerMarkets payload
Uses common paging.
{
"type": "MakerMarkets",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000012",
"markets": [
{
"products": [
"covered_call",
"call_spread"
],
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"is_finalized": false,
"underlying_symbol": "SOL",
"quote_symbol": "USDC"
}
],
"next_cursor": null
}
}
MmSummary payload
Uses common paging.
MmSummary pages positions, live quotes, markets, tokens and caps with one shared limit and cursor. See common paging.
Send GetMmSummary on /maker/data. Valid triggers are initial connect/auth,
reconnect, manual refresh, detected drift, and post-transaction reconciliation
when no owner-direct push is expected. Do not poll it. It costs one query token, but it is a
heavy read.
{
"type": "MmSummary",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000003",
"maker_pda": "HYe9CryCnQ3ZviCwoG8X7REFoSBK7HCjrhWWMpNtTah1",
"caps": {
"positions": {
"current": 5,
"limit": 100
},
"notional": [
{
"underlying_mint": "So11111111111111111111111111111111111111112",
"symbol": "SOL",
"current": "50000000000",
"limit": "200000000000"
}
],
"balances": [
{
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"decimals": 6,
"deposited": "1000000000",
"committed": "500000000",
"available": "500000000"
}
],
"quote_liabilities": [
{
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"current_liability": "20000000",
"policy": {
"type": "limited",
"max_liability": "100000000",
"headroom": "80000000"
}
}
]
},
"positions": [],
"active_quotes": [],
"markets": [],
"tokens": [],
"computed_at": 1710000042,
"unrenderable_positions": [],
"next_cursor": null
}
}
Field semantics:
maker_pda: on-chain maker account PDA (base58)caps: same shape as theMyCapsresponse (echoesrequest_idfromGetMmSummary)positions:PositionInfo[]— see MakerPositions payload. Positions are ordered newest first; follownext_cursorto continue the compound reply.active_quotes:MakerQuoteInfo[]— see MyQuotes payloadmarkets:MakerMarketInfo[]— see MakerMarkets payloadtokens:TokenInfo[]— seeTokenInfocomputed_at: server-side snapshot timestamp (Unix seconds)unrenderable_positions: positions the summary holds but cannot describe; same shape asMakerPositions.unrenderable
All balance values are in their respective token atomic units (use decimals from caps.balances to format).
ActiveRfqs payload
Uses common paging.
{
"type": "ActiveRfqs",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000005",
"rfqs": [
{
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"terms": {
"type": "covered_call",
"strike": "160000000000"
},
"side": "sell",
"quantity": "1000000000",
"expires_at": 1710000050,
"quotes_count": 3,
"best_price": {
"type": "quoted",
"price": "5500000000"
},
"order_options": [
{
"type": "covered_call",
"strike": "150000000000"
},
{
"type": "covered_call",
"strike": "160000000000"
}
]
}
],
"next_cursor": null
}
}
best_price is { "type": "none" } if no quotes have been submitted yet, otherwise { "type": "quoted", "price" }.
GetMyTrades (maker -> server)
Uses common paging.
{
"type": "GetMyTrades",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000014",
"limit": 50,
"cursor": {
"type": "start"
},
"market_pda": {
"type": "only",
"value": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi"
}
}
}
All four fields are required.
limit: page size in1..=200.cursor: the tagged cursor from common paging.market_pda: aQueryFilteron the market PDA.
MyTrades payload
Uses common paging.
{
"type": "MyTrades",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000014",
"trades": [
{
"id": "7c2e9a41-6b3d-4f58-9e1a-0d4b6f8a2c35",
"rfq_id": "8f3e7e6a-4f5c-4b7c-9f1d-1f2a3b4c5d6e",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"underlying_symbol": "SOL",
"underlying_decimals": 9,
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"quote_symbol": "USDC",
"quote_decimals": 6,
"terms": {
"type": "covered_call",
"strike": "160000000000"
},
"side": "sell",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"quantity": "1000000000",
"price": "5000000000",
"transaction_signature": "<base58 transaction signature>",
"position": {
"type": "confirmed",
"position_pda": "75NqraLLofiLUpNQg2wUPG6CJpxcaGEZUwuNrnAgvcTP"
},
"confirmed_at": 1710000042
}
],
"next_cursor": null
}
}
Field semantics:
price: gross premium per 1 underlying unit (1e9 scale)confirmed_at: Unix timestamp seconds when the trade was confirmed on-chaintransaction_signatureis always present;positionis{ "type": "confirmed", "position_pda" }or{ "type": "pending" }
MyTrades returns confirmed trades only — in-flight orders are visible via GetOrderStatus and the order push flow, not here. The cursor is therefore stable.
TokenCaps payload
Uses common paging.
Platform-level OI and notional caps. Full schema (fields, unlimited semantics, include_markets behavior): Capacity limits.
MyCaps payload
Uses common paging.
Per-maker position count, notional, balance and quote-liability caps. Full schema (fields, decimals rendering, unlimited semantics): Capacity limits.
CheckQuote / QuoteCheck
Dry run of the cap checks a Quote of quantity at price on market_pda (the market PDA) would face. Allowed on /maker, /maker/data and /vault. Nothing is reserved: a passing check is advice, not a hold. It checks spread collateral C against the quote-liability caps as well as premium capacity.
{
"type": "CheckQuote",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000015",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"terms": { "type": "call_spread", "lower_strike": "100000000000", "upper_strike": "120000000000" },
"side": "sell",
"quantity": "1000000000",
"price": "5000000000"
}
}
{
"type": "QuoteCheck",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000015",
"verdict": { "type": "rejected", "cap_detail": { "maker_position_cap_exceeded": { "current": 10, "limit": 10 } } }
}
}
verdict is { "type": "admissible" } or { "type": "rejected", "cap_detail": CapError }. quantity is in underlying base units; price is the gross price per underlying unit scaled by 1e9, as on Quote. cap_detail is the CapError a QuoteRejected would carry. "cap_detail": "caps_unavailable" means retry, not a cap. An unknown market_pda returns an uncorrelated Error with Generic code market_not_found.
Subscriptions payload
Uses common paging.
{
"type": "Subscriptions",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000004",
"channels": [
"rfqs",
"chain_events"
],
"underlying_mints": [],
"quote_mints": [],
"next_cursor": null
}
}
An empty mint list means that dimension is unfiltered; filtered lists contain base58 mint addresses. The response does not include products.
Broadcast events
Received when subscribed to the corresponding channel.
TradeExecuted (channel: trades)
{
"type": "TradeExecuted",
"data": {
"trade": {
"id": "7c2e9a41-6b3d-4f58-9e1a-0d4b6f8a2c35",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"quantity": "1000000000",
"price": "5000000000",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"maker_pda": "HYe9CryCnQ3ZviCwoG8X7REFoSBK7HCjrhWWMpNtTah1",
"transaction_signature": "<base58 transaction signature>",
"executed_at": 1710000042
}
}
}
TradeExecuted is a live hint: it can be lost, delayed or repeated. Merge it with GetMyTrades by trade.id. Do not derive correctness from event counts.
StatsUpdate (channel: stats)
{
"type": "StatsUpdate",
"data": {
"stats": {
"usd": {
"type": "available",
"notional_24h": "1500.00",
"premium_24h": "49.00",
"priced_trades_24h": 149
},
"total_volume_24h": "1000000",
"total_trades_24h": 150,
"spread_trades_24h": 12,
"total_price_24h": "500000",
"active_markets": 12,
"active_makers": 5,
"active_rfqs": 3
}
}
}
stats.usd contains exact decimal USD strings: underlying notional and gross
premium. It is null when no USD valuation is available. Only confirmed orders with a captured oracle valuation contribute;
priced_trades_24h exposes coverage against total_trades_24h. Volume and price aggregates for covered calls and cash-secured puts exclude spreads; spread trades are counted in spread_trades_24h. The numeric volume/price aggregates are not dollars and can retain
the last representable value after overflow; prefer the USD object.
PositionUpdated (owner-only push)
PositionUpdated is delivered directly to the session of the maker that owns the position. It is never broadcast and needs no subscription (there is no positions channel). It carries the full position row and the update type. See Protocol Flow.
{
"type": "PositionUpdated",
"data": {
"position": {
"revision": {
"slot": 250000000,
"transaction_index": 12,
"instruction_index": 1
},
"pda": "75NqraLLofiLUpNQg2wUPG6CJpxcaGEZUwuNrnAgvcTP",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"underlying_symbol": "SOL",
"underlying_decimals": 9,
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"quote_symbol": "USDC",
"quote_decimals": 6,
"terms": {
"type": "covered_call",
"strike": "160000000000"
},
"side": "sell",
"state": "funded",
"quantity": "1000000000",
"price": "5000000000",
"total_premium": "4975000",
"created_at": 1710000042,
"expiry_ts": 1710600000,
"underlying_price": {
"type": "available",
"price": "151000000000",
"published_at": 1710000040
}
},
"update_type": "funded"
}
}
update_type follows the row's state: open gives created, and funded, liquidated and settled map to the same names. Spreads and cash puts only produce created and settled. Apply the row only if its revision is newer than the stored one for the same pda. The row has no symbol fields. The push has no caps data; caps arrive in MakerCapsUpdated.
MakerCapsUpdated (owner-only push)
Sent to the owner's sessions when the maker's capacity changes without a position event: a settled or liquidated position released capacity, or an administrator changed a limit.
{
"type": "MakerCapsUpdated",
"data": {
"caps_snapshot": {
"positions": { "current": 6, "limit": 100 },
"notional": [
{
"underlying_mint": "So11111111111111111111111111111111111111112",
"symbol": "SOL",
"current": "51000000000",
"limit": "200000000000"
}
],
"balances": [
{
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"symbol": "USDC",
"decimals": 6,
"deposited": "1000000000",
"committed": "550000000",
"available": "450000000"
}
],
"quote_liabilities": []
},
"reason": "lifecycle"
}
}
reason is lifecycle or policy. caps_snapshot has the shape of the caps portion of MmSummary, without request_id. Use it to keep local caps in sync without calling GetMyCaps.
MarketCreated (channel: markets)
{
"type": "MarketCreated",
"data": {
"pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"products": [
"covered_call",
"call_spread"
],
"status": "active",
"settlement": {
"type": "pending"
}
}
}
MarketFinalized (channel: markets)
{
"type": "MarketFinalized",
"data": {
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"settlement_price": "160000000000"
}
}
ChainEvent (channel: chain_events)
ChainEvent is an internally tagged enum. The event_type field inside data indicates the variant. Event-specific fields are flat alongside event_type (not nested in a sub-data object).
{
"type": "ChainEvent",
"data": {
"event_type": "PositionOpened",
"signature": "<base58 transaction signature>",
"instruction_index": 0,
"slot": 250000000,
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"maker_pda": "HYe9CryCnQ3ZviCwoG8X7REFoSBK7HCjrhWWMpNtTah1",
"taker_owner": "5DNHbugre3SXXogpZroA5SEsENdAd69AfNK5Z7ZCWr84",
"terms": { "type": "covered_call", "strike": "160000000000" },
"side": "sell",
"quantity": "1000000000",
"price": "5000000000",
"order_id": "0x9d1c2a6a0c2f5e7d9b4d8d8f2a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a"
}
}
Variants:
event_type | Additional fields |
|---|---|
PositionOpened | market_pda, maker_pda, taker_owner, terms, side, quantity, price, order_id |
MarketCreated | market_pda, underlying_mint, quote_mint, expiry_ts, is_put |
MarketFinalized | market_pda, settlement_price |
MakerRegistered | maker_owner, maker_pda, quote_signing |
PositionSettled | position_pda |
PositionLiquidated | position_pda |
All variants require signature (tx signature, base58), instruction_index (instruction coordinate) and slot (Solana slot number). Deduplicate by (signature, instruction_index); one transaction may contain multiple events.
Delivery and recovery
When your outbound queue is full, a critical message is dropped and the server closes the connection (4002 slow_consumer), so its loss always surfaces as a disconnect. Best-effort broadcasts are dropped silently. For /maker the critical set is RfqBroadcast, the quote lifecycle, QuoteRefreshRequested, MarketCreated, MarketFinalized, VaultCatalogChanged, VaultProjectionAdvanced, and every message addressed to your session alone (responses, PositionUpdated, MakerCapsUpdated). ChainEvent, StatsUpdate, RfqSkipped and IndicativePricesRequest broadcasts are best-effort. Owner-direct TradeExecuted uses addressed delivery and closes the affected session on queue overflow. The full table is in WebSocket common.
The wire has no replay cursor or stream sequence number. The server does not replay events missed during a disconnect. Do not infer execution from absent events. SDK receiver sequence gaps are local delivery gaps, distinct from the wire.
Recovery after reconnect
After every reconnect, authenticate (ResumeAuth or the full challenge) and run these steps.
Quote plane, /maker. The managed Rust SDK does this before it reports Ready:
- Send
GetSubscriptions. - If the server holds channels the client does not want, send
Unsubscribefor them. Wait forUnsubscribeAck. - Send
Subscribewith the desired products, channels and both mint lists (empty lists included). Wait forSubscribeAck. This replaces any mint scope that a resumed session restored. - Send
GetActiveRfqsandGetMyQuotes { scope: live }.ActiveRfqssupplies each RFQ's taker and market PDA for the quote preimage. The SDK follows every live quote page before reporting readiness.
Data plane, /maker/data:
- Send
GetMmSummary. Owner pushes start after it is answered.
These reads span live server state and the database. They are not an atomic snapshot. Then, in the strategy:
- Rebuild the live position book. Apply revisions from
MmSummary. If it has a continuation, read allGetMakerPositionspages withstatus: ["open", "funded"]. Historical positions remain an explicit read. Preserve newer push revisions received during paging. - Book money from position rows.
total_premiumis the net premium the taker received. The maker's cost is the gross premium,scaled_quote_amount(price, quantity), and the fee is that cost minustotal_premium.QuoteFilledhas no fee or net field. - Reconcile unfinished orders. For each local order with no terminal outcome that is not in the Live set, send
GetOrderStatusand wait for its response before sending the next. Stop at the firstRequestError. Fix the cause and restart the loop from that order.pendingandunknownkeep the order as an open obligation.confirmedgives theposition_pda; book it from the position row. - Drop signed quotes from before the disconnect. Sign new ones with a fresh
valid_until,nonceandorder_id.
An empty Live set, a timeout and unknown do not prove that an order did not execute.
TradeExecuted is a live hint, not authoritative. The DB-backed reads (GetMmSummary, GetMakerPositions, GetMyTrades) are the recovery authority. On any doubt, re-read rather than trusting the last live push. Also reconcile via GetMmSummary after your own transactions and when you detect drift, not on a timer.
Indicative pricing workflow
Indicative pricing covers covered calls and cash-secured puts only. Each request names one taker side: sell asks what you pay a taker who writes the option, buy what you charge a taker who buys it. Sell requests reach only sessions subscribed to rfqs, buy requests only sessions subscribed to taker_buy_rfqs; a session subscribed to neither receives none. Echo side in the response; a response without it does not parse, and repeated parse errors close the connection. The server publishes the median of maker prices per strike.
Request from taker-side cache (server -> maker)
{
"type": "IndicativePricesRequest",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000021",
"market_descriptor": {
"chain_id": 0,
"program_id": "33Ezs5eoa16QyPW8wifnyz2nCyMEcq2crqkVBNjnTE8U",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"underlying_mint": "So11111111111111111111111111111111111111112",
"quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"expiry_ts": 1710600000,
"is_put": false,
"collateral_mint": "So11111111111111111111111111111111111111112",
"settlement_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
},
"position_type": "covered_call",
"side": "sell",
"strikes": ["150000000000", "160000000000"]
}
}
Response (maker -> server)
{
"type": "IndicativePricesResponse",
"data": {
"request_id": "a1b2c3d4-0000-4000-8000-000000000021",
"market_pda": "4vJ9JU1bJJE96FWSJKvHsmmFADCg4gpZQff4P3bkLKi",
"position_type": "covered_call",
"side": "sell",
"prices": [{ "strike": "150000000000", "price": "4200000000" }]
}
}
Indicative rules
- Timing. The server asks every market about every 30 seconds, once per side. A
request_idstays open for 5 seconds; a response after that, or for an unknownrequest_id, is dropped without an error. - One answer per request. Only your first response to a
request_idcounts. Each round replaces the previous one: the published price per strike is the median of the answers that round. - Partial and empty answers. Price any subset of the requested strikes; strikes not in the request are ignored. An empty
pricesmeans you abstain this round; it does not clear other makers' prices. A strike nobody prices showsprice: { "type": "none" }to takers. - Strikes. A request carries the strike ladder the taker sees, usually 4 to 10 strikes, at most 1000.
- Price. Per one unit of the underlying,
1e9-scaled, gross like aQuoteprice; there is no size. The server applies the protocol fee when it shows the price to takers. - Freshness. Takers see a market's indicatives as
stale60 seconds after the last round any maker answered. - Rate limits. A response the server accepts does not count against any rate limit. A late or unknown one counts against the session message bucket, which for a registered maker rejects excess frames instead of closing the connection.
- Commitment. Indicatives are not binding and never become orders.
Errors
Two error message types: Error (connection-level) and RequestError (request-correlated).
See WS common conventions "Error format" for the envelope.
Parsing rule for maker integrations:
- Handle
RequestErrorwhere you passrequest_id(e.g. query requests,Subscribe). - Handle
Errorfor connection-level failures (auth, WS errors, unknown request). - For both, switch on
ServerError.type. - If
type == "Generic", switch ondata.code. - The set of error codes is closed. A frame whose code is not in the catalog does not match the 1.0.0 schema; treat it as a version mismatch.
Every typed ServerError variant and its data is in the ServerError catalog.
Quote-specific validation failures are sent as QuoteRejected with a typed reason. See the QuoteRejected section above for its variants.
Generic codes are listed, with their frames, in the WS error code catalog; match on code. The codes introduced by products and queries are:
| Code | Meaning |
|---|---|
unsupported_protocol_version | Hello.protocol_version is not 1.0.0; the server closes with 4006 |
invalid_products | Subscribe.products is empty |
invalid_limit | A page limit is outside the range of its request |
product_not_allowed | The pair's policy does not allow the RFQ's product |
taker_buy_unsupported | RfqRequest with side: "buy" on /vault |
spread_invalid_strikes | Invalid spread strikes |
spread_tick_violation | A strike is off the underlying mint's strike tick |
spread_premium_invalid | Price or gross premium outside 0 < price < width, 0 < gross < C |
quote_identity_mismatch | Quote product, side or spread terms differ from the RFQ |
missing_tick_for_underlying_mint | The underlying mint has no strike tick |
Operational handling recommendations:
- for
rate_limited: the error carries no retry time. Wait at least1 / per_secondofWelcome.rate_limits.liquidity_provider, then retry with exponential backoff and jitter. An authenticated maker connection stays open; before authentication theconnectionbucket closes it with4003. See Rate limits and admission. - for
session_replaced: another connection replaced this session — stop; do not auto-reconnect in a loop. - for
parse_error: treat as payload bug and stop retries until fixed. - for
too_many_parse_errors: reconnect only after fixing payload/codec mismatch. - for
unsupported_protocol_version: upgrade the client. Retrying does not help.
Enums reference
RfqCloseReason
| Value | Meaning |
|---|---|
expired | RFQ expired without fill |
taker_cancelled | Taker cancelled the RFQ |
filled | RFQ was filled on-chain |
market_expired | The underlying market expired |
no_eligible_makers | No maker could receive the RFQ; sent to the taker only |
server_shutdown | A graceful server stop closed the RFQ before its order reached the keeper; your quote reports cancelled |
QuoteFinalStatus (in RfqClosed.your_quote.status)
| Value | Meaning |
|---|---|
expired | Quote expired before selection |
outbid | Another maker won |
cancelled | Quote was cancelled |
filled | This quote was selected and filled |
QuoteCancelReason (in QuoteCancelled.reason)
| Value | Meaning |
|---|---|
requested | Maker requested cancellation |
risk_check | Server-side risk check triggered |
rfq_accepted | RFQ accepted another quote |
maker_disconnected | Session had on_disconnect: "cancel_quotes" and disconnected |
QuoteExpiryReason (in QuoteRefreshRequested.reason and QuoteExpired.reason)
| Value | Meaning |
|---|---|
expired | The quote's validity ended |
expiring_soon | The quote reached its refresh point before the settlement-buffer cutoff |
RfqAvailableAgainReason
| Value | Meaning |
|---|---|
signature_timeout | Taker did not sign in time |
tx_failed | On-chain transaction failed |
tx_build_failed | Transaction could not be built |
When reason = "tx_build_failed", a corresponding Error or RequestError is also sent to
the taker with generic.code = "tx_build_failed" and a message field
describing what went wrong.
OnDisconnect (in Hello)
| Value | Meaning |
|---|---|
cancel_quotes | The server removes the connection's active and retained non-winning quotes on disconnect |
keep_quotes | Resting quotes stay live after disconnect |
TakerSide (side)
| Value | Meaning |
|---|---|
sell | The taker writes the option; the maker or vault holds it. |
buy | The taker buys; the maker or vault writes it. |
PositionStatus (in GetMakerPositions.status)
Uses common paging.
| Value | Meaning |
|---|---|
open | Position created on-chain but maker has not yet escrowed settlement asset. |
funded | The holder called DepositFundsToPosition. Settlement asset is escrowed; WithdrawFundsFromPosition before expiry returns it and the state to open. |
liquidated | Unfunded ITM position seized by a third-party liquidator. |
settled | Position settled at expiry; assets distributed per ITM/OTM outcome, or paid in cash. |
Position status is a lowercase snake_case string on the wire. funded and liquidated apply to covered calls and cash-secured puts only.
PositionState (on position rows)
state | Extra fields |
|---|---|
open | none |
funded | none |
liquidated | none |
settled | settlement: physical { settlement_price, is_otm, holder, writer } (each side { collateral_atoms, settlement_atoms }), not_exercised { settlement_price } or cash { settlement_price, holder_payoff, writer_return } |
PositionUpdateType (in PositionUpdated)
| Value | Row state |
|---|---|
created | open. Position opened on-chain. |
funded | funded. The holder called DepositFundsToPosition. |
liquidated | liquidated. Unfunded ITM position liquidated by a third party. |
settled | settled. Position settled at expiry. |
Physical transitions: created -> funded -> settled. An unfunded position (created) goes to settled if OTM and to liquidated if ITM. A funded position cannot be liquidated. Cash products go created -> settled.
See Protocol Flow for the physical scenarios.
RateLimitReason (in typed RateLimit error)
| Value | Meaning |
|---|---|
too_many_active_rfqs_total | Platform-wide RFQ limit reached |
too_many_active_rfqs_per_taker | Per-taker active RFQ limit reached |
too_many_quotes_per_rfq | Max quotes per RFQ reached |
too_many_failed_orders_per_rfq | AcceptQuote refused: too many failed orders on this RFQ are still unresolved. Create a new RFQ |
too_many_sessions_per_user | Too many concurrent sessions |
CapError
Used in the typed cap error, QuoteRejected.reason, RfqSkipped.cap_detail and QuoteCheck.verdict.
Full variant catalog (token_oi_cap_exceeded, market_oi_cap_exceeded, maker_position_cap_exceeded, maker_notional_cap_exceeded, maker_insufficient_balance, quote_notional_cap_exceeded, maker_quote_notional_cap_exceeded, quote_liability_cap_exceeded, maker_quote_liability_cap_exceeded, caps_unavailable) with fields and rejection semantics: Capacity limits.
Quirks and constraints
Details that are easy to miss in the schemas.
Multiple quotes per RFQ
When RfqBroadcast.order_options lists several strikes of a covered call or cash-secured put, you can quote each strike independently — each quote needs a distinct order_id and nonce. Submitting a new quote on the same (rfq_id, terms) pair replaces your prior quote on that pair; QuoteAcknowledged.replaced (replaced { order_id }) tells you which one was displaced. Across all makers, max_quotes_per_rfq from GET /api/v1/venue bounds the quotes per RFQ.
order_options validation
For a covered call or cash-secured put, the quote's strike must be one the RFQ offers. Anything else returns invalid_strike. A spread or cash-put quote must carry the RFQ's terms exactly, or it returns quote_identity_mismatch.
Subscribe / Unsubscribe
Both require a request_id. The ack carries the diff of channels added or removed by this call, not the full subscription. For the full set, query GetSubscriptions.
Sessions and disconnects
One active quote connection per maker pubkey. A new quote connection replaces the previous quote connection; the separate data connection is for reads. On replacement, the displaced session gets Error { generic.code = "session_replaced" } and is closed.
The client chooses cancel-on-disconnect with Hello.on_disconnect. The managed quote SDK examples use cancel_quotes. Selected and executing quotes remain obligations. Reconcile GetMyQuotes { scope: live } and execution status after reconnect.
A resumed maker auth session restores server-side routing and mint scope. After fresh auth, establish subscriptions again. The managed SDK restores its own desired target after either path by sending Subscribe with both mint lists, including empty lists.
Max message size
32 KB inbound. A larger frame closes the connection without an error frame.
Nonce
nonce is a u64 baked into the order-id preimage. The server doesn't enforce uniqueness on the nonce itself — it's validated only as part of sha256(preimage) matching the submitted order_id.
order_id hex
Accepted with or without 0x prefix; case-insensitive. Must decode to exactly 32 bytes.
Message ordering after auth
After AuthSuccess, the server sends Snapshot before any broadcast events. You can safely initialise state from Snapshot before processing push messages.
is_taker_buy
In the order-id preimage, is_taker_buy is 0 for side sell and 1 for side buy.
gross_price in preimage
The gross_price at preimage offset 94 is the same value as price in the Quote message — gross premium per one underlying unit, 1e9 scale. total_premium in position data is the net amount after the protocol fee, not derivable from the wire price alone. The fee formula is under Cash settlement and fees.