mrgin Protocol Docs

Introduction

mrgin is a cross-margined trading platform on Solana. It unifies two product lines — leveraged crypto markets (SOL, BTC, ETH) and binary sports predictions — inside a single USDC collateral pool.

The core idea is simple: winnings from one product can cushion drawdowns in the other. A profitable sports bet increases your free collateral for markets; a winning market position does the same for your sports exposure. One account, one equity number, shared risk.

• Up to 20× leverage on USDC-settled markets
• Binary YES/NO sports markets with shared vault collateral
• Hybrid order book — fast off-chain matching, on-chain settlement
• Permissionless liquidations when portfolio health falls below threshold
• $5,000 demo balance for every new account

Getting Started

No wallet or deposit is required to explore the platform. Create an account and you receive demo USDC instantly.

System Architecture

mrgin follows a layered architecture: on-chain programs hold collateral and enforce rules; off-chain services handle matching, indexing, and real-time data; the web app is the user interface.

┌─────────────────────────────────────────────────────┐
│                   Web Application                    │
│         Markets · Sports · Portfolio · History       │
└────────────────────────┬────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   REST + WS API    Account Service   Price Feeds
   (markets, book)  (auth, demo state) (external)
         │               │               │
         └───────────────┼───────────────┘
                         ▼
              Off-chain Matching Engine
              (order book, fill routing)
                         │
                         ▼
              Solana Programs (devnet)
    ┌────────────────────┼────────────────────┐
    │   Market Engine    │  Prediction Markets │
    │   Cross-Margin Vault (shared USDC)      │
    └─────────────────────────────────────────┘

Core services

Markets & Trading

mrgin supports multiple USDC-settled markets. Each market has its own order book, funding rate, and mark price sourced from external oracle feeds.

Supported markets

Order types

• Market orders — filled immediately at the best available price (AMM backstop when book is thin)
• Limit orders — rest in the book until matched or cancelled
• All orders require sufficient free collateral before submission

Margin calculation

Required margin  =  notional / leverage
Notional         =  size × entry price
Free collateral  =  total equity − locked margin
Max position     =  free collateral × leverage

Funding rate

Perpetual markets use an hourly funding rate to keep the mark price anchored to the spot oracle. When funding is positive, longs pay shorts; when negative, shorts pay longs. The rate is displayed on the Markets terminal header.

Cross-Margin Vault

Instead of siloed margin per product, mrgin uses a single vault per user. Every deposit, position, and bet updates the same equity pool.

Equity formula

Total equity     =  free balance + locked collateral + unrealized PnL
Portfolio health =  free collateral / locked notional   (in basis points)
Liquidation      =  health drops below 500 bps (5%)

How cross-margin helps

• Sports winnings increase free collateral available for new market positions
• Profitable market positions cushion sports bet drawdowns
• One liquidation check covers the entire portfolio, not individual products
• No manual transfers between products — collateral flows automatically

Example scenario

You deposit $5,000 demo USDC. You open a $1,000-collateral SOL long at 5× and place a $250 YES bet on an NBA game. Your locked collateral is $1,250; free balance is $3,750. If the bet wins $422, your equity rises and your portfolio health improves — even if the SOL position is temporarily underwater.

Sports Predictions

Binary prediction markets let you bet YES or NO on sporting events. Odds are pool-based: your payout depends on the ratio of YES vs NO liquidity at entry.

• Select an event from the Sports page (NBA, IPL, NFL, and more)
• Choose YES or NO and enter your stake in USDC
• Collateral locks from your shared vault — same balance as Markets
• When the market resolves, winners receive their share of the pool pro-rata
• Lost bets forfeit locked collateral back to the pool

Because sports bets share the cross-margin vault, a winning bet can keep your account healthy enough to avoid liquidation on an underwater market position.

Order Matching

mrgin uses a hybrid central-limit order book (CLOB). Resting limit orders are matched off-chain for speed; the result is settled on-chain for security and finality.

Matching flow

• User submits an order via the web terminal
• Engine validates collateral and adds the order to the book
• When bid ≥ ask, a fill is generated at the maker's price
• Fill is settled on-chain — position PDAs and vault balances update
• Fill event is indexed and broadcast to connected clients via WebSocket

Price sources

Mark prices for charts, order books, and liquidations are sourced from major exchange feeds (Binance spot). The oracle price anchors funding calculations and acts as the AMM backstop reference when the book has no resting liquidity.

Liquidations & Risk

When portfolio health falls below 500 basis points (5%), the account becomes eligible for liquidation. Liquidations are permissionless — any participant can trigger them and earn a fee.

Liquidation triggers

• Portfolio health < 5% — automatic liquidation eligible
• Adverse price move erodes unrealized PnL below maintenance margin
• Multiple losing positions and bets compound locked collateral usage

Liquidation waterfall

• Step 1 — Forfeit or close losing prediction bets (easier to unwind)
• Step 2 — Close largest market positions until health is restored
• Step 3 — Liquidator receives a fee (50 bps of notional) as incentive

Risk management tips

• Monitor unrealized PnL in the Positions panel and account dropdown
• Lower leverage on volatile markets (BTC moves differently than SOL)
• Cross-margin helps, but correlated losses across products still increase risk
• Use the History tab to review closed trades and refine position sizing

Demo Accounts

Every new account starts with $5,000 USDC in demo funds. No wallet connection, no deposit, no KYC — just sign up and trade.

What gets saved

• Free balance and locked collateral
• All open market positions and sports bets
• Full trade history with entry, exit, PnL, and ROE
• Account state syncs to the cloud when signed in — access from any device

Reset

You can reset your demo account to $5,000 at any time from the account dropdown in the header. This clears all positions, bets, and history — useful for testing strategies from a clean slate.

Guest mode

You can also trade without signing in — state is stored locally in your browser only. Sign in to persist your account to the cloud.

API Reference

The public REST API exposes market data, order books, portfolio summaries, and prediction markets. A WebSocket endpoint streams real-time fills, book updates, and liquidations.

Markets

Portfolio

Sports

WebSocket

Connect to /stream

Channels:
  fills         — { price, size, side, market, timestamp }
  book-update   — { market, bids[], asks[] }
  liquidations  — { wallet, notional, fee }

Base URL is configured via environment variable in your deployment. Demo account auth (sign-up, login, state sync) is handled by the web application directly.

Data Flow

Order lifecycle

User                Web App              Engine              Chain
 │                     │                    │                   │
 │── place order ─────►│                    │                   │
 │                     │── validate margin ►│                   │
 │                     │                    │── match fill ────►│
 │                     │                    │◄── confirmed ──────│
 │                     │◄── update UI ──────│                   │
 │◄── toast + position │                    │                   │

Price update → liquidation check

Oracle Feed ──► Mark Price Update ──► Health Recalc
                                              │
                                    health < 5% ?
                                              │
                              Yes ──► Liquidation Bot ──► On-chain Close
                              No  ──► Continue monitoring

Cross-margin equity update

• Every price tick recalculates unrealized PnL on open market positions
• Resolved sports bets update realized PnL immediately
• Free collateral = equity minus locked margin across all products
• UI polls and WebSocket events keep the account dropdown live

FAQ

Do I need a Solana wallet?

No — demo trading works with just an email account. Connect a wallet optionally to view on-chain portfolio data on the Portfolio tab.

Is this real money?

Not yet. Demo accounts use simulated USDC on devnet. Treat all balances and PnL as practice only.

What markets can I trade?

SOL, BTC, and ETH leveraged markets, plus binary sports predictions. All settle in USDC from one vault.

How does cross-margin work?

One pool of collateral backs every product. Winnings in sports can offset market losses and vice versa — no manual transfers needed.

Where is my data stored?

Signed-in accounts are stored securely in a cloud database. Guest sessions use browser local storage only.

What happens when I get liquidated?

Positions and bets are closed automatically to restore portfolio health. The liquidator earns a fee. You can review the event in your history once on-chain indexing is connected.