Skip to main content

API overview

The Opshuns API is an Elixir/Phoenix JSON service. Base URL for this docs build (set DOCS_API_URL in env):

https://api.testnet.opshuns.com

WebSockets use the same host on /socket (Phoenix Channels).

Prefer @opshuns/sdk (../sdk) for typed clients, sessions, and signing. See TypeScript SDK.

What the API does​

AreaPurpose
AuthSIWE login → bearer token; maker / taker org keys; explore gate for analytics. auth, explore auth
Options RFQTakers open short quote windows; makers post EIP-712 signed offers (FillMatched on-chain)
On-chain fillsAlso FixedPackage, Dutch auction, and Authority. See fill modes
CLOBResting book + bilateral fillMatched: CLOB
PubsubRegister for chain-scoped request feeds and private maker streams
NetworksPublic registry of chain IDs, RPCs, and contract addresses
Indexer / portfolioOn-chain CLOB discovery, status, and wallet snapshots (Postgres-backed)
OrdersRecord CLOB orders and issue exclusive fills
Borrow RFQComing soon. Borrowers post collateral; lenders post signed loan offers

Quote sessions themselves are ephemeral (in-memory processes). Config (networks, maker orgs, keys) lives in Khepri. Indexer data lives in Postgres.

Conventions​

  • JSON request/response bodies
  • Ethereum addresses are normalized lowercase 0x…
  • Large integers (amounts, strikes, nonces) are often decimal strings
  • Authenticated routes: Authorization: Bearer <token-or-maker-key>
  • Errors: { "error": "…" } with appropriate HTTP status

Endpoint map (high level)​

Public​

MethodPathNotes
GET/api/healthLiveness
GET/api/login/nonceSIWE challenge
POST/api/loginExchange signed SIWE message for token
GET/api/networksChains + contracts
GET/api/payment-tokensPayment token metadata (testnet faucet, quote defaults)
GET/api/default-premium-tokensDefault premium tokens
GET/api/recommended-min-notionalSuggested minimum notionals
GET/api/landing-page-settingsTrading landing CMS (networks, premium + payment tokens)
GET/api/filler-page-settingsMaker/filler page CMS content
GET/api/bond-requirementsPremium / exclusive-fill bond minima per token
POST/api/quoteCreate options RFQ (no login). Spread payloads
GET/api/quote/:idPoll quote (stream token required)
POST/api/ordersCreate a CLOB order record. Orders
GET/api/indexer/statusIndexer health
GET/api/indexer/coresDiscovered CLOB addresses
GET/api/portfolio/:addressPortfolio across networks (?chain_id= optional)

Explore gate (SIWE + Turnstile/Origin, or taker-delegate JWT)​

See Explore & loan data auth.

MethodPathNotes
GET/api/explore/clobs/:addressIndexed CLOB snapshot
POST/api/explore/clobs/:address/streamMint explore_clob_stream token
GET/api/clob/:address/bookResting depth
GET/api/clob/:address/activityBucketed posted vs filled
GET/api/clob/:address/fillsPaginated fills
GET/api/clob/:address/summaryMetric cards
GET/api/explore/loans/summaryLoan explorer aggregates
GET/api/explore/loans/at-riskLiquidatable / near-liquidation
GET/api/explore/loans/recentRecent LoanOpened events
GET/api/explore/loans/activityBucketed opened / liquidated / repaid
POST/api/explore/loans/streamMint explore_loan_stream token

Authenticated​

MethodPathNotes
GET/api/meSession / maker role (admin / owner / manager / member)
POST/api/pubsub/premiumMaker pubsub registration
POST/api/pubsub/freemiumFreemium pubsub registration
POST/api/quote/:idMaker options offer
POST/api/exclusive-fillMaker exclusive fill over order ids

Maker org admin​

MethodPathNotes
GET/api/maker/keysList member keys
POST/api/maker/keysIssue a member key (signed admin action)
DELETE/api/maker/keys/:idRevoke a key (signed admin action)
PUT/api/maker/organizationTransfer org admin (signed transfer_admin)

Coming soon (Borrow)​

Borrow is not live. These routes are the planned surface and may change.

MethodPathNotes
POST/api/margin/quoteCreate Borrow RFQ (planned, no login)
GET/api/margin/quote/:idPoll Borrow quote (stream token)
POST/api/margin/quote/:idLender Borrow offer (maker auth)
POST/api/margin/quote/:id/selectBorrower selects a loan offer

See Respond to Borrow RFQs. Protocol rates: Borrow fees.

Deprecated​

Legacy announcement quotes (/api/quotes*) return 410 Gone. Use /api/quote.

POST /api/premium/activate returns 410 Gone (maker orgs replaced premium bonds for API access).

Next​