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 & Path | Request | Response |
|---|
GET /auth/nonce | None | { 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/session | Header Authorization: Bearer <token> | { wallet, expiresAt } |
POST /auth/logout | Header Authorization: Bearer <token> | 204 No Content |
Health, stats, mints, and pairs
| Method & Path | Purpose | Key response fields |
|---|
GET /health | Service readiness and cluster info | status (ready \ | waiting \ | fixture), cluster, programId, feeBps, feeRecipient, asOf |
GET /v1/stats | Protocol-wide indexed metrics | clearedFills, medianFinalityMs, activeRings, shieldedCommitments, openHiddenOrders, supportedMintsCount, feeBps, feeRecipient, buybackStatus (dormant \ | active), meraMint, asOf |
GET /v1/mints | Registered supported mints | items: MintInfo[] (symbol, name, mint, decimals, standard, referencePriceUsd), asOf |
GET /v1/pairs | Active trading pairs | items: PairInfo[] (id, label, baseSymbol, quoteSymbol, baseMint, quoteMint, baseDecimals, quoteDecimals, referencePrice, feeBps), asOf |
Custom Rings
| Method & Path | Request body | Response |
|---|
GET /v1/rings | None | { items: RingSummary[], asOf } |
GET /v1/rings/:ringId | None | RingDetail (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 & Path | Request / Query | Response |
|---|
GET /v1/balances/:wallet | Query 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 & Path | Request body | Response |
|---|
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 & Path | Request / Query | Response |
|---|
GET /v1/orders | Query 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/:wallet | Query 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 & Path | Request body | Response |
|---|
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/quotes | None | RfqRequestResponse (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 & Path | Request / Query | Response |
|---|
GET /v1/fills | Query 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/:tvk | URL-encoded tvk param | VerifiedReceiptResponse |
POST /v1/transactions/submit | { id, signedTransactionBase64?, signature? } | TxSubmissionResponse (id, status, signature, slot, finalityMs, settlementId, tvk, errorMessage, updatedAt) |
GET /v1/transactions/:id | None | TxSubmissionResponse |
Transaction build response (`TxBuildResponse`)
Every */build endpoint returns:
{
"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:
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 name | Payload 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.