Mera
ExecutionInstant confidential swapsClear from encrypted balances in one 150ms slot.Hidden-size limit ordersLock encrypted size in a private escrow PDA.Sealed RFQ block tradesRequest signed quotes without leaking size.
Vault & AuditShielded vault & keysDeposit SOL, SPL, or Token-2022 into a Ring.Viewing key verifierDecrypt and prove a single settled fill.
Docs/Protocol & Reference
5 min read

REST & WebSocket API Reference

Complete HTTP REST, SIWS authentication, and SSE event stream reference for Mera's API and matching relay.

Mera's API and matching relay (@mera/contract v0.1.0, OpenAPI 3.1) builds unsigned Solana v0 transactions, coordinates sealed RFQ quotes, indexes hidden-order price bands, verifies Transaction Viewing Keys, and streams live events over Server-Sent Events (SSE).

Base URL and conventions

  • Local default: http://127.0.0.1:36102
  • All /v1/* routes enforce a write rate limit (120 requests per window) and return JSON validated by @mera/contract zod schemas.
  • Base-unit token amounts (PositiveU64, U64, BaseUnits) are encoded as decimal strings to avoid JavaScript floating-point precision loss.
  • Pagination query parameters: cursor (optional string) and limit (integer). Paginated responses return { items, nextCursor, asOf }.
  • Every error returns the unified envelope { error: { code, message, retryable, stage, fieldErrors?, programError?, retryAfterSeconds?, requestId? } }. See Error Codes.

Sign-In With Solana (SIWS) authentication

Mera mounts SIWS routes under /auth using header transport (Authorization: Bearer <token>), with statement "Sign in to Mera Dark Execution":

Method & PathRequestResponse
GET /auth/nonceNone{ input: { domain, statement, uri, version, chainId, nonce, issuedAt, expirationTime }, nonceToken }
POST /auth/verify{ input, output, nonceToken } (signed SIWS proof){ wallet, expiresAt, token } (session TTL 30 days, nonce TTL 5 minutes)
GET /auth/sessionHeader Authorization: Bearer <token>{ wallet, expiresAt }
POST /auth/logoutHeader Authorization: Bearer <token>204 No Content

Health, stats, mints, and pairs

Method & PathPurposeKey response fields
GET /healthService readiness and cluster infostatus (ready \waiting \fixture), cluster, programId, feeBps, feeRecipient, asOf
GET /v1/statsProtocol-wide indexed metricsclearedFills, medianFinalityMs, activeRings, shieldedCommitments, openHiddenOrders, supportedMintsCount, feeBps, feeRecipient, buybackStatus (dormant \active), meraMint, asOf
GET /v1/mintsRegistered supported mintsitems: MintInfo[] (symbol, name, mint, decimals, standard, referencePriceUsd), asOf
GET /v1/pairsActive trading pairsitems: PairInfo[] (id, label, baseSymbol, quoteSymbol, baseMint, quoteMint, baseDecimals, quoteDecimals, referencePrice, feeBps), asOf

Custom Rings

Method & PathRequest bodyResponse
GET /v1/ringsNone{ items: RingSummary[], asOf }
GET /v1/rings/:ringIdNoneRingDetail (RingSummary plus members: RingMemberEntry[])
POST /v1/rings/build`{ authority, name, mode: 'confidential' \'anonymous', allowlistEnabled?, auditorPubkey? }`TxBuildResponse (action: "create_ring")
POST /v1/rings/:ringId/members/build{ authority, member, allowed, frozen? }TxBuildResponse (action: "set_ring_member")

Shielded balances and vault transfers

Method & PathRequest / QueryResponse
GET /v1/balances/:walletQuery ringId (default ring-default)WalletBalancesResponse (wallet, ringId, viewingKeyFingerprint, balances: MintBalanceEntry[], notes: CommitmentNoteSummary[], asOf)
POST /v1/shield/deposit/build{ wallet, ringId, mint, amount, commitment? }TxBuildResponse (action: "deposit_shielded")
POST /v1/shield/withdraw/build{ wallet, ringId, mint, amount, recipient?, noteId? }TxBuildResponse (action: "withdraw_shielded")

Instant confidential swaps

Method & PathRequest bodyResponse
POST /v1/swap/quote`{ wallet, ringId, pairId, side: 'buy' \'sell', inputAmount, slippageBps? } (slippageBps 1..500, default 50`)SwapQuoteResponse (quoteId, inputMint, outputMint, inputAmount, outputAmount, minOutputAmount, executionPrice, feeBps, feeAmount, maker, expiresAt, 25s TTL)
POST /v1/swap/build{ wallet, quoteId }TxBuildResponse (action: "settle_confidential_swap", cosigned: true)

Hidden-size limit orders

Method & PathRequest / QueryResponse
GET /v1/ordersQuery ringId?, pairId?, status? (open \filled \cancelled \expired \all), cursor?, limit?HiddenOrdersPage of PublicHiddenOrder (exposes priceBand, limitPrice, sizeCommitment, status, expirySlot; hides plaintextSize and maker)
GET /v1/orders/mine/:walletQuery ringId?{ wallet, items: MyHiddenOrder[], asOf } (includes maker and plaintextSize)
POST /v1/orders/place/build{ wallet, ringId, pairId, side, limitPrice, size, expirySlots? } (expirySlots 50..500000, default 1200)TxBuildResponse (action: "place_hidden_order", meta.orderId)
POST /v1/orders/:orderId/cancel/build{ wallet }TxBuildResponse (action: "cancel_hidden_order")
POST /v1/orders/:orderId/fill/build{ wallet, counterpartyAmount? }TxBuildResponse (action: "fill_hidden_order")

Sealed RFQ block trades

Method & PathRequest bodyResponse
POST /v1/rfq/request{ wallet, ringId, pairId, side, size, ttlSeconds? } (ttlSeconds 5..120, default 30)RfqRequestResponse (requestId, envelopeHash, status, quotes: SealedRfqQuote[], expiresAt, createdAt)
GET /v1/rfq/:requestId/quotesNoneRfqRequestResponse (live quote list and status)
POST /v1/rfq/:requestId/accept/build{ wallet, quoteId }TxBuildResponse (action: "settle_sealed_rfq", cosigned: true)

Fills, receipts, and transaction submission

Method & PathRequest / QueryResponse
GET /v1/fillsQuery ringId?, wallet?, cursor?, limit?FillsPage of SettledFillSummary (settlementId, ringId, pairId, mode, side, executionPrice, commitmentHash, tvkHint, tvk, slot, finalityMs, signature, settledAt)
POST /v1/receipts/verify{ tvk } (16..2048 chars)VerifiedReceiptResponse (verified, onchainMatched, trade details, fee details, commitmentHash, nullifierHash, slot, finalityMs, signature)
GET /v1/receipts/:tvkURL-encoded tvk paramVerifiedReceiptResponse
POST /v1/transactions/submit{ id, signedTransactionBase64?, signature? }TxSubmissionResponse (id, status, signature, slot, finalityMs, settlementId, tvk, errorMessage, updatedAt)
GET /v1/transactions/:idNoneTxSubmissionResponse

Transaction build response (`TxBuildResponse`)

Every */build endpoint returns:

json
{
  "id": "tx_9f8a7b6c5d4e3f2a",
  "action": "settle_confidential_swap",
  "transactionBase64": "AQAAAA...",
  "blockhash": "7xK...",
  "lastValidBlockHeight": 298412,
  "estimatedFeeLamports": "5000",
  "cosigned": true,
  "expiresAt": "2026-11-22T09:10:00.000Z"
}

When cosigned is true, sign the deserialized VersionedTransaction with the taker wallet first and pass signedTransactionBase64 to POST /v1/transactions/submit; the relay attaches the maker co-signature before sending.

Live event stream (SSE)

Connect to GET /v1/events (optional ?ringId=<ringId> and Last-Event-ID header for replay) using EventSource:

ts
const es = new EventSource('http://127.0.0.1:36102/v1/events?ringId=ring-default')

es.addEventListener('rfq_quote', (event) => {
  const data = JSON.parse(event.data)
  console.log('New RFQ quote:', data.requestId, data.quoteId)
})

es.addEventListener('fill_settled', (event) => {
  const data = JSON.parse(event.data)
  console.log('Settled fill:', data.settlementId, data.finalityMs, 'ms')
})
Event namePayload fields
ring_created{ ringId }
balance_updated{ wallet, ringId }
order_updated{ orderId, ringId, status }
rfq_quote{ requestId, ringId, pairId, quoteId }
fill_settled{ settlementId, ringId, pairId, finalityMs, slot }

RPC relay

In chain mode, the backend also mounts a CORS-enabled HTTP Solana RPC relay at /rpc allowing solana-client and Content-Type headers for browser Connection calls.