Pelagos protocol reference

Product, settlement, and API semantics

Pelagos is a non-custodial structured-products interface on Sui testnet. The backend prices products, validates current quote state, builds unsigned programmable transaction blocks, and dry-runs supported writes. A connected wallet remains the signer.

Testnet only. dUSDC and mUSDC are separate test assets. Product availability depends on live oracle freshness, quoteability, vault capacity, and configured testnet objects. Nothing here represents a mainnet or guaranteed-return product.

Current application surfaces

Product Map

The primary navigation is Portfolio, Distribution Markets, Volatility, Range Strips, Baskets, and About. Oracle Index is an infrastructure subview inside Portfolio, while Range Strips opens the BTC Range Desk.

Surface	Scope	Pricing and settlement
Distribution Markets	BTC option bands and an advanced distribution builder	Exact-size DeepBook range quotes; dUSDC or isolated mUSDC settlement
Volatility	Prebuilt and custom volatility structures	DeepBook strip pricing with display greeks and labeled hedge simulation
Range Strips	Navigation label for the BTC Range Desk	Range Execution, Liquidity Mandates, and Funded Outcomes
Baskets	Curated event baskets and advanced risk slices	Live reference data with clearly separated settlement behavior
Portfolio	Wallet positions, activity, and execution infrastructure	Rail-aware holdings plus the Oracle Index subview; dUSDC and mUSDC are never combined as one asset

Three distinct books

BTC Range Desk

Range ExecutionForward Pin, Upper Band, Upper Tail, Lower Band, Lower Tail, In-Range, and Breakout profiles. Each order buys a terminal BTC settlement strip priced at its exact band quantities.

Liquidity MandatesUnhedged PLP, PLP + Lower Tail, PLP + Two-Sided Wings, and PLP + Center Rebate. dUSDC creates transferable PLP inventory and optional live range hedges; mUSDC creates an isolated counterparty-payoff receipt. Both are capital at risk: PLP is market-making exposure, not lending, fixed APY, or guaranteed yield.

Funded OutcomesUpside Participation, Range Accrual, Terminal Corridor, Downside Buffer, Two-Sided Buffer, and Three-Date Autocall. Every preset is capital at risk; names such as Buffer describe payoff shape, not principal protection. The first five are terminal schedules. Three-Date Autocall is mUSDC-only and observes three discrete dates.

A requested tenor is a target. Funded Outcomes select the nearest available live execution expiry and return the actual tenor in the quote. Terminal barriers are observed at expiry unless the quote explicitly carries the discrete autocall schedule.

Do not aggregate the currencies

Settlement Rails

Property	dUSDC	mUSDC
Asset	DeepBook Predict quote asset; faucet-gated on testnet	Freely mintable Pelagos mock USDC test asset
Execution	Native Predict ranges and transferable PLP shares	Pelagos receipt with an isolated, server-locked payoff schedule
Capacity	Consumes finite Predict vault risk capacity	Does not consume or represent Predict execution capacity
Pricing reference	Live DeepBook sized bid/ask	The same current DeepBook reference book, without Predict ownership
Wallet funding	May be reduced by existing manager collateral; headroom is disclosed separately	Gross debit equals the server-quoted premium or capital-at-risk amount; fee economics are itemized
Autocall	Not supported	Canonical Three-Date Autocall rail

There is no swap, peg, redemption right, or ownership equivalence between the rails. An mUSDC receipt does not confer a Predict range position, PLP share, dUSDC claim, or capacity reservation.

Raw integer amounts are authoritative

Funding Identity

USD labels are presentation values. Prepare responses reconcile funding in raw coin integers, and those integers should be used for balance checks and transaction review.

dUSDC Range Execution and Basic Options

live exact position cost + execution headroom = funding ceilingfunding ceiling - existing manager collateral applied = max new wallet authorization

The quoted cost is the position price, while the funding ceiling is a temporary maximum used to tolerate a small execution move. Existing dUSDC already inside the owner-controlled PredictManager is applied first. That is why the wallet authorization can be below the quoted cost. It is not a discount and it does not change the position economics.

dUSDC Liquidity Mandates and Funded Outcomes

existing manager collateral applied + max new wallet authorization = strategy capitallive hedge cost + execution headroom = hedge funding ceilingstrategy capital = PLP acquired + live range cost + unused headroom converted to PLP

Hedged dUSDC strategies keep the full capital allocation invested: unused hedge headroom is converted into additional PLP within the same transaction. The manager finishes with no detached idle balance. There is no follow-up refund or reclaim action. A legacy manager_buffer_raw quote field may still be present for response compatibility; it is zero and is not a funded sleeve.

mUSDC

gross wallet debit = server-quoted premium or capital-at-risk amountmanager credit = 0 · execution headroom = 0

The mUSDC deposit response itemizes gross amount, vault fee, net amount, expected shares, and fee basis points. The fee reduces receipt economics; it does not authorize a wallet debit above the server-quoted gross amount.

Current, exact, and currency-bound

Quote Integrity

Quote	Validity	Prepare rule
Basic option	30 seconds	Exact whole-contract quantity is repriced; dUSDC rejects more than 2% price drift
Range Execution	45 seconds	Canonical quote buckets are repriced; dUSDC rejects more than 2% price drift
Liquidity Mandate	90 seconds	Prepare loads the cached quote and requires the same settlement currency
Funded Outcome	90 seconds	Prepare loads canonical allocations and payoff bands and requires the same settlement currency

Liquidity Mandate and Funded Outcome quotes carry settlement_currency. Switching dUSDC/mUSDC after quoting is rejected; request a fresh quote for the new rail. The browser cannot replace canonical bands, quantities, allocations, or autocall observations at prepare time.

A supplied settlement currency must be exactly dUSDC or mUSDC. Unknown values return 400; they are never silently converted to another rail. An omitted currency uses only the documented compatibility default for that endpoint.

Every executable quote id is also bound to its product and prepare route. For public mUSDC opens, POST /api/sim/open/prepare reads only { owner, quote_id }. The server loads product, premium, maximum payout, oracle, forward, expiry, and terminal bands from the short-lived quote registry; extra client-authored payoff fields cannot influence the prepared transaction. Liquidity Mandates and Funded Outcomes continue through their dedicated currency-bound prepare routes.

Live Predict failures are explicit: unavailable oracle pricing returns 503 PREDICT_UNAVAILABLE, stale expiry or quote state returns 409, invalid or off-grid ranges return 400, and insufficient dUSDC vault capacity returns 409 PREDICT_CAPACITY on supported quote routes. Pelagos does not substitute a zero or model-only execution quote.

Discovery is broader than execution

Oracle Index

The Portfolio Oracle Index combines two deployments: Mysten public Predict for discovery/history and Pelagos execution for the configured write path. A public oracle appearing in search does not make it executable through Pelagos.

Layer	Behavior
Archive	Mysten public archive refreshes every five minutes when available
Discovery	Sui GraphQL tails OracleCreated events for both deployments
Live state	Direct object reconciliation refreshes every five seconds
Quoteability	Lifecycle must be live and the latest update must be no more than 30 seconds old
REST catalogue	In-memory archive, default 50 rows, maximum 200 per page
SSE snapshot	Source health, aggregate totals, and at most 64 current live/upcoming records

Search matches oracle ID, Predict object ID, underlying asset, deployment ID or label, lifecycle, and expiry expressed as epoch milliseconds, ISO time, or a UTC date token. Filters support deployment, lifecycle, and underlying; sorting supports expiry ascending, expiry descending, and status.

The index reports grid metadata rather than materializing every boundary: strike(n) = min_strike + n × tick_size. The configured grid contains 100,001 valid boundaries. Contract-valid does not necessarily mean currently mintable or liquid.

Canonical product routes

API Reference

The frontend uses a quote → prepare → wallet sign → confirm workflow. Quote routes establish all executable economics. Prepare endpoints consume the corresponding quote id and return unsigned transaction bytes plus dry-run metadata; they do not sign for the user. The list below covers the current options, volatility, Range Desk, settlement, and oracle surfaces. Exact request and response fields are available from GET /api/docs.

GET/api/options/chainLive full-domain BTC calls and puts with one-contract market prices.

GET/api/options/depthDepth and risk limits for one validated oracle range.

POST/api/options/quoteExact-size, rail-bound option quote; mUSDC terms are registered server-side.

POST/api/options/open/preparedUSDC-only option prepare with fresh repricing and dry-run.

GET/api/predict/vol-surfaceSVI surface: forward, slices, term structure, and strike width.

GET/api/predict/densitySVI-implied density arrays for one execution oracle.

POST/api/predict/strip/previewRail-bound low-level distribution quote constructed by the server.

POST/api/predict/strip/open/preparedUSDC-only low-level distribution prepare from its quote id.

GET/api/vol/surfaceVolatility surface plus realized-volatility context.

POST/api/vol/quoteRail-bound volatility quote; hedge output is indicative only.

POST/api/vol/open/preparedUSDC-only volatility-strip prepare from its quote id.

GET/api/deepbook/strategiesRange Execution strategy catalogue.

GET/api/deepbook/expiriesActive, selectable execution expiries.

POST/api/deepbook/quoteRail-bound Range Execution quote for dUSDC or mUSDC.

POST/api/deepbook/open/preparedUSDC-only Range Execution prepare from its quote id.

GET/api/deepbook/yield/strategiesLiquidity Mandate catalogue.

POST/api/deepbook/yield/quoteCurrency-bound 90-second PLP or reference-payoff quote.

POST/api/deepbook/yield/open/prepareCurrency-bound mandate prepare from an unexpired quote.

GET/api/deepbook/yield/account/:ownerdUSDC PLP shares, manager ranges, and marked account value.

POST/api/deepbook/yield/ranges/exit/prepareOwner-verified dUSDC range exit; proceeds settle in the same PTB.

GET/api/notes/strategiesCapital-at-risk Funded Outcome catalogue and supported currencies.

POST/api/notes/quoteCurrency-bound 90-second capital-at-risk outcome quote.

POST/api/notes/open/prepareOutcome prepare from server-loaded allocations and observations.

POST/api/sim/open/preparePublic mUSDC prepare; request body is only owner + canonical quote_id.

POST/api/sim/confirmConfirm the wallet deposit digest for one prepared mUSDC receipt.

POST/api/sim/settleSettle a confirmed mUSDC receipt from authoritative observations.

GET/api/sim/positions/:ownermUSDC receipt lifecycle for one wallet.

POST/api/predict/confirmVerify a wallet-submitted dUSDC transaction digest.

GET/api/predict/oracle-indexPaginated and searchable multi-deployment oracle index.

GET/api/predict/oracle-index/streamFive-second SSE snapshot with bounded live/upcoming records.

GET/api/predict/oracle-index/:oracleIdOne oracle with deployment provenance and live state.

Operational boundaries

Testnet Limits

dUSDC faucets and the managed Predict vault have finite balances and risk capacity.
mUSDC is an isolated test asset; its receipts are not DeepBook positions.
Oracle archive snapshots and event cursors are held in memory and reset when the backend container is replaced.
The public archive can be degraded while the Pelagos execution deployment remains readable directly from Sui.
Only currently quoteable configured oracles can support a transaction; the full Oracle Index is a discovery surface.
PLP NAV can fall and withdrawals can be liquidity-constrained while liabilities remain open. No yield, APY, repayment floor, or principal protection is guaranteed.
Funded Outcome names and modeled minimums describe payoff schedules, not protected deposits; loss can reach the disclosed theoretical minimum.
Autocall is mUSDC-only, and settlement requires authoritative observations; the opening forward is not a fallback settlement value.
All routes and package IDs described here are testnet-specific and can change on redeployment.

Repository references

Products · Architecture · DeepBook integration · Testnet deployment