Protocol Flow

Acta is an RFQ options venue on Solana. Positions are fully collateralized against on-chain escrow accounts. There is no continuous margin engine, no leverage, and no early exercise.

Five products trade on the venue. Covered calls and cash-secured puts settle physically. Call spreads, put spreads and cash puts settle in cash in the quote mint.

API payloads are in Maker API, Taker API, and WS common conventions.

Actors

ActorRoleAccess
TakerWrites the option or spread, posts collateral, opens the RFQ.Open. Any wallet; no registration, no KYC. Only rate-limited (active RFQ count).
MakerBuys the option or spread, pays the premium. For physical positions, may fund the settlement leg.Permissioned. On-chain RegisterMaker is admin-gated and timelocked. Subject to caps.
Keeper (hot authority)Co-signs the open instructions, calls FinalizeMarket, settles positions.Protocol-operated.
Oracle setter and settlement attestorCompute the expiry fixing and publish it to the oracle accounts.Protocol-operated. See Settlement fixing.
LiquidatorCloses ITM physical positions the maker never funded; fronts the settlement to the taker.Permissionless. Anyone can run it.

Every RFQ, quote and position carries side, the taker's direction. On sell the taker writes and the maker buys. On buy a wallet buys from a maker, who writes from Maker PDA custody, or from a vault, which writes from its collateral leg; the is_taker_buy byte in the order-id preimage is 1. A vault quotes buys but cannot request one: RfqRequest with side: "buy" from a vault session fails with taker_buy_unsupported.

On a buy the buyer pays the gross premium, and a physical option needs a deposit strictly before expiry_ts to exercise. With no deposit all collateral returns to the writer, also when in the money, and the position reads not_exercised. A bought spread or cash put takes no deposit: the maker locks the width times quantity, the buyer can lose at most the premium and receives at most the width.

Products

terms is a tagged union. Each variant fixes the product and its strikes.

terms.typeStrike fieldsMarket sideSettlementTaker collateral
covered_callstrikecallPhysicalquantity underlying atoms
cash_secured_putstrikeputPhysicalfloor(strike × quantity) quote atoms
call_spreadlower_strike, upper_strikecallCash, quote mintC = ceil(width × quantity) quote atoms
put_spreadlower_strike, upper_strikeputCash, quote mintC = ceil(width × quantity) quote atoms
cash_putstrikeputCash, quote mintC = ceil(strike × quantity) quote atoms

width = upper_strike − lower_strike. A cash put is economically a put spread with lower strike 0 and upper strike K. It executes on chain with those legs and keeps the wire name cash_put.

A market is either a call market or a put market (is_put). Market rows list in products only the products of their own side: put markets list cash_secured_put, put_spread, cash_put; call markets list covered_call, call_spread. A market with none of the configured products is not listed. Strikes and strike_tick are scaled by 1e9.

Position lifecycles

Physical: covered call and cash-secured put

The on-chain position account has two live states, open and funded. settled and liquidated are terminal outcomes; the account is closed when they happen.

FromInstructionSignerConditionsTo
(none)OpenPositiontaker, maker Ed25519 quote, keeperProtocol not paused; market not expiredopen
openDepositFundsToPositionholder (maker owner of a sold position, buyer of a bought one)Sold: none on the market's expiry or finalization. Bought: strictly before expiry_tsfunded
fundedWithdrawFundsFromPositionholderStrictly before expiry_tsopen
openSettlePositionany signerMarket finalized; position OTMsettled
fundedSettlePositionany signerMarket finalizedsettled
openLiquidatePositionany signerMarket finalized; position ITMliquidated

A funded position cannot be liquidated. An open ITM position cannot be settled (PositionNotFunded). An OTM position cannot be liquidated (PositionNotItm).

Cash: call spread, put spread, cash put

The lifecycle is open → settled. There is no funded state and no liquidation. DepositFundsToPosition and LiquidatePosition reject spread positions. The maker owes nothing after the premium is paid at open. SettlePosition is permissionless and needs only a finalized market.

PositionUpdated rows for these products never carry funded or liquidated.

What an RFQ does

There is no order book. The taker drives a sealed auction, makers stream signed quotes, and the taker picks the winner.

  • The taker sends RfqRequest (market, terms, side, quantity, timeout). The backend broadcasts it to eligible makers.
  • Makers reply with signed Quotes. Each quote is a (terms, side, price, valid_until) against the fixed request. Makers cannot quote partial size or change the terms.
  • The taker selects the winner by sending AcceptQuote { maker, order_id }. Whatever order_id the taker names wins. The server's "best price" (QuoteBestStatus / QuoteOutbid) is advisory only and never selects the winner.
  • Winner-take-all: one quote is locked for the full RFQ quantity. No partial fills, no multiple winners. Every live quote reserves full capacity against caps (open interest, notional, position count) for its validity window; the reservation is released on cancel, expiry, or rejection, and converts into position exposure on fill. See Capacity limits.
  • A maker's live quote is keyed by (rfq_id, terms). A new quote with the same key replaces the previous one, and QuoteAcknowledged.replaced names it.
  • The advisory "best" ranking (used only for QuoteBestStatus / best_price) is: higher premium wins, ties broken by earlier received_at, then by smaller order_id.

Indicative pricing: after connecting, makers may receive IndicativePricesRequest, one per taker side, and reply with non-binding reference prices per strike. Takers see the median per strike while browsing, before opening an RFQ.

When the taker accepts a quote, the other makers on the RFQ receive RfqLocked. Their quotes stay as backups: a failed signature reopens the RFQ with RfqAvailableAgain.

Trade lifecycle

market traded
  -> RFQ active            (taker requests quotes)
  -> quotes streaming      (makers submit signed quotes)
  -> quote accepted        (taker picks order_id; sponsored tx built)
  -> position open         (atomic risk transfer on-chain)
  -> position funded?      physical only, optional (maker deposits settlement leg)
  -> market finalized      (settlement price written after expiry)
  -> settled / liquidated  (liquidated: physical, ITM, unfunded)

1. Market

A market carries underlying mint, quote mint, expiry timestamp, is_put and the oracle accounts of both mints for that expiry. Strikes belong to orders and positions, not the market identity. Backend tradability also applies the pre-expiry cutoff, the disable state and the finalization state; market expiry alone is not an admission check. After expiry, finalization is required before any settlement or liquidation. See Expiries and the trading cutoff.

2. RFQ

The taker sends RfqRequest with market, terms, side and quantity. quantity is always in underlying atomic units. Before broadcasting, the backend checks: market is active, taker can trade, trading is not paused, size and tick rules pass, caps do not block. A maker blocked by caps may receive RfqSkipped instead of RfqBroadcast.

3. Quote

Makers receive RfqBroadcast, choose a premium, build a 32-byte order_id, sign it, and send Quote. The quoted price is the gross premium per 1 underlying unit, scaled by 1e9. The order_id commits to market, product, strikes, quantity, gross price, validity, maker, taker, and nonce. Physical products use the 182-byte preimage; spreads and cash puts use the 190-byte preimage that also commits the upper strike. Backend checks: order-id and maker signature match, quote still valid, maker registered, maker has enough deposited quote balance for the premium, maker and platform caps pass.

For spreads and cash puts the gross price per unit G must satisfy 0 < G < width.

4. Accept and open

The taker sends AcceptQuote { maker, order_id }. The backend returns a sponsored transaction; the taker signs it and returns it with SubmitSignedSponsoredTx. On chain, the open instruction (OpenPosition for physical products, OpenSpread for spreads and cash puts) requires the taker's signature, the maker's Ed25519 signature over order_id in the preceding instruction, and the keeper co-signature. It fails with ProtocolPaused while the protocol is paused. If the checks pass, the position opens atomically; risk transfers here (see Risk model).

Timing and deadlines

Defaults below are the server's configuration defaults; all are configurable.

<!-- generated:rfq-timing-defaults -->
ParameterDefaultMeaning
RFQ windowtaker-chosenexpires_at = created_at + request.timeout. The auction deadline.
settlement_buffer50 sThe trailing window reserved for settlement confirmation. A quote's effective trading cutoff is valid_until - settlement_buffer; quotes whose valid_until is closer than settlement_buffer + quote_refresh_lead are rejected.
quote_refresh_lead10 sAt effective_expiry - quote_refresh_lead the server fires QuoteRefreshRequested and freezes the quote (unacceptable until re-quoted).
signature_timeout30 sMax time the taker has to sign the sponsored tx after AcceptQuote. The signature deadline is the minimum of now + signature_timeout, the quote's effective expiry, and the RFQ's expires_at.
submitted_watchdog_timeout120 sAfter this the server flags a submitted trade that has not resolved. The RFQ stays locked to the selected quote until the trade confirms on-chain or the server knows the transaction was never sent.
closed_rfq_ttl300 sHow long a closed RFQ is retained before purge.
max_quotes_per_rfq50Cap on quotes per RFQ across all makers.
max_rfqs_per_taker / max_active_rfqs50 / 1000Concurrency limits; each must be within 1..=1000.
max_active_rfqs_per_ip50Unfinished RFQs per source IP, counted across wallets and reconnects; must be within 1..=1000. A breach rejects RfqRequest with a resource-limit error.
<!-- /generated:rfq-timing-defaults -->

rfq.expires_at is the auction deadline; quote.valid_until is the on-chain order validity. They are distinct clocks. valid_until may not exceed the market expiry.

On a signature timeout or tx-build failure, the locked (winning) quote is discarded and only the still-valid losing quotes are restored; the RFQ reverts to active if it has not yet expired.

Expiries and the trading cutoff

An expiry is the expiry_ts of a market. Markets are created on chain by the hot wallet with any expiry_ts in the future. For each expiry the market needs one oracle account per mint, created before the market. Neither the contract nor the backend enforces an expiry grid or a creation cadence, so the set of expiries is whatever markets exist. Read it from GET /api/v1/markets or the GetExpiries query, and re-read on ReferenceChanged.

New RFQs stop pre_expiry_cutoff_seconds before expiry. GET /api/v1/venue returns this default (the server's built-in default is 10,800 s). An operator can set an explicit absolute cutoff on a single market, which replaces the default for that market. /venue does not report such overrides. A disabled or finalized market is not tradable regardless of the cutoff. The cutoff gates new RFQs and admission only; it does not close existing positions.

Economics

Units

PRICE_SCALE = 1_000_000_000.

FieldMeaning
priceGross premium per 1 underlying unit, 1e9 scale
strike, lower_strike, upper_strike, strike_tickQuote per 1 underlying unit, 1e9 scale
quantityUnderlying atomic units
total_premiumNet premium paid to the taker, quote atomic units

Quote-side atomic amount, rounded down or up:

scaled_quote_amount(x, quantity)      = floor(x * quantity * 10^quote_decimals / (PRICE_SCALE * 10^underlying_decimals))
scaled_quote_amount_ceil(x, quantity) = ceil( x * quantity * 10^quote_decimals / (PRICE_SCALE * 10^underlying_decimals))

scaled_quote_amount(price, quantity) is the gross premium. scaled_quote_amount(strike, quantity) is the notional of a physical position: put collateral and call settlement amount. Spread collateral and payoff use the ceiling form.

Cash flow at open

On a successful open:

  1. Maker PDA pays the net premium to the taker in the quote token.
  2. Maker PDA pays the protocol fee to the protocol fee account.
  3. Taker collateral moves into the position escrow.
  4. Position state becomes open.

Collateral

ProductTaker collateral (locked at open)Maker settlement asset (physical, if ITM)
Covered callquantity underlying atomic unitsscaled_quote_amount(strike, quantity) quote atomic units
Cash-secured putscaled_quote_amount(strike, quantity) quote atomic unitsquantity underlying atomic units
Call spread, put spreadC = scaled_quote_amount_ceil(width, quantity) quote atomic unitsNone
Cash putC = scaled_quote_amount_ceil(strike, quantity) quote atomic unitsNone

Taker collateral is fully locked at open. For physical products the maker settlement leg is not locked at open: the maker pays the premium and may deposit the settlement asset later with DepositFundsToPosition (open → funded). Spreads and cash puts have no maker leg. The maker needs a deposited program quote balance (via MakerDeposit) for the premium debit; idle balance is retrieved with MakerWithdraw.

Fees

The maker signs the gross price. The contract nets the fee during open:

gross_premium = scaled_quote_amount(price, quantity)

price_after_premium_fee_bps =
  price - floor(price * protocol_fee_bps_premium / 10_000)
premium_fee =
  gross_premium - scaled_quote_amount(price_after_premium_fee_bps, quantity)

exposure = strike          (covered call, cash-secured put, cash put)
         = width           (call spread, put spread)
volume_fee = floor(scaled_quote_amount(exposure, quantity) * protocol_fee_bps_volume / 10_000)

fee_total   = min(premium_fee, volume_fee)
net_premium = gross_premium - fee_total

The taker receives net_premium; Position.total_premium and the wire field total_premium hold the same net value in quote atoms. The maker pays gross_premium, so its cost is scaled_quote_amount(price, quantity) and the fee is that cost minus total_premium. protocol_fee_bps_premium and protocol_fee_bps_volume are on-chain config of each quote token, set by governance (each ≤ 10000 bps), and are published as the token's protocol_fees by GET /api/v1/tokens. net_price in WS payloads is a display estimate only; for accounting use the formula above or total_premium.

Spread payoff

For a spread or cash put with legs (L, U) at settlement price S:

call spread: intrinsic = max(S - L, 0)
put spread:  intrinsic = max(U - S, 0)      (cash put: L = 0, U = K)

holder_payoff = scaled_quote_amount_ceil(min(intrinsic, width), quantity)
writer_return = collateral_balance - holder_payoff

holder_payoff is at most C. The writer receives the rest of the escrow, including any amount donated to it. The buyer's profit is holder_payoff - gross_premium, and the writer's loss is bounded by C - net_premium.

Settlement and payoff

After expiry the hot wallet publishes one scalar price per oracle account (one for the underlying mint and one for the quote mint) and then calls FinalizeMarket:

settlement_price = floor(underlying_price * PRICE_SCALE / quote_price)

FinalizeMarket needs both oracle prices published at or after expiry. The market stores settlement_price, which the market rows return as settlement: { "type": "pending" } until then. Settlement prices are determined as described in Settlement fixing.

At-the-money counts as OTM.

ProductOTMITM
Covered callsettlement_price <= strikesettlement_price > strike
Cash-secured putsettlement_price >= strikesettlement_price < strike
Call spreadsettlement_price <= lower_strike (payoff 0)settlement_price > lower_strike
Put spread, cash putsettlement_price >= upper_strike (payoff 0)settlement_price < upper_strike

Physical outcomes

StateMoneynessToken movement
openOTMTaker gets collateral back.
fundedOTMTaker gets collateral back; maker gets the settlement deposit back.
fundedITMTaker collateral goes to the maker; the maker settlement deposit goes to the taker (a swap at the strike).
openITMSettlePosition fails. The position must be liquidated.
Covered callCash-secured put
Taker posts (collateral)UnderlyingQuote
Taker receives (premium)Quote (net)Quote (net)
Maker pays (premium)QuoteQuote
Maker funds (settlement, if ITM)QuoteUnderlying
ITM: taker receivesQuote (maker's settlement)Underlying (maker's settlement)
ITM: maker receivesTaker's underlying collateralTaker's quote collateral
OTM: each side keepsTaker keeps collateral; maker keeps settlement depositSame

Cash outcomes

SettlePosition pays holder_payoff to the holder and writer_return to the writer, both in the quote mint, and closes the position. If one owner is on both sides, both amounts go to distinct quote accounts or one shared account. The final state is settled { settlement: cash { settlement_price, holder_payoff, writer_return } }.

Funding deadline (physical positions)

For a sold position the contract sets no deadline for DepositFundsToPosition. It accepts a deposit while the position is open, before or after expiry and before or after market finalization. The only thing that ends the window is a terminal instruction. A bought position is funded by its buyer strictly before expiry_ts.

Before expiry_ts the holder can take the deposit back with WithdrawFundsFromPosition; the position is open again and settles as unfunded unless it is funded again.

  • Before finalization. Funding is always safe.
  • After finalization, position OTM. Funding has no effect on the outcome. SettlePosition returns both sides' assets.
  • After finalization, position ITM and open. LiquidatePosition is permissionless. Anyone can call it once the market is finalized. The first of the maker's DepositFundsToPosition and a liquidation to land wins. If the deposit lands first, the position is funded and LiquidatePosition fails; settlement then swaps at the strike.
  • If the liquidation lands first. The liquidator transfers the settlement amount to the taker, receives the whole escrowed collateral, and the position closes as liquidated. The maker keeps nothing and owes nothing further. The premium paid at open is not returned.

The keeper does not liquidate. Its settler settles OTM and funded positions, refuses an ITM open position ("must be liquidated, not settled") and logs a count of open_itm_not_fundable positions per tick. Whether a third-party liquidator runs on a deployment is not guaranteed by the protocol. A maker that wants the swap must fund before finalization.

Funding a position held by a vault has additional vault rules; see the vault operator guide.

Settlement fixing

The oracle price of each mint at expiry E is a time-weighted average of Pyth prices over the 30 minutes ending at E. It is computed off chain from Pyth Benchmarks history. The chain checks who signed the number, not how it was computed.

Policy

The policy is acta-pyth-benchmarks-v1, calculation version 1, and applies to oracle type 0. It is compiled into the services and is not operator configuration.

ParameterValue
Window[E - 1800, E] seconds
AnchorThe last observation at or before E - 1800, read from history starting at E - 1860
SourcePyth Benchmarks history for the oracle's feed id; ordinary price, not ema_price
Feed idsThe feed id stored in the oracle account, taken from the mint's oracle source. GET /api/v1/tokens lists them as oracle_feed_ids
ScaleNormalized to 1e9, integer half-up rounding
Confidence filterObservations with ceil(conf / price * 1_000_000) > 100_000 ppm (10%) are discarded
Other filtersNon-positive prices and observations after E are discarded
DuplicatesIdentical observations at one publish_time are merged; different values at one publish_time fail the fixing
Maximum gap60 s between consecutive kept observations, from the anchor to E - 1800, and from the last observation to E
CalculationPiecewise-constant TWAP: each observation's price holds until the next one; sum of price × seconds over the 1800 s window, divided by 1800, rounded half-up
ResultMust be non-zero

If no anchor exists, a gap exceeds 60 s, or two observations conflict, no price is produced and the oracle is not updated. The fixing is never filled from live Hermes prices.

The settlement attestor fetches history in 60 s slots. A slot is fetched only after its end plus a finalization delay (60 s in the shipped configuration), so the last slot is read no earlier than E + 60 s. A decision for an (oracle, expiry) pair, once made, is stored with its policy hash and is not recomputed under a different policy.

Mints with an on-chain price route are fixed by evaluating the route at expiry with this TWAP in place of the Pyth input. The on-chain message is the same.

Who submits and what the chain checks

  1. After E, the oracle setter (hot wallet) computes the TWAP from Benchmarks history.
  2. The settlement attestor, a separate service with its own key, computes it independently. The setter submits only if the attestor's price, observation digest and evidence match its own and both signatures verify.
  3. The hot wallet submits UpdateOraclePriceAttested, preceded in the same transaction by an Ed25519 instruction signed by the attestor. The message binds the domain, program, global config, oracle, price, expiry, issued_at, valid_until and calculation version. The contract requires GlobalConfig.settlement_attestor to be the signer, the message to match exactly, issued_at >= expiry, a validity window of at most 300 s and now inside it.
  4. The contract rejects a zero price, a price above its maximum, and a second update of the same oracle (OracleAlreadyUpdated). It does not recompute the TWAP and does not verify any Pyth account.
  5. FinalizeMarket (hot wallet) combines the two oracle prices into settlement_price.

When no attestor is configured, the hot wallet publishes directly with UpdateOraclePrice. When one is configured, direct hot publication is rejected and only the cold authority keeps a direct path. The cold authority can also overwrite a published price with CorrectOraclePrice until the markets on that oracle are finalized. See Governance and security.

Risk model

Every position is fully collateralized at open in its own escrow. There is no leverage, no maintenance margin, no mark-to-market, no margin call, and no early exercise. Positions open before expiry and resolve only after market finalization.

Custody is per-position. Taker collateral and, for physical products, the maker's settlement deposit each sit in escrow accounts owned by the position PDA; the maker's premium balance sits in the maker PDA. The protocol never holds principal risk; it custodies escrow and routes settlement. The counterparty is a specific maker, not a pool or the protocol: each position names one taker and one maker.

Spreads and cash puts carry no counterparty risk after open. The maker's entire exposure is the premium it paid, and the payoff is paid out of the taker's escrow at settlement.

For physical products, taker collateral is locked at open. An ITM payout requires the maker to fund settlement or a liquidator to supply the settlement asset. The contract provides both paths; it does not guarantee when a willing, funded liquidator will execute the latter. If the option expires ITM and the maker never funded, the position stays open after finalization; a liquidator pays the taker the settlement asset, takes the taker's collateral, and closes the position as liquidated. The contract creates no additional claim against the maker for an unfunded settlement leg.

Liquidation is post-finalization only: an ITM, unfunded physical position, not a price-threshold or maintenance call. It is permissionless but not automatic. The taker is paid when the liquidation transaction lands.

Backend caps are a separate risk control layered on top: platform caps (token open interest per underlying, quote notional per quote mint, market open interest) apply to everyone; maker caps (open position count, notional per underlying, deposited premium balance) apply to makers. See Capacity limits.

State machine and events

Terminal states:

  • RFQ: expired, cancelled, or filled.
  • Position: settled or liquidated.

Events worth tracking end to end:

EventWhen
QuoteFilled / OrderConfirmedPosition opened on chain; both carry position_pda, and QuoteFilled also transaction_signature. QuoteFilled has no fee or net-premium fields; read the money from the position row.
RfqClosedAuction closed; on a fill, winner = { type: "winner", maker, price, transaction }.
ChainEvent(position_opened)Position opened, via chain events.
PositionUpdated { position, update_type }Full position row; update_type is created, funded, liquidated or settled. Apply it only if its revision is newer than the stored one.
MarketFinalizedMarket expired, settlement price set.
ChainEvent(position_settled)Assets distributed.
ChainEvent(position_liquidated)Unfunded ITM physical position liquidated.

RegisterMaker, MakerDeposit, MakerWithdraw, DepositFundsToPosition and WithdrawFundsFromPosition are Solana on-chain instructions, not WebSocket messages; build and submit them as transactions signed by the relevant owner wallet. The layouts of the maker's deposit instructions are in Sandbox. The full IDL ships in @acta-markets/ts-sdk as ACTA_IDL.