Getting Started

Leviathan Prime API

The Leviathan Prime API is the programmatic interface to our prime brokerage layer for prediction markets and perpetual futures. Manage positions, execute trades, monitor margin, and pull reports — all over HTTPS with JSON responses.

The base URL for all API requests is:

https://api.leviathan.global/v1

The API is currently in private beta. Request access at contact@leviathan.global to receive credentials.

Getting Started

Authentication

All API requests require an API key passed as a bearer token in the Authorization header. Prime API keys are issued after onboarding and KYB — contact us to get started.

Request headers

Header	Description
Authorization required	Bearer token. Format: `Bearer lev_live_xxxxxxxxxxxxxxxx`
Lev-Version	API version to use. Defaults to `2026-04-01` if omitted.
Content-Type	Required for POST requests: `application/json`

import requests

headers = {
    "Authorization": "Bearer lev_live_xxxxxxxxxxxxxxxx",
    "Lev-Version":   "2026-04-01",
}

response = requests.get(
    "https://api.leviathan.global/v1/intelligence/positions",
    headers=headers,
)
print(response.json())

const response = await fetch(
  "https://api.leviathan.global/v1/intelligence/positions",
  {
    headers: {
      Authorization: "Bearer lev_live_xxxxxxxxxxxxxxxx",
      "Lev-Version": "2026-04-01",
    },
  }
);
const data = await response.json();
console.log(data);

curl https://api.leviathan.global/v1/intelligence/positions \
  -H "Authorization: Bearer lev_live_xxxxxxxxxxxxxxxx" \
  -H "Lev-Version: 2026-04-01"

Getting Started

Quickstart

Install the Python SDK, authenticate, and fetch your open positions in under two minutes.

# Install the SDK
# pip install leviathan-sdk

from leviathan import Leviathan

client = Leviathan(api_key="lev_live_xxxxxxxxxxxxxxxx")

# View all open positions
positions = client.intelligence.positions()
for p in positions:
    print(f"{p.symbol} {p.side} — PnL: {p.pnl}")

# Execute a trade
trade = client.intelligence.execute(
    symbol="TRUMP-WIN",
    side="buy",
    notional_usdc="50000",
)
print(f"Trade executed: {trade.id}")

// npm install @leviathan/sdk

import { Leviathan } from "@leviathan/sdk";

const client = new Leviathan({ apiKey: "lev_live_xxxxxxxxxxxxxxxx" });

// View all open positions
const positions = await client.intelligence.positions();
positions.forEach(p =>
  console.log(`${p.symbol} ${p.side} — PnL: ${p.pnl}`)
);

// Execute a trade
const trade = await client.intelligence.execute({
  symbol: "TRUMP-WIN",
  side: "buy",
  notionalUsdc: "50000",
});
console.log(`Trade executed: ${trade.id}`);

Core Concepts

Margin Portfolio

Trade on margin with increased buying power. Available to selected users who have traded over $1M in volume.

Margin Portfolio lets you open positions that exceed your cash deposit. Leviathan adjusts the value of your positions based on their risk profile and monitors your account health in real time.

Margin Portfolio is available to selected users who have traded over $1M in lifetime volume through Leviathan Prime. If you are interested, reach out at contact@leviathan.global.

How It Works

When you deposit funds and open positions, Leviathan continuously computes a Margin Health ratio for your account. This ratio tells you whether your portfolio is adequately collateralized.

Margin Health	Status
Above 1.5	Your account is healthy. Trade normally.
Between 1.0 and 1.5	Caution. Your margin cushion is thin.
Below 1.0	Margin call. You must deposit funds or close positions to avoid liquidation.

Key Concepts

Deposit

The cash you have deposited into your account. This is your base collateral. The collateral is the same across Polymarket and Kalshi.

Used Margin

The amount of collateral borrowed from Leviathan to open your positions. If your deposit fully covers your cashflows, your used margin is zero. Otherwise, used margin reflects the shortfall.

Adjusted Equity

A conservative estimate of what your portfolio is worth. Leviathan applies risk adjustments to each position individually. Positions with higher uncertainty (events trading near 50/50) are valued more conservatively because the outcome is less predictable. Positions that expire sooner are valued more conservatively because they have not had time to season. Adjusted Equity also includes a diversification adjustment: a portfolio concentrated in a single position will have lower Adjusted Equity than a well-diversified one.

Available Margin

The difference between your Adjusted Equity and your Used Margin. This is how much room you have to open new positions. If it reaches zero, you cannot open new positions without depositing more funds or closing existing ones.

Margin Health

The ratio of your Adjusted Equity to your Used Margin. This is the single number that determines your account status.

Margin Requirements

Leviathan enforces two margin thresholds:

Threshold	Value	Behavior
Initial Margin Requirement	`1.2`	To open a new position, your projected Margin Health after the trade must remain above 1.2. If the trade would push your health below 1.2 it will be rejected. This buffer ensures you do not enter a position already close to a margin call.
Maintenance Margin Requirement	`1.0`	At all times, your Margin Health must stay above 1.0. If market movements cause your health to drop below 1.0, a margin call is triggered and you must deposit funds or close positions to restore it.

Reading the Dashboard

Your Margin Portfolio dashboard shows four components:

Component	Description
Margin Health Gauge	A color coded indicator showing your current margin health at a glance. Green means healthy, yellow means caution, red means action required.
Account Summary	Your Deposit, Used Margin, Adjusted Equity, and Available Margin — the four numbers that define your account state.
Position Breakdown	Each open position with its notional value and its contribution to your Adjusted Equity, sorted by contribution so you can see which positions are helping your margin the most.
Trade Simulation	A preview of how your Margin Health will change before you confirm a trade, shown directly on the order form.

Simulations

Before placing a trade, the order form shows your projected Margin Health after the trade. As you adjust the position size, the projection updates in real time. If the projected margin health drops into the warning or danger zone, you will see it before you confirm.

From the portfolio view you can also simulate:

Simulation	What it shows
Close a position	How your Margin Health improves if you close a specific position.
Add funds	Exactly how much you need to deposit to restore a healthy margin.

Margin Calls

If your Margin Health falls below 1.0, you will receive a notification. You have two options:

Option	Effect
Deposit additional funds	Increases your collateral base and raises your Margin Health.
Close positions	Reduces your margin usage and raises your Margin Health.

If you do not act, Leviathan may liquidate positions to bring your account back to a healthy state. Positions are liquidated at Leviathan's discretion to minimize the cost of liquidation.

Core Concepts

Account Types

Two ways to trade on Leviathan Prime: let us manage your funds, or connect your own exchange account.

Custodial

Leviathan manages everything for you. We create the exchange accounts, set up the wallets, and execute trades on your behalf. You do not need your own Kalshi account or Polymarket wallet. Custodial accounts also support leverage.

Hands off trading	No exchange accounts or wallets to manage
Leverage	Access leverage on your positions

Non-Custodial

You bring your own exchange account. Connect your Kalshi API key or Polymarket wallet and Leviathan tracks your positions. Your funds stay on the exchange — we never touch them.

Full control	Your keys, your funds
Direct access	Manage funds directly on the exchange

Comparison

	Custodial	Non-Custodial
Who holds funds	Leviathan	You
Deposits	Card or bank transfer	On the exchange directly
Withdrawals	Request through Leviathan	On the exchange directly
Exchange credentials	We set them up	You provide your own
Leverage	Yes	No
Best for	Users who want it simple	Users who want full control

Prime API

Leviathan Prime

The Prime API is the programmatic interface to Leviathan's prime brokerage layer for prediction markets and perpetual futures. Access requires an Intelligence-scoped API key, which is issued after onboarding and KYB.

Intelligence endpoints require a credit facility to be established. Contact contact@leviathan.global to begin onboarding.

Positions

GET/intelligence/positions

Returns all open positions across prediction market and perpetual venues, including notional, side, unrealized P&L, and margin utilization.

Response

{
  "account_id": "acct_9f3a2bc",
  "margin_utilization": "0.62",
  "positions": [
    {
      "symbol":    "BTC-PERP",
      "venue":     "leviathan",
      "side":      "long",
      "notional":  "2840000",
      "pnl":       "18420.00",
      "opened_at": "2026-04-22T14:30:00Z"
    },
    {
      "symbol":    "TRUMP-WIN",
      "venue":     "polymarket",
      "side":      "long",
      "notional":  "480000",
      "pnl":       "11050.00",
      "opened_at": "2026-04-20T09:15:00Z"
    }
  ]
}

Execute Trade

POST/intelligence/execute

Executes a trade through the prime brokerage layer. Leviathan routes the order to the optimal venue, settles against your credit facility, and updates your position in real time.

Body field	Description
symbol required	Instrument identifier. Example: `TRUMP-WIN`, `BTC-PERP`
side required	string `buy` or `sell`
notional_usdc required	string Trade size in USDC notional
venue	string Preferred venue. Omit for smart routing.
slippage_bps	integer Max acceptable slippage in basis points. Default `50`.

Margin

GET/intelligence/margin

Returns current margin utilization, available credit, and a breakdown by venue and asset class.

Reports

GET/intelligence/reports

Generates a performance or operational report for a given date range. Returns a signed download URL valid for 15 minutes.

Parameter	Description
type required	`performance`, `positions`, or `transactions`
from required	ISO 8601 start date. Example: `2026-04-01`
to required	ISO 8601 end date
format	`csv` (default) or `json`

Real-Time

WebSocket Streams

Subscribe to live order book updates, trade feeds, and account events over a persistent WebSocket connection.

Connection

import asyncio, json, websockets

async def stream():
    uri = "wss://stream.leviathan.global/v1"
    async with websockets.connect(uri) as ws:
        # Authenticate
        await ws.send(json.dumps({
            "op": "auth",
            "key": "lev_live_xxxxxxxxxxxxxxxx"
        }))
        # Subscribe to BTC-PERP order book
        await ws.send(json.dumps({
            "op": "subscribe",
            "channel": "orderbook",
            "market_id": "BTC-PERP"
        }))
        async for message in ws:
            print(json.loads(message))

asyncio.run(stream())

const ws = new WebSocket("wss://stream.leviathan.global/v1");

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({ op: "auth", key: "lev_live_xxxxxxxxxxxxxxxx" }));
  ws.send(JSON.stringify({
    op: "subscribe",
    channel: "orderbook",
    market_id: "BTC-PERP",
  }));
});

ws.addEventListener("message", (e) => {
  console.log(JSON.parse(e.data));
});

Available channels

Channel	Description
orderbook	Full order book snapshot and incremental updates
trades	Public trade feed for a market
account	Private feed: order fills, cancellations, and position changes
positions	Real-time position and margin updates (Intelligence only)

Reference

Errors

The API returns standard HTTP status codes. Error bodies include a machine-readable code and a human-readable message.

Status	Code	Meaning
400	`invalid_params`	A required parameter is missing or malformed
401	`unauthorized`	API key missing or invalid
403	`forbidden`	Key does not have permission for this endpoint
404	`not_found`	Resource does not exist
409	`duplicate_order`	client_order_id already used
422	`insufficient_margin`	Order would exceed your credit facility
429	`rate_limited`	Too many requests. See Rate Limits.
500	`internal_error`	Something went wrong on our side

Reference

Rate Limits

Rate limits are applied per API key. Exceeding a limit returns a 429 response. The Retry-After header contains the number of seconds to wait.

Endpoint group	Limit
Market data (read)	300 requests per minute
Order management	60 requests per minute
Yield (deploy/withdraw)	10 requests per minute
Prime (execute)	30 requests per minute
WebSocket connections	5 concurrent per key

Enterprise rate limit increases are available for institutional accounts. Contact us to discuss higher throughput requirements.