Acta WS Common Conventions

Message envelope

All WS messages use:

{ "type": "MessageType", "data": { ... } }

Unit variants have no data field, for example:

{ "type": "Logout" }

Encodings and units

Numbers

One rule covers the WebSocket protocol and the HTTP API:

  • Token amounts are JSON decimal strings. Every amount in token atoms or 1e9-scaled integers: prices, premiums, strikes (lower_strike, upper_strike), quantities, collateral, balances, payoffs and returns, fees in atoms, shares, share prices, equity and TVL values (value_1e9), deposit and withdrawal amounts, notionals, intrinsic values, caps and size rules. The quote nonce is a full-range u64 and is a decimal string too. A decimal string is canonical: ASCII digits, no sign, no leading zero ("0", "150000000000").
  • Everything else is a JSON number: Unix timestamps (*_ts, *_at, *_at_ms, valid_until, expires_at), slots, counts, versions and generations, decimals, basis points, durations in seconds, rate limits, page limits, and ratios such as utilization or apr. Every integer number is below 2^53, so JSON.parse reads it exactly.

The server rejects an amount sent as a number and a number sent as a string. A field has the same encoding in every message and on both transports.

FieldFormat
Pubkeysbase58
Signaturesbase58 (64 bytes)
order_id64-char hex (optional 0x prefix)
pricedecimal string, gross premium per 1 underlying unit, 1e9 scale
total_premiumdecimal string, net premium amount in quote token atomic units
strike, lower_strike, upper_strikedecimal string, quote per 1 underlying unit, 1e9 scale
quantitydecimal string, underlying atomic units
size_rulemin_size, max_size, step: decimal strings in underlying atomic units; always tied to underlying_mint
strike_tickdecimal string, strike ladder spacing for an underlying, 1e9 scale
noncedecimal string, full-range u64
Timestampsnumber, Unix seconds
server_now_at_msnumber, Unix milliseconds

price and strike are always 1e9 fixed-point per 1 underlying unit, independent of mint decimals.

Address fields

Address fields are named by what they hold:

ValueFieldNotes
Market PDAmarket_pdaEvery message and query filter that references a market by address
Market descriptor (object)market_descriptorRfqBroadcast, IndicativePricesRequest, MarketDescriptorInfo; the address is market_descriptor.market_pda
Maker owner walletmaker_ownerQuote messages (QuoteReceived, QuotesUpdate, AcceptQuote, RfqClosed.winner) and MakerRegistered
Maker PDAmaker_pdaTrades and chain events: TradeInfo, PositionOpened, MakerRegistered, MmSummary, AuthSuccess.role
Vault PDAvault_pdaVault messages and every HTTP vault route
Counterparty walletcounterparty_ownerHTTP vault positions
Position PDAposition_pdaQuoteFilled, OrderConfirmed, PositionSettled, PositionLiquidated
Mintunderlying_mint, quote_mintMarketInfo, positions, caps, filters
Own address of a recordpdaMarketInfo, PositionInfo

Derive a maker PDA from its owner with the program's maker seed rather than comparing the two.

Names follow one rule set:

SuffixHolds
_pdaA program-derived account address
_ownerThe wallet behind an account, as opposed to its PDA
_mintA token mint
_atA Unix time in seconds
_at_msA Unix time in milliseconds
_tsA market expiry in Unix seconds, named as in the program: expiry_ts, min_expiry_ts, max_expiry_ts, active_expiry_ts
_secondsA duration in seconds
_atomsAn amount in a mint's base units

A record's own address is pda (MarketInfo.pda, PositionInfo.pda). Two time fields keep their established names: valid_until (Unix seconds, as in the order preimage) and HTTP as_of (Unix seconds).

Reference data

Tokens and markets come from one server snapshot, shared by WS (GetTokens, GetMarkets, GetMarketDescriptors, GetExpiries, Snapshot.markets) and HTTP (/api/v1/tokens, /api/v1/markets, see HTTP API). WS discovery always answers from the active set: markets that are not finalized, not disabled and before their trading cutoff. For closed and finalized markets use GET /api/v1/markets?active=false.

TokenInfo

One object per mint, on both transports. role is a tagged union.

type TokenInfo = {
  mint: string;
  symbol: string;
  decimals: number;
  oracle_feed_ids: string[];       // Pyth feed ids, hex without 0x; [] when none is known
  role:
    | { type: "quote" }
    | {
        type: "underlying";
        size_rule: {               // decimal strings, underlying atomic units
          min_size: string;
          max_size: string;
          step: string;
        };
        strike_tick: string;       // decimal string, strike ladder spacing, 1e9 scale
        quote_mints: string[];     // quote mints of its active markets
      };
  schedule:                        // the price feed schedule
    | { type: "unknown" }
    | { type: "continuous" }
    | { type: "pyth"; spec: string };  // Pyth TZ;Mon,..,Sun;MMDD/spec,...
  session:                         // whether the feed trades now (Unix seconds)
    | { type: "continuous" }
    | { type: "open"; closes_at: number }
    | { type: "closed"; opens_at: number }
    | { type: "closed_indefinitely" }
    | { type: "unknown" };
  protocol_fees:                   // fees of markets quoted in this token
    | { type: "not_quote_token" }
    | { type: "unavailable" }      // a quote token whose fee config is not projected yet; not zero
    | { type: "quote"; premium_bps: number; volume_bps: number };
};

While a market is closed the oracle keeps its last price; see /api/v1/tokens for the schedule format.

A valid quantity satisfies min_size <= quantity <= max_size and (quantity - min_size) % step == 0. Only tokens of active markets are listed.

MarketInfo

Used by Snapshot.markets, Markets and HTTP /api/v1/markets. Markets name tokens by mint.

type MarketInfo = {
  pda: string;
  underlying_mint: string;
  quote_mint: string;
  expiry_ts: number;
  is_put: boolean;
  products: Product[];               // non-empty; see below
  status: "active" | "closed" | "finalized";
  settlement: { type: "pending" } | { type: "fixed"; price: string }; // price: decimal string, 1e9 scale
};

type Product =
  | "covered_call" | "cash_secured_put" | "call_spread" | "put_spread" | "cash_put";

products lists the products enabled for the pair that fit the market's side. A put market (is_put: true) lists a subset of cash_secured_put, put_spread and cash_put. A call market lists a subset of covered_call and call_spread. A market with no product on its side is not listed.

WS responses (Snapshot, Markets) contain only active markets.

ReferenceChanged

Pushed to every authenticated maker (quote and /maker/data), taker and vault operator session, without a subscription, when the token list or the market list changes, including a market crossing its trading cutoff or expiry. The server checks for changes every second.

{
  "type": "ReferenceChanged",
  "data": { "tokens_etag": "\"3f2a...\"", "markets_etag": "\"9b1c...\"" }
}

The ETags are the HTTP ETag values of /api/v1/tokens and of unfiltered /api/v1/markets?active=false. On receipt, re-read what you cache (GetTokens / GetMarketDescriptors on WS, or the HTTP routes with If-None-Match). Vault sessions on /vault re-read the HTTP routes.

VaultCatalogChanged

Sent on the vaults channel to maker and taker sessions after a vault is created, re-delegated (RotateVaultDelegate) or closed. Disabling a delegate (DisableVaultDelegate) does not send it. It carries only the vault address; re-list vaults (GET /api/v1/vaults) to pick up the change. /vault operator sessions do not receive it.

It is a hint, not a feed. It is never replayed: if your outbound queue is full the message is dropped and the server closes the connection, and nothing sent while you were disconnected is redelivered. Re-list vaults after every connect and reconnect as well as on this message.

{ "type": "VaultCatalogChanged", "data": { "vault_pda": "VaultPdaBase58" } }

VaultProjectionAdvanced

Sent on the vaults channel after the server's projection of a vault advances by a committed on-chain vault event. /maker quote sessions and taker sessions subscribed to vaults receive it for every vault; a /vault operator session receives it only for its own vault. It is a change notification, not the new state: reload GET /api/v1/vaults/{pda}. version increases with each projected vault event; if you see a gap, or after a reconnect, reload the vault rather than repairing local state. Delivery follows the same drop-and-disconnect rule as VaultCatalogChanged.

{
  "type": "VaultProjectionAdvanced",
  "data": {
    "vault_pda": "VaultPdaBase58",
    "version": 42,
    "slot": 312345678,
    "transaction_index": 3,
    "signature": "TxSignatureBase58",
    "event_index": 1
  }
}

slot, transaction_index, signature and event_index locate the vault event that produced version.

Quantity and collateral by product

quantity on the wire is always in underlying atomic units, regardless of position type. The products differ in what the collateral is:

Covered call — user deposits underlying (e.g. SOL). quantity maps directly to the deposit: quantity = userInput * 10^underlying_decimals.

Cash-secured put — user deposits quote (e.g. USDC). The collateral is floor(strike * quantity * 10^quote_decimals / (1e9 * 10^underlying_decimals)), in quote atoms. To turn a budget in quote atoms into a quantity, round down, then snap to the size rule:

raw      = floor(quoteAtoms * 1e9 * 10^underlying_decimals / (strike * 10^quote_decimals))
quantity = min_size + floor((raw - min_size) / step) * step

Stop if raw < min_size, and cap quantity at max_size. Rounding up would need more collateral than the budget, and a quantity off the step is rejected with invalid_quantity_size_rule. For 100 USDC at strike 136 with 9 and 6 decimals, min_size 10000000 and step 10000000: raw is 735294117, quantity is 730000000 and the collateral is 99280000.

And to display the deposit back in quote terms:

quoteAmount = quantity * strike / 1e9 / 10^underlying_decimals

underlying_decimals comes from MarketDescriptorInfo.

Call spread, put spread, cash put — collateral is quote. Spreads and cash puts settle in cash in the quote mint. The width is upper_strike - lower_strike for a spread and strike for a cash put (a put spread with legs (0, strike)). The collateral in quote atoms is ceil(width * quantity * 10^quote_decimals / (1e9 * 10^underlying_decimals)). The gross price G per underlying unit satisfies 0 < G < width. To size from a quote budget, use the formulas above with width in place of strike.

Size rule display for CSP

size_rule values (min_size, max_size, step) are in underlying atomic units. To show constraints in quote terms for a CSP UI, apply the same conversion:

min_quote = min_size * strike / 1e9 / 10^underlying_decimals
max_quote = max_size * strike / 1e9 / 10^underlying_decimals
step_quote = step    * strike / 1e9 / 10^underlying_decimals

Example: SOL/USDC CSP, strike $90 (90e9), size_rule = {min: 1e9, max: 10e9, step: 1e8}:

Wire (SOL lamports)Display (USDC)
min_size = 1,000,000,00090 USDC
max_size = 10,000,000,000900 USDC
step = 100,000,0009 USDC

The TS SDK provides helpers for these conversions: quoteAmountToQuantity, quantityToQuoteAmount, sizeRuleInQuoteTerms (exported from @acta-markets/ts-sdk/ws). quoteAmountToQuantity takes whole quote tokens, rounds to the nearest atom and ignores the size rule, so snap its result before sending.

Time and clock skew

server_now_at_ms is present in:

  • Welcome.server_now_at_ms (required)
  • Pong.server_now_at_ms (required)

Snapshot does not include server_now_at_ms in current protocol.

Client estimate:

offset_ms = server_now_at_ms - local_time_ms
estimated_server_now_ms = local_time_ms + offset_ms

Use this estimate for expires_at, valid_until, and signature_deadline_at.

Authentication protocol

Signing algorithm

Ed25519. Signatures are 64 bytes, base58-encoded on the wire.

Challenge format

After the client sends Hello and receives Welcome, the server sends AuthRequest with a challenge field. The challenge is a multiline plaintext string. The format differs by role:

Taker challenge (includes Wallet: line):

Acta RFQ Authentication

Sign this message to authenticate your wallet.

Wallet: {base58_pubkey}
Nonce: {hex_encoded_32_random_bytes}
Issued At: {RFC3339_timestamp}

Maker challenge (no Wallet: line):

Acta RFQ Authentication

Sign this message to authenticate your wallet.

Nonce: {hex_encoded_32_random_bytes}
Issued At: {RFC3339_timestamp}

Makers do not need a Wallet: line. The server identifies the maker from AuthChallenge.pubkey, then looks up the registered signing key from the on-chain maker registry.

Vault operator challenge (/vault sessions): the taker challenge for the operator key, followed by \nVault: {vault_pda} with no trailing newline. Because the taker challenge already ends in \n, a blank line precedes the Vault: line:

Acta RFQ Authentication

Sign this message to authenticate your wallet.

Wallet: {operator_pubkey}
Nonce: {hex_encoded_32_random_bytes}
Issued At: {RFC3339_timestamp}

Vault: {vault_pda}

What to sign

Validate the entire challenge before invoking the signer. Require the exact text and blank lines above, a nonce of exactly 64 lowercase hex characters, a valid UTC timestamp in YYYY-MM-DDTHH:MM:SSZ format, and a final \n after that timestamp. A maker challenge must have no Wallet: line. A taker challenge must include that line and it must match the wallet being authenticated. A vault challenge must be a valid taker challenge for the operator key followed by exactly \nVault: {vault_pda} for the vault you requested, and nothing after it. Reject anything that is not one of these three formats for your role: extra lines, alternate domains, missing final newlines and arbitrary 32-byte strings.

After validation, sign the original UTF-8 bytes without normalization, additional prefix or hashing. The fixed text already supplies the authentication domain. Signing arbitrary endpoint text with the order key can authorize an order instead of authentication.

Rust SDK (acta-maker-sdk 0.10.0) and TS SDK (@acta-markets/ts-sdk 0.7.0) validate authentication messages before invoking signers in their managed clients. Raw Rust clients use validate_maker_auth_challenge, or validate_vault_auth_challenge(challenge, operator, vault) for a vault session; raw TS clients use validateAuthChallenge, which checks the grammar of the maker and taker formats and rejects the vault format, and assertVaultAuthChallenge(challenge, operator, vault) for a vault session. This does not establish endpoint trust or prevent relay of a genuine server challenge.

AuthChallenge (client -> server)

{
  "type": "AuthChallenge",
  "data": {
    "challenge": "Acta RFQ Authentication\n\nSign this message...",
    "signature": "3q7uQqYc3...base58sig",
    "pubkey": "PubkeyBase58"
  }
}

Maker: pubkey is the maker_owner pubkey registered on-chain. Sign the challenge with the maker's registered quote_signing key, the same key that signs quotes. The server looks up maker_owner and verifies the authentication signature against its quote_signing key.

Taker: pubkey is the taker's wallet pubkey (same as the Wallet: value in the challenge). The signature is verified directly against this key.

Auth constraints

  • Max auth attempts per connection: 3. The 4th attempt closes the connection.
  • Auth deadline after challenge issued: 15s.

Ping / Pong

{ "type": "Ping" }

Ping is a unit variant (no data field). Server responds with:

{
  "type": "Pong",
  "data": {
    "server_now_at_ms": 1710000000000
  }
}

Clients should send Ping every ~30s to avoid the 90s idle timeout.

Connection close codes

When the server closes a connection itself, the close frame carries one of these codes, with the name as the close reason. An Error or AuthError frame naming the cause usually precedes it. Other closes (blacklist, expired session, too many parse or auth errors, shutdown) send a close frame without a code; the preceding error frame says why.

CodeReasonCause
4000idle_timeoutNo traffic within the idle timeout
4001auth_timeoutAuthentication not completed within the auth deadline
4002slow_consumerA critical message could not be queued for you, or a socket write to you timed out
4003rate_limitedPer-connection or per-wallet message rate exceeded, or the inbound queue is full. See Rate limits and admission
4004session_replacedA newer connection authenticated as the same maker or taker session
4005hello_timeoutHello not received in time
4006unsupported_protocol_versionHello.protocol_version is not 1.0.0

A rejected WebSocket upgrade returns an HTTP status with the same JSON body as the HTTP API, {"error": "...", "code": "..."}: 403 origin_not_allowed, 429 rate_limited (too many connections from your IP), 503 too_many_connections, 503 server_overloaded, 503 server_shutting_down.

Rate limits and admission

Limits are server configuration; the values below are the defaults. Welcome.rate_limits carries the values in force on that connection, so a client can pace itself instead of hardcoding them. A limit is a token bucket: per_second tokens refill each second up to burst, or unlimited. The rows below apply until the connection authenticates as a maker or Vault operator; then the shared liquidity_provider bucket replaces all of them. Quote messages need that authentication, so they always spend from the shared bucket. A per-type limit rejects the message with rate_limited and keeps the connection. The per-connection and per-wallet message limits close it.

rate_limits fieldRow below
connectionMessage rate
walletWallet message rate; applies once the wallet authenticates
rfqs, queriesRFQ and query messages
liquidity_providerMaker and Vault operator budget: shared on /maker, /maker/data and /vault, not_applicable on /taker
LimitScopeDefaultOn exceed
Message rateEvery connection30/s, burst 60rate_limited error, then close 4003
Wallet message rateAll /taker and /vault connections of one authenticated wallet50/s, burst 100rate_limited error, then close 4003
RFQ messages (RfqRequest, AcceptQuote, CancelRfq, SwapQuote, SwapSubmit)Taker and Vault connections10/s, burst 20rate_limited error for that message; the connection stays open
Query messages (Get*, CheckQuote, subscription messages)Every connection20/s, burst 40rate_limited error for that message; the connection stays open
Quote messages (Quote, ReplaceQuote, BatchQuotes, CancelQuote, CancelAllQuotes)/maker and /vault before maker or operator authentication; a taker on /vault50/s, burst 100rate_limited for that message; the connection stays open. Not in Welcome.rate_limits; these messages are rejected anyway until the session can quote

Once a maker or Vault operator authenticates, one shared bucket replaces all of the limits above: every message spends from it, and an exceeded budget rejects the message with rate_limited: Quote and ReplaceQuote get QuoteRejected with reason rate_limited, BatchQuotes gets BatchQuotesAck with every result rejected the same way, and other messages get a rate_limited error. The default is 1000/s, burst 2000 for makers and 100/s, burst 200 for Vault operators. A maker connection stays open; a Vault connection whose messages keep being rejected for 10 seconds, with no break longer than a second, is closed with 4003.

BatchQuotes spends one token per quote in the batch, and SwapQuote spends five. Every other message spends one. A batch over max_batch_quotes is rejected before the shared bucket and is charged to the connection message rate instead.

Authentication messages (StartAuth, StartVaultAuth, AuthChallenge, ResumeAuth, and Hello on /maker and /maker/data) also spend from a per-IP bucket, 20/s, burst 40 by default. It is not in Welcome.rate_limits. An exceeded budget rejects the message with rate_limited and keeps the connection.

No rate-limit rejection says when to retry: rate_limited carries only code and message. A bucket gains one token every 1 / per_second seconds, so wait at least that long, using the message's bucket from Welcome.rate_limits, then back off further on repeated rejections. After a 4003 close, reconnect with backoff. The typed RateLimit error is a different case: its action depends on the RateLimitReason (see the ServerError catalog).

Admission limits cap work in flight across the server:

LimitDefaultOn exceed
Concurrent query handlers128server_overloaded for that message
Concurrent sponsored-transaction submissions64server_overloaded for that message
Connection command queue (messages received but not yet processed)n/auncorrelated server_overloaded, then close 4003

Other defaults:

SettingDefault
Max message size32 KiB
max_batch_quotes50
Parse error budget3 consecutive parse errors
Max connections, server total7500
Max connections per IP50
Max auth attempts3
Auth deadline15 s
Idle timeout90 s
Hello timeout5 s

Logout

{ "type": "Logout" }

Unit variant, no data field. Server responds with LogoutSuccess and closes the connection.

{ "type": "LogoutSuccess", "data": {} }

Fee model

The protocol charges a fee per trade. Fees are set per quote mint in basis points (bps). The on-chain config stores protocol_fee_bps_premium and protocol_fee_bps_volume; each quote token publishes its own as protocol_fees in GET /api/v1/tokens and WS Tokens.

  • price in the Quote message is the gross premium per 1 underlying unit (1e9 scale). The maker signs it, and it goes into the order id preimage as gross_price.
  • On chain, gross premium is scaled to quote-token atomic units. The premium fee is protocol_fee_bps_premium of the premium. The volume fee is protocol_fee_bps_volume of the exposure: the strike notional for physical products, the width notional for spreads and cash puts. The charged fee is min(premium_fee, volume_fee).
  • net_price in QuoteReceived is a Price for display only. The authoritative amount is the net premium after the fee and token-decimal scaling.
  • total_premium in position rows is the net premium in quote atoms after the protocol fee. It is the authoritative money figure. QuoteFilled carries no fee or net fields.
  • The fee does not change what the maker signs. The contract applies it when the position opens.

Auth messages

AuthSuccess

{
  "type": "AuthSuccess",
  "data": {
    "session_id": "uuid",
    "expires_at": 1710086400,
    "role": {
      "type": "maker",
      "maker_pda": "MakerPdaBase58"
    }
  }
}

expires_at wire contract:

  • Required JSON integer in Unix seconds, for makers and takers. This is the resume credential deadline, not the lifetime of the authenticated socket.
  • Used for session resume by both makers and takers.

role wire contract:

  • { "type": "maker", "maker_pda" } for authenticated makers, with the on-chain maker account PDA (base58).
  • { "type": "taker" } for every other session.

AuthError

{
  "type": "AuthError",
  "data": {
    "reason": "session_expired",
    "message": "Session expired"
  }
}

reason is a snake_case code from the WS error code catalog (frames marked AuthError). message is a required string.

Error format

Two error message types exist:

Error — connection-level errors

Sent when no request_id is available (the message had no request_id field, or the error occurred before routing):

{ "type": "Error", "data": { "type": "RfqNotFound" } }

data is a tagged ServerError variant (type + optional nested data).

Endpoint-policy violations use a typed error rather than closing the socket:

{
  "type": "Error",
  "data": {
    "type": "WrongEndpoint",
    "data": {
      "endpoint": "maker_data",
      "allowed_endpoints": ["maker"]
    }
  }
}

Endpoint values are maker, maker_data, taker, and vault.

RequestError: request-correlated errors

Sent when the server can correlate the failure to a specific client request. The request_id echoes the client's request_id from the originating message:

{
  "type": "RequestError",
  "data": {
    "request_id": "1e3a5c7e-9b0d-4f26-8a4c-6e8a0c2e4f93",
    "error": {
      "type": "RfqNotFound"
    },
    "delivery": "not_applicable"
  }
}

The inner error has the same ServerError shape as Error.data.

delivery is always present. It is not_applicable except on failures of SubmitSignedSponsoredTx and SwapSubmit:

{
  "type": "RequestError",
  "data": {
    "request_id": "1e3a5c7e-9b0d-4f26-8a4c-6e8a0c2e4f93",
    "error": { "type": "Generic", "data": { "code": "vault_swap_quote_expired", "message": "Vault swap quote expired" } },
    "delivery": "not_forwarded"
  }
}

delivery describes this one request only:

  • not_forwarded: this request was rejected before it was handed to the keeper (routing gates, validation, a pre-enqueue rejection).
  • unknown: this request may have reached the keeper pipeline (timeouts, queue errors, kernel_timeout, order_already_submitted). Resolve it with GetOrderStatus (orders) or GetSwapStatus / SwapSettled (Vault swaps).

It says nothing about earlier attempts with the same signed transaction. Treat an order or swap as not executed only if every attempt you made returned not_forwarded; if any attempt timed out, was lost with the connection, or returned unknown, resolve it by status before re-signing.

Prefer RequestError handlers over Error handlers wherever you pass request_id in requests. Both events fire error in the TypeScript SDK (see Web client SDK).

Parsing rule (applies to both Error.data and RequestError.data.error)

  1. Branch on type.
  2. If type != "Generic", treat it as a typed variant.
  3. If type == "Generic", branch on data.code.

Generic code example:

{
  "type": "Error",
  "data": {
    "type": "Generic",
    "data": { "code": "parse_error", "message": "invalid payload" }
  }
}

Typed variant examples:

{ "type": "Error", "data": { "type": "RfqNotFound" } }
{
  "type": "Error",
  "data": {
    "type": "Unauthenticated",
    "data": { "action": "submit_quotes" }
  }
}

Generic codes and AuthError reasons are listed in the WS error code catalog.

Error actions

Every error maps to one action; the ServerError catalog and the WS error code catalog list it per type, code or nested reason. Branch on the action, not on message.

ActionWhat the client does
retryTransient. Send the same request again after a backoff
reauthenticateAuthenticate again, then send the same request
refreshAn input went stale (quote, RFQ, risk authority). Fetch fresh state and build a new request
reconcileThe command may already have taken effect. Look it up (GetOrderStatus, GetSwapStatus, MyActiveRfqs) before anything else
fix_requestThe request is invalid. Change it before sending again
stopNo resend succeeds until the venue, market or account state changes

delivery: "unknown" overrides the action: such a submission may still execute, so the action is reconcile whatever the error. Only retry and reauthenticate allow resending an unchanged request. The SDKs expose the same table: errorAction in TypeScript and ServerError::action in Rust.

ServerError catalog

This is the closed set of type values. A variant without data has no data key: { "type": "RfqNotFound" }. Enum values are lowercase snake_case strings.

typedataActionMeaning
Unauthenticated{ action }reauthenticateThe action needs an authenticated session
Unauthorized{ role, action }stopOnly role may do this
RfqNotFoundnonerefreshThe RFQ does not exist
RfqNotActivenonerefreshThe RFQ is not accepting quotes
RfqAlreadyLockednonereconcileAnother of your orders holds the RFQ; MyActiveRfqs shows it in lock
InvalidState{ state }stopThe RFQ is in the wrong state for this command
QuoteLocked{ reason }rfq_locked: refresh; order_submitted: reconcileThe quote cannot be changed
QuoteNotFoundnonerefreshThe quote does not exist or is already gone
QuoteExpirednonerefreshThe quote has expired
QuoteExpiryTooShort{ min_seconds }fix_requestvalid_until is less than min_seconds from now
InvalidStrikenonefix_requestThe strike is not allowed on this RFQ
InvalidValidUntilnonefix_requestvalid_until is invalid
OrderIdMismatchnonefix_requestorder_id does not match the order
UnknownOrdernonerefreshThe server does not know this order_id
SignatureTimeoutnonerefreshThe signature window closed; select another quote
OracleNotReadynoneretryThe underlying oracle is not available yet; retry
OraclePriceStale{ age_seconds }retryThe oracle price is age_seconds old
OraclePriceNotReadynoneretryThe oracle has no usable price yet
InvalidPositionTypenonefix_requestThe product does not fit the market's side
InvalidMarket{ pubkey }fix_requestpubkey is not a valid market
MarketMetadataIncomplete{ details }retryActive markets lack oracle PDAs or decimals
TokenMetadataIncomplete{ details }retryActive markets lack token decimals
RateLimita RateLimitReason stringtoo_many_active_rfqs_per_taker, too_many_active_rfqs_total: retry; too_many_failed_orders_per_rfq: reconcile; too_many_quotes_per_rfq, too_many_sessions_per_user: stopA resource limit was hit
Capa CapError objectcaps_unavailable: retry; any exceeded cap: fix_requestA cap was hit. See Capacity limits
InternalErrornoneretryUnexpected server failure
KernelNotAvailablenoneretryThe matching engine is not available; retry
DbDisabled{ feature }stopThis read needs a database and the server has none
ServerShuttingDownnoneretryThe server is draining; reconnect
InviteRequirednonestopThe taker wallet must redeem an invite
Invitean InviteErrorReason stringinternal_error: retry; invalid_code: fix_request; other reasons: stopThe invite was refused
Claima ClaimErrorReason stringinternal_error: retry; not_registered: stop; other reasons: fix_requestThe referral code claim was refused
WrongEndpoint{ endpoint, allowed_endpoints }fix_requestThe message is not accepted on this endpoint
Generic{ code, message }by codecode is in the WS error code catalog
Field or stringValues
actionsubmit_quotes, cancel_quotes, create_rfqs, accept_quotes, submit_signed_tx, cancel_rfqs, access_rfq, request_positions, subscribe, unsubscribe, read_maker_data
rolemaker, taker, owner
statenot_active, not_pending_signature, cannot_be_cancelled
reasonrfq_locked, order_submitted
min_seconds, age_secondsInteger seconds
featuremaker_positions, maker_markets, market_descriptors, expiries, tokens, mm_summary, my_quotes, my_trades
endpoint, allowed_endpointsmaker, maker_data, taker, vault
InviteErrorReasoninvalid_code, code_exhausted, code_expired, code_disabled, code_owner_inactive, code_owner_blacklisted, already_registered, internal_error
ClaimErrorReasonnot_registered, invalid_format, code_taken, reserved, internal_error

RateLimitReason is in the Maker and Taker references. CapError is in CapError.

{ "type": "Error", "data": { "type": "QuoteLocked", "data": { "reason": "rfq_locked" } } }
{ "type": "Error", "data": { "type": "QuoteExpiryTooShort", "data": { "min_seconds": 60 } } }
{ "type": "Error", "data": { "type": "OraclePriceStale", "data": { "age_seconds": 120 } } }
{ "type": "Error", "data": { "type": "DbDisabled", "data": { "feature": "mm_summary" } } }

WS error codes

The closed set of Generic.code values (in Error.data and RequestError.data.error) and AuthError.reason values. The server sends nothing outside this table; typed ServerError variants (RfqNotFound, Unauthenticated, WrongEndpoint, …) are not codes. A client that receives a code outside this set fails to decode the frame.

CodeFramesActionMeaning
parse_errorGenericfix_requestThe frame is not valid JSON or not a known message
too_many_parse_errorsGenericfix_requestConsecutive parse errors exhausted the budget; the connection closes
hello_requiredGenericfix_requestThe first message was not Hello; the connection closes
hello_timeoutGenericretryNo Hello in time; followed by close 4005
hello_already_sentGenericfix_requestA second Hello on one connection
rate_limitedGenericretryConnection or wallet rate limits close with 4003; a per-type limit rejects only the message. Carries no retry time; see Rate limits and admission
server_overloadedGenericretryThe admission limit for this message class is full; retry with backoff. A full connection command queue sends it uncorrelated and closes with 4003
server_busyGeneric, AuthErrorretryA bounded internal queue (auth, RFQ creation) is full; retry
internal_errorGenericretryUnexpected server failure; the message is sanitized
temporarily_unavailableGeneric, AuthErrorretryA dependency (database, matching engine, registry) is not ready; retry with backoff
clock_errorGeneric, AuthErrorretryThe server clock is before the Unix epoch
time_overflowGenericfix_requestThe requested deadline cannot be represented
trading_pausedGenericstopVenue trading is paused; order-path messages are rejected
batch_quotes_too_largeGenericfix_requestBatchQuotes exceeds max_batch_quotes
session_replacedGenericstopA newer connection took over this session; do not reconnect automatically
session_expiredGeneric, AuthErrorreauthenticateThe session or resume credential expired; authenticate again
session_limit_exceededAuthErrorstopToo many concurrent sessions for this identity
session_conflictGenericreauthenticateThe server no longer binds this session to the identity
blacklistedGeneric, AuthErrorstopThe identity is blacklisted; terminal
maker_unregisteredGenericstopThe maker left the registry while connected; the connection closes
maker_not_registeredGeneric, AuthErrorstopThe pubkey is not a registered maker
auth_timeoutAuthErrorreauthenticateAuthentication did not finish in time; followed by close 4001
too_many_auth_attemptsAuthErrorretryAuth attempt budget exhausted; the connection closes
already_authenticatedAuthErrorfix_requestAuth started on an authenticated connection
challenge_not_issuedAuthErrorfix_requestAuthChallenge without a preceding AuthRequest
challenge_mismatchAuthErrorfix_requestThe signed challenge differs from the issued one
pubkey_mismatchAuthErrorfix_requestAuthChallenge.pubkey differs from the StartAuth pubkey
invalid_signatureAuthErrorfix_requestThe challenge signature does not verify
operator_mismatchAuthErrorfix_requestThe Vault challenge was signed by another operator
vault_auth_not_startedAuthErrorfix_requestVault challenge answered without StartVaultAuth
vault_auth_requiredGenericreauthenticateA Vault message on a session without Vault authority
vault_resume_not_supportedAuthErrorfix_requestResumeAuth on /vault
vault_operator_unauthorizedAuthErrorstopThe operator holds no current grant for the Vault
vault_authorization_unavailableAuthErrorretryVault authority could not be read; retry
vault_session_invalidatedGenericreauthenticateThe Vault grant changed or was revoked; the session closes
invalid_vault_subscriptionGenericfix_requestThe subscription is not allowed for a Vault session
invalid_productsGenericfix_requestSubscribe.products is empty
subscription_scope_too_largeGenericfix_requestThe two mint lists exceed 1024 entries after each is deduplicated; the existing scope stays unchanged. See Subscribe
history_projection_incompleteGenericstopA history read lacks listener metadata; retrying does not help until reconciliation
invalid_limitGenericfix_requestPage limit outside the accepted range for the query
invalid_cursorGenericfix_requestPage cursor is malformed or does not match the requested cursor format
invalid_timeoutGenericfix_requesttimeout_seconds outside the venue's min_rfq_timeout_seconds to max_rfq_timeout_seconds
market_not_foundGenericfix_requestThe market is not in the registry
invalid_program_idGenericstopThe server program id is misconfigured
unsupported_protocol_versionGenericstopHello.protocol_version is not 1.0.0; followed by close 4006
invalid_strike_notionalGenericfix_requestStrike × quantity is zero or not representable on chain
insufficient_collateralGenericfix_requestWallet taker cannot fund the RFQ collateral. RfqRequest is rejected before maker broadcast; message includes required and available in collateral atoms
invalid_quantity_size_ruleGenericfix_requestThe quantity is outside the size rule
product_not_allowedGenericfix_requestThe pair policy is absent or does not allow the requested product
missing_size_rule_for_underlying_mintGenericstopNo size rule is configured for the underlying
invalid_underlying_mint_keyGenericstopThe tick configuration key is not a valid mint
missing_tick_for_underlying_mintGenericstopNo strike tick is configured for the underlying
ladder_strike_source_unavailableGenericretryThe strike ladder source failed
invalid_strikesGenericfix_requestThe requested strike set is invalid
taker_buy_unsupportedGenericfix_requestRfqRequest with side: "buy" from a vault session; a vault writes buys only by quoting
spread_invalid_strikesGenericfix_requestZero, reversed or otherwise invalid spread strikes
spread_tick_violationGenericfix_requestA spread strike is off the underlying mint's strike tick
spread_premium_invalidGenericfix_requestPrice is at or above the width, the gross transfer is zero, or the cash arithmetic is unrepresentable
duplicate_rfq_idGenericreconcileThe RFQ id already exists
rfq_closedGenericrefreshThe RFQ is closed
market_finalizedGenericstopThe market is finalized
market_disabledGenericstopThe market is disabled
market_expiredGenericstopThe market expired
market_pre_expiryGenericstopThe market is in its pre-expiry window
quote_identity_mismatchGenericfix_requestThe quote terms or side differ from the RFQ
quote_refresh_requiredGenericrefreshThe quote must be refreshed; the maker got QuoteRefreshRequested
duplicate_quoteGenericreconcileDuplicate quote order_id
resource_limitGenericretryA per-identity resource limit was reached
kernel_timeoutGenericreconcileThe matching engine did not answer in time; a submission's outcome is unknown
caps_authority_unavailableGenericrefreshQuote risk authority changed; request a new quote
vault_not_tradableGenericstopA Vault counterparty cannot take this position now
invalid_vault_counterpartyGenericfix_requestWriter and holder must be distinct Vaults
tx_build_failedGenericretryThe sponsored transaction could not be built; the message is from a fixed list
order_already_submittedGenericreconcileThe order was already handed to settlement
sponsored_tx_not_readyGenericretryThe sponsored transaction is not ready yet
invalid_signed_txGenericfix_requestThe signed transaction does not decode or match
invalid_amountGenericfix_requestThe swap amount is not a positive u64 string
vault_authorization_failedGenericreauthenticateVault authorization is no longer valid
vault_projection_unavailableGenericretryVault state is temporarily unavailable
vault_safety_modeGenericstopVault safety mode forbids the action
vault_pending_capitalGenericstopThe idle capital window must be closed and unpriced
vault_trading_closedGenericstopThe Vault cycle does not permit trading
vault_mismatchGenericfix_requestThe request Vault differs from the session Vault
vault_governance_requiredGenericstopRecovery and closing swaps need governance
vault_swap_invalid_stateGenericstopVault state does not permit this swap
vault_swap_invalid_amountGenericfix_requestThe swap amount is invalid for the Vault
vault_swap_idempotency_conflictGenericfix_requestThe swap id is already bound to different swap data
vault_swap_quote_expiredGenericrefreshThe swap quote expired; request a new one
vault_swap_signed_tx_rejectedGenericrefreshThe signed swap transaction was rejected
vault_swap_oracle_staleGenericretryThe Pyth price is too old; retry within seconds
vault_swap_route_unavailableGenericretryNo swap route right now
vault_swap_service_unavailableGenericretryAnother transient swap-service failure

Correlation semantics

There's no single global correlation id. Correlation is per-request, via the request_id field on messages that have a defined response.

  • Subscribe / Unsubscribe carry a mandatory request_id. The server echoes it in SubscribeAck / UnsubscribeAck, and the subscribed / unsubscribed arrays contain only the diff for this call — not the full subscription list.
  • GetSubscriptions carries request_id; Subscriptions echoes it.
  • Query-style Get* operations require request_id and echo it in their responses.
  • Correlated failures use RequestError { request_id, error }; Error has no request ID.
  • RfqRequest, AcceptQuote and SubmitSignedSponsoredTx require request_id and get exactly one reply: CommandAccepted { request_id } or RequestError { request_id, error }, including for routing gates (rate limit, pause, invite gate, wrong endpoint, overload). CommandAccepted means the server accepted the command, never that anything landed on chain. Lifecycle pushes (RfqCreated, OrderAccepted, OrderFailed, …) stay keyed by rfq_id / order_id and may arrive before or after the receipt. RfqRequest.request_id is also the idempotency key: a repeat while the RFQ is open fails with duplicate_rfq_id, which proves the first one created it.
  • Exception: when the server's inbound queue for a connection is full it sends an uncorrelated Error { code: "server_overloaded" } and closes the socket with 4003 rate_limited. Every request still outstanding on that connection has an unknown outcome; resolve submissions by status after reconnecting.
  • Indicative pricing uses request_id on both IndicativePricesRequest (server → maker) and IndicativePricesResponse (maker → server).
  • Broadcasts (RfqBroadcast, TradeExecuted, StatsUpdate, etc.) don't carry request_id.

SubscribeAck / UnsubscribeAck

{
  "type": "SubscribeAck",
  "data": {
    "request_id": "uuid",
    "subscribed": ["rfqs", "trades"]
  }
}
{
  "type": "UnsubscribeAck",
  "data": {
    "request_id": "uuid",
    "unsubscribed": ["stats"]
  }
}

subscribed / unsubscribed are the channels that were actually added or removed — channels already subscribed (or already absent) are not repeated.

Lifecycle terms

Use the same terms across all external docs:

RFQ lifecycle

  • Terminal RFQ event: RfqClosed. Close RFQ state only on this event.
  • Fill-details event (maker): QuoteFilled. Contains fill details for the winning maker.
  • Order-level confirmation (taker): OrderConfirmed. Confirms the selected order and carries position_pda; the transaction signature came earlier on OrderSubmitted.

Position lifecycle (post-fill)

Position rows carry a required state: open, funded, liquidated or settled { settlement: physical | cash }.

  • open: position created, collateral locked, premium paid to taker.
  • funded: the holder deposited the settlement asset via DepositFundsToPosition. Physical products only. WithdrawFundsFromPosition before expiry returns the position to open.
  • settled: market finalized, assets distributed based on the ITM/OTM outcome. settlement is physical for covered calls and cash-secured puts, cash for spreads and cash puts.
  • liquidated: an unfunded ITM position was closed by a liquidation transaction. Physical products only.

Spreads and cash puts settle in cash in the quote mint. Their lifecycle is open then settled. PositionUpdated with update_type funded or liquidated does not occur for them.

Trade lifecycle and payoff: Protocol flow.

Supported channels

WsChannel values and what each carries. Channels are role-oriented — subscribe only to the ones your role consumes.

ChannelProducer(s)Audience
rfqsRfqBroadcast, IndicativePricesRequest, quote/order lifecycleMakers. Takers do not subscribe — a taker's own RFQ/quote/order events (RfqCreated, QuoteReceived, OrderAccepted, SponsoredTxToSign, Order*, RfqClosed) are delivered session-addressed regardless of subscription.
taker_buy_rfqsRfqBroadcast and IndicativePricesRequest with side: "buy"Makers that write options for buying wallets from Maker PDA custody.
tradesTradeExecutedPublic trade tape. Participants also receive their own fills session-addressed.
statsStatsUpdateGlobal venue stats.
chain_eventsChainEvent (position opened / settled / liquidated, market finalized)Anyone. This is how a taker tracks position outcomes (settlement / liquidation).
marketsMarketCreated, MarketFinalizedAnyone tracking the tradable market set.
vaultsVaultCatalogChanged, VaultProjectionAdvancedMaker and taker sessions that list or watch vaults: they receive both, VaultProjectionAdvanced for every vault. /vault operator sessions are subscribed automatically and receive VaultProjectionAdvanced for their own vault only, and no VaultCatalogChanged.

There is no positions channel: PositionUpdated and MakerCapsUpdated are delivered owner-direct to the maker's session, with no subscription.

Takers typically subscribe to chain_events (position outcomes) plus optionally trades / stats / markets. They do not need rfqs.

Delivery criticality

When your outbound queue is full, the server handles a pushed message in one of two ways:

  • Critical: the message is dropped and the connection is closed with 4002 slow_consumer. Responses and some pushes are retried briefly first; lifecycle pushes fanned out from chain events are not. Reconnect and re-read state.
  • Best-effort: the message is dropped silently and the connection stays open.
AudienceCriticalBest-effort
/makerRfqBroadcast, QuoteAcknowledged, QuoteRefreshRequested, MarketCreated, MarketFinalized, VaultCatalogChanged, VaultProjectionAdvancedTradeExecuted, ChainEvent, StatsUpdate, RfqSkipped, IndicativePricesRequest
/takereverything except StatsUpdateStatsUpdate
/maker/data, /vaulteverything—

Messages addressed to your session alone (responses, your own lifecycle, PositionUpdated, MakerCapsUpdated) always follow the critical rule.

TradeExecuted is a best-effort live hint and may be lost, delayed, or repeated. Merge it with role-appropriate authoritative history by trade.id; never derive trade counts or irreversible actions from the number of received frames.

Timeout hierarchy

market.expiry_ts
  └─ rfq.expires_at                     # Auction window (no new quotes or accepts after this)

quote.valid_until                        # Cryptographic expiry (on-chain enforcement)
  └─ effective_expiry                    # = valid_until - settlement_buffer_seconds (server-side trading cutoff)
       └─ refresh point                  # = effective_expiry - quote_refresh_lead_seconds (quote freezes)

rfq.signature_deadline_at
  └─ tx_submit_timeout

rfq.expires_at vs quote.valid_until

expires_at is the auction deadline. valid_until is the on-chain order validity.

  • rfq.expires_at controls how long makers can submit quotes and the taker can accept. After this time new quoting/acceptance stops; an enqueued order remains unresolved until execution evidence arrives.
  • quote.valid_until is the signed-order expiry. The on-chain program rejects opening the position at or after valid_until. It does not govern later settlement of an open position.

Choose valid_until beyond expires_at. A taker can accept in the last second of an auction. The signature deadline is capped at expires_at, and the signed transaction confirms on Solana after that. If valid_until equaled expires_at, the quote would freeze before the auction ended, and the on-chain order could expire before the transaction lands.

hard min:    now + min_quote_validity_seconds             (default 60 s)
recommended: rfq.expires_at + min_quote_validity_seconds  (plus a little slack)
hard max:    market.expiry_ts

min_quote_validity_seconds and settlement_buffer_seconds come from Welcome or GET /api/v1/venue. The minimum validity covers the settlement buffer and the refresh lead. To calculate the refresh point, read quote_refresh_lead_seconds from GET /api/v1/venue; Welcome does not carry it. At valid_until - settlement_buffer_seconds - quote_refresh_lead_seconds the server freezes the quote and sends QuoteRefreshRequested. The recommended value keeps that point at or after rfq.expires_at, so the quote stays acceptable for the whole auction.

Values below the hard min are rejected with quote_expiry_too_short. Values later than market.expiry_ts are rejected with market_expired. A value far above the recommended one is accepted, but after rfq.expires_at the server allows no accepts, so it only widens the maker's exposure window.

Example: RFQ with expires_at = now + 60s, settlement buffer 50 s, refresh lead 10 s:

valid_until:      now + 120s
effective_expiry: now + 70s
refresh point:    now + 60s

Invariants

  • quote.valid_until >= now + min_quote_validity_seconds (default 60 s; the server rejects shorter expiries)
  • quote.valid_until <= market.expiry_ts (hard server-side bound)
  • effective_expiry = quote.valid_until - settlement_buffer_seconds (default 50 s)
  • rfq.expires_at < market.expiry_ts (recommended client-side validation)
  • signature_deadline_at = min(accept time + signature_timeout, effective_expiry, rfq.expires_at)

signature_deadline_at appears in QuoteSelected (server -> maker; see Maker API reference) and SponsoredTxToSign (server -> taker; see Taker API reference).

Reconciliation safety

Position rows carry revision { slot, transaction_index, instruction_index }. Compare revisions lexicographically and apply a PositionUpdated or query row only if its revision is newer than the stored one. PositionUpdated is { position, update_type } with a full row. Equal revisions mean equal state.

Use entity versions where available:

  • rfq_version for RFQ lifecycle progression
  • order_version for order lifecycle progression

order_version is present on order lifecycle pushes, not on OrderStatus. Lifecycle precedence uses ranks accepted = 1, submitted = 2, failed = 3, confirmed = 4. Confirmation can replace a locally recorded failure; a transition may skip a rank and replay keeps the same rank.

GetOrderStatus instead returns state: pending | confirmed { position_pda } | unknown. unknown and timeouts do not prove nonexecution. Reconnect reads are not an atomic snapshot; keep unresolved obligations separately from transient RFQ/UI caches.

On client side:

  • apply update only if new_version > current_version
  • ignore stale updates (new_version < current_version)
  • treat equal versions as idempotent replay

Paging

Every WS list request requires limit (1 through 200; max_page_size in /venue, MAX_PAGE_SIZE in the Rust SDK, PAGE_LIMIT in the TS SDK) and cursor. Start with {"type":"start"}. Each response includes next_cursor, an opaque string or null. For the next page, send {"type":"after","id":"<next_cursor>"} with the same filters. Stop at null. Never construct a cursor from a returned row.

{"type":"GetMarkets","data":{"request_id":"00000000-0000-4000-8000-000000000001","limit":200,"cursor":{"type":"start"}}}

REST uses optional limit and cursor query parameters. limit defaults to 50 and allows 1 through 200. Omit cursor for the first page, then pass the opaque next_cursor string directly as its value, URL-encoded as a query parameter. Do not wrap a REST cursor in JSON. For example, request GET /api/v1/vaults?limit=100, then GET /api/v1/vaults?limit=100&cursor=abc if next_cursor is abc. Vault deposit and withdrawal request routes allow at most 100 rows. Out-of-range limits return invalid_limit; malformed cursors return invalid_cursor. WS messages missing required fields fail decoding. Limits are rejected, never clamped. Compound replies share one page budget across their collections. Scalars repeat on each page. Token-market strike lists can span pages; merge fragments by market PDA and position type.

Rust SDK 0.10.0 and TypeScript SDK 0.7.0 use one shared fetch_all or fetchAllPages helper. Their normal list methods collect every page. Use an explicit page method for incremental UI loading, such as getPositionsPageAsync in TypeScript. Raw WS request methods return one page. Keep push updates received during a read and apply position revisions before replacing local state. Paged reads are recovery and history reads, not polling.

Public and admin Hello remain 1.0.0. There is no compatibility layer. Old clients can complete Hello but changed list calls fail request decoding or response decoding. Previous limits of 500 or 1000 now return invalid_limit. Push and cancellation acknowledgement shapes are unchanged and retain their server hard bounds.