Perpetuals

Perpetuals let you take a leveraged position on a market’s price without an expiry. On Murmo they live as proposals inside a group: a proposal is a single LONG or SHORT idea on a Phoenix RISE perp market, and each member who joins runs their own position under it. You put up USD collateral, pick a multiplier, and the position tracks the market with live mark price, unrealized PnL, and funding.

Leverage cuts both ways. At 5×, a −20% move in the underlying wipes out your collateral and the position can be liquidated — you lose what you put in. Size positions you can afford to lose, and watch liquidationPriceUsd.

Perpetuals are restricted in some jurisdictions and may require identity verification. If a call returns 403, see Eligibility & geo restrictions.

Two IDs: proposalId vs assignmentId

This is the one thing to get straight before you start. Perp routes are keyed by one of two IDs, and they are not interchangeable.

ID	What it is	Where it comes from
`proposalId`	The shared trade idea (the LONG/SHORT on a market).	The `id` field of a `PerpProposal`.
`assignmentId`	Your position under a proposal.	The `id` field of a `PerpPosition` (it is the assignment id).

CREATE, JOIN, and CLOSE-proposal are keyed by proposalId. REDUCE and CLAIM act on a single position and are keyed by assignmentId. A PerpPosition.id and its assignment id are the same value — use it wherever a route says {assignmentId}.

Route	Keyed by	Action
`POST /perps/proposals`	— (creates one)	Open a new proposal + your first position.
`POST /perps/proposals/{id}/increase`	`proposalId`	Join an existing proposal (inherits its side).
`POST /perps/proposals/{id}/close`	`proposalId`	Creator closes the proposal.
`POST /perps/positions/{assignmentId}/reduce`	`assignmentId`	Reduce or fully close your position.
`POST /perps/positions/{assignmentId}/claim`	`assignmentId`	Acknowledge a take-profit close and drain proceeds.

Setup

Same base URL, key, and money rules as everywhere else in the API.

export MURMO_API_KEY="murmo_your_key_here"
export MURMO_BASE="https://api.alpha-labs.trade"

Every monetary value on the wire is a full-precision decimal string in USD. collateralUsd and leverage are sent as numeric strings ("25.00", "5") — never numbers, never raw base units. Base-lot quantities are strings too. See Money & precision.

Lifecycle

Pick a market

List the tradable perp markets and read a live price to size your entry. GET /api/v1/perps/markets (or /markets/{symbol} for one).

Open a position

POST /api/v1/perps/proposals creates a proposal and opens your position in one call — pick side, collateralUsd, leverage, and optional stopLossPct / takeProfitPct brackets. To back an idea someone else posted, POST /perps/proposals/{id}/increase instead.

Monitor PnL

GET /api/v1/perps/positions?filter=active returns your open positions with live markPrice-derived value, unrealizedPnlUsd, funding, and liquidationPriceUsd. For low-latency price ticks, subscribe to market data over WebSocket.

Reduce or close

POST /api/v1/perps/positions/{assignmentId}/reduce trims or fully closes your position (reduceFraction in (0, 1], isFullClose). The proposal creator can close the whole proposal with POST /perps/proposals/{id}/close.

Claim a take-profit close

If a takeProfitPct bracket fired, the position closes automatically and becomes claimable. POST /api/v1/perps/positions/{assignmentId}/claim acknowledges it and drains the proceeds to your wallet.

Browse markets

GET /api/v1/perps/markets returns every tradable perp market; GET /api/v1/perps/markets/{symbol} returns one (and data: null if the symbol is unknown).

curl "$MURMO_BASE/api/v1/perps/markets/BTC" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const res = await fetch(`${process.env.MURMO_BASE}/api/v1/perps/markets/BTC`, {
  headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` },
});
const { data } = await res.json();
console.log(data.symbol, data.markPriceUsd, data.fundingRatePercentage);

res = requests.get(
    f"{base}/api/v1/perps/markets/BTC",
    headers={"Authorization": f"Bearer {key}"},
)
print(res.json()["data"])

Response

{
  "data": {
    "symbol": "BTC",
    "assetId": 1,
    "baseAsset": "BTC",
    "name": "Bitcoin",
    "marketStatus": "ACTIVE",
    "markPriceUsd": "68250.5",
    "midPriceUsd": "68249.0",
    "oraclePriceUsd": "68251.2",
    "fundingRatePercentage": "0.0042",
    "volume24hUsd": "91234567.8",
    "priceChange24hPct": "1.85",
    "prevDayPriceUsd": "67010.0",
    "tickSize": 1,
    "baseLotsDecimals": 5,
    "takerFeeBps": "4",
    "makerFeeBps": "2",
    "isolatedOnly": true
  }
}

PerpAsset (selected fields):

Field	Type	Notes
`symbol`	string	Market symbol, e.g. `BTC`. Use this as `marketSymbol` when opening.
`marketStatus`	string	Whether the market is tradable.
`markPriceUsd`	MoneyString \| null	Mark price (USD) — the position’s reference price.
`midPriceUsd` / `oraclePriceUsd`	MoneyString \| null	Mid and oracle prices (USD).
`fundingRatePercentage`	DecimalString \| null	Funding rate per funding interval, as a percent.
`volume24hUsd`	MoneyString \| null	24h notional volume (USD).
`priceChange24hPct`	DecimalString \| null	24h price change, as a percent.
`takerFeeBps` / `makerFeeBps`	DecimalString	Fees in basis points.
`tickSize`, `baseLotsDecimals`, `assetId`	integer	Structural ints (plain JSON numbers).
`leverageTiersJson`, `riskFactorsJson`	string	JSON-encoded leverage tiers / risk factors.
`fundingIntervalSeconds`, `fundingPeriodSeconds`	integer	Funding schedule.

The market_tick WebSocket stream sends these prices as numbers, not decimal strings, for speed. For exact money math (entry sizing, accounting) read prices from GET /perps/markets. See Market data.

See proposals in a group

A proposal is a shared LONG/SHORT idea. Reads are members only — you’ll get 403 NOT_GROUP_MEMBER for a group you don’t belong to. GET /api/v1/perps/proposals?groupId=... lists a group’s perp proposals; GET /api/v1/perps/proposals/{id} returns one (data: null if not found).

curl "$MURMO_BASE/api/v1/perps/proposals?groupId=1a9d212a-de67-45f4-88f5-6e9f41e78dc0" \
  -H "Authorization: Bearer $MURMO_API_KEY"

Response

{
  "data": [
    {
      "id": "b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30",
      "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
      "createdByUserDynamicId": "usr_9f1c...",
      "marketSymbol": "BTC",
      "side": "LONG",
      "reason": "Bullish into the halving",
      "creatorLeverage": "5",
      "stopLossPct": null,
      "takeProfitPct": "100",
      "currentPnlPct": "12.4",
      "closedAt": null,
      "exitPnlUsd": null,
      "exitPnlPct": null,
      "participantCount": 3,
      "totalParticipantCount": 3,
      "participantAvatars": ["https://...", "https://..."],
      "createdAt": "2026-06-02T18:55:00.000Z"
    }
  ]
}

PerpProposal (selected fields):

Field	Type	Notes
`id`	string	The `proposalId` — pass to `/increase` and `/close`.
`groupId`	string	Owning group.
`marketSymbol`	string	The market this idea is on.
`side`	`"LONG"` \| `"SHORT"`	Direction of the idea. Joiners inherit it.
`reason`	string	The creator’s thesis.
`creatorLeverage`	DecimalString \| null	The creator’s leverage.
`stopLossPct` / `takeProfitPct`	DecimalString \| null	The creator’s bracket settings (% collateral ROI).
`currentPnlPct`	DecimalString \| null	Live PnL on the idea, as a percent.
`closedAt`	date-time \| null	Set when the creator closes the proposal.
`exitPnlUsd` / `exitPnlPct`	MoneyString / DecimalString \| null	Realized PnL after close.
`participantCount` / `totalParticipantCount`	integer	How many members are in.
`participantAvatars`	string[]	Avatar URLs of participants.

Open a position (new proposal)

POST /api/v1/perps/proposals creates the proposal and opens your position atomically. The wallet is resolved for you — you never pass one.

Field	Required	Type	Notes
`groupId`	yes	string	Group to open the idea in. You must be a member.
`marketSymbol`	yes	string	A `symbol` from `GET /perps/markets`, e.g. `BTC`.
`side`	yes	`"LONG"` \| `"SHORT"`	Direction. Must be exactly one of these.
`collateralUsd`	yes	MoneyString	USD you put up, as a decimal string, e.g. `"25.00"`.
`leverage`	yes	DecimalString	Multiplier as a numeric string, e.g. `"5"`.
`reason`	no	string	Your thesis, shown to the group.
`stopLossPct`	no	DecimalString	% collateral-ROI stop-loss (see below).
`takeProfitPct`	no	DecimalString	% collateral-ROI take-profit (see below).

side must be exactly "LONG" or "SHORT". Anything else is rejected with 400 — the API never silently coerces a bad value, which would otherwise open a reversed position.

curl -X POST "$MURMO_BASE/api/v1/perps/proposals" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
    "marketSymbol": "BTC",
    "side": "LONG",
    "collateralUsd": "25.00",
    "leverage": "5",
    "reason": "Bullish into the halving",
    "takeProfitPct": "100"
  }'

const res = await fetch(`${process.env.MURMO_BASE}/api/v1/perps/proposals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupId: "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
    marketSymbol: "BTC",
    side: "LONG",
    collateralUsd: "25.00",
    leverage: "5",
    reason: "Bullish into the halving",
    takeProfitPct: "100",
  }),
});
const { data } = await res.json();
console.log(data.assignmentId, data.proposalId, data.txSignature);

res = requests.post(
    f"{base}/api/v1/perps/proposals",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={
        "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
        "marketSymbol": "BTC",
        "side": "LONG",
        "collateralUsd": "25.00",
        "leverage": "5",
        "reason": "Bullish into the halving",
        "takeProfitPct": "100",
    },
)
print(res.json()["data"])

Response

{
  "data": {
    "assignmentId": "f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55",
    "proposalId": "b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30",
    "subaccountIndex": 0,
    "txSignature": "5Jx...solana_sig",
    "marketSymbol": "BTC",
    "side": "LONG",
    "closePnlUsd": null,
    "closePnlPct": null,
    "closeProceedsUsd": null,
    "closedBaseUnits": null,
    "isFullClose": null
  }
}

This is a PerpPositionResult. On an open (or increase) the close-side fields are null; they’re populated only when a reduce fully closes the position.

Field	Type	Notes
`assignmentId`	string	Your position’s id — pass to `/reduce` and `/claim`.
`proposalId`	string	The proposal this position belongs to.
`subaccountIndex`	integer	The Phoenix subaccount holding this position.
`txSignature`	string	Solana signature of the opening transaction.
`marketSymbol`	string	Market traded.
`side`	`"LONG"` \| `"SHORT"`	Direction.
`closePnlUsd`	MoneyString \| null	Realized PnL — only on a full close.
`closePnlPct`	DecimalString \| null	Realized PnL % — only on a full close.
`closeProceedsUsd`	MoneyString \| null	USD returned to the wallet — only on a full close.
`closedBaseUnits`	string \| null	Base-unit quantity closed (a token quantity, not money).
`isFullClose`	boolean \| null	Whether the action fully closed the position.

Stop-loss and take-profit brackets

stopLossPct and takeProfitPct are optional and expressed as % collateral ROI (account P&L), not as a price move in the underlying.

takeProfitPct: "100" means “close when the position is up 100% of collateral” — i.e. you’d roughly double your stake. stopLossPct: "50" means “close when down 50% of collateral.” Because ROI is on collateral, these scale with leverage: at higher leverage a smaller price move hits the same ROI bracket. The corresponding trigger prices come back on the position as stopLossPriceUsd and takeProfitPriceUsd.

Join a proposal (increase)

To back an idea that already exists, POST /api/v1/perps/proposals/{id}/increase opens a new position under that proposal. The side is inherited from the proposal — you only send your own collateralUsd and leverage. You must be a member of the proposal’s group.

Field	Required	Type	Notes
`collateralUsd`	yes	MoneyString	USD you put up, e.g. `"25.00"`.
`leverage`	yes	DecimalString	Your multiplier, e.g. `"5"`.

curl -X POST "$MURMO_BASE/api/v1/perps/proposals/b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30/increase" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "collateralUsd": "25.00", "leverage": "5" }'

The response is a PerpPositionResult with your new assignmentId (same shape as opening above).

{id} here is the proposalId. This is the only join path on REST — a position’s own assignmentId is for /reduce and /claim, not for joining.

Monitor your positions

GET /api/v1/perps/positions?filter=active returns your positions, with live mark/PnL/funding fields plus realized fields once closed. filter is active (default), past, or all.

curl "$MURMO_BASE/api/v1/perps/positions?filter=active" \
  -H "Authorization: Bearer $MURMO_API_KEY"

Response

{
  "data": [
    {
      "id": "f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55",
      "userId": "usr_9f1c...",
      "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
      "proposalId": "b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30",
      "subaccountIndex": 0,
      "marketSymbol": "BTC",
      "side": "LONG",
      "status": "OPEN",
      "openedAt": "2026-06-02T18:55:01.000Z",
      "closedAt": null,
      "initialCollateralUsdc": "25.00",
      "initialLeverage": "5",
      "currentSizeBaseLots": "18420",
      "positionValueUsd": "126.10",
      "entryPriceUsd": "68110.0",
      "liquidationPriceUsd": "55230.4",
      "stopLossPriceUsd": null,
      "takeProfitPriceUsd": "81732.0",
      "unrealizedPnlUsd": "1.10",
      "unsettledFundingUsd": "-0.02",
      "accumulatedFundingUsd": "-0.05",
      "isClaimable": false,
      "participantCount": 3,
      "participantAvatars": ["https://..."]
    }
  ]
}

PerpPosition (selected fields):

Field	Type	Notes
`id`	string	= `assignmentId` — pass to `/reduce` and `/claim`.
`proposalId`	string	Proposal this position belongs to.
`marketSymbol` / `side`	string / enum	Market and direction.
`status`	string	`OPEN`, `CLOSED`, `LIQUIDATED`, or `ADL_CLOSED`.
`subaccountIndex`	integer	Phoenix subaccount.
`initialCollateralUsdc`	MoneyString	Collateral you put up.
`initialLeverage`	DecimalString	Leverage at open.
`currentSizeBaseLots`	string \| null	Current size in base lots (a quantity, not money).
`currentSizeBaseUnits`	DecimalString \| null	Current size in base units.
`positionValueUsd`	MoneyString \| null	Live notional value (USD).
`entryPriceUsd` / `exitPriceUsd`	MoneyString \| null	Entry and (on close) exit price.
`liquidationPriceUsd`	MoneyString \| null	Price at which the position is liquidated.
`stopLossPriceUsd` / `takeProfitPriceUsd`	MoneyString \| null	Bracket trigger prices.
`unrealizedPnlUsd`	MoneyString \| null	Live PnL on an open position.
`unsettledFundingUsd` / `accumulatedFundingUsd`	MoneyString \| null	Pending / total funding.
`collateralBalanceUsdc` / `effectiveCollateralUsdc`	MoneyString \| null	Collateral balances.
`isClaimable`	boolean	`true` after a take-profit close, until you `/claim`.
`closeReason` / `claimedAt`	enum / date-time \| null	Why it closed (`USER_FULL_CLOSE`, `LIQUIDATION`, `BACKSTOP_LIQUIDATION`, `ADL`, `STOP_LOSS_TRIGGERED`, `TAKE_PROFIT_TRIGGERED`, `ADMIN`), and when claimed.

When closed, the realized fields populate: priceRealizedPnlUsd, fundingRealizedUsd, totalFeesUsd, liquidationPenaltyUsd, netRealizedPnlUsd, and finalCollateralReturned — all MoneyString. Use filter=past or filter=all to see them.

currentSizeBaseLots / currentSizeBaseUnits are quantities, not USD. Everything ending in ...Usd (and prices/PnL/percent) is a human decimal string. See Money & precision → Raw vs. human quantities.

Reduce or close your position

POST /api/v1/perps/positions/{assignmentId}/reduce trims or fully closes your position. It’s keyed by assignmentId (the position’s id).

Field	Required	Type	Notes
`reduceFraction`	yes	DecimalString	Fraction of current size to close, in `(0, 1]`, e.g. `"0.5"`.
`isFullClose`	yes	boolean	Set `true` when this fully closes the position.

# Trim 50%
curl -X POST "$MURMO_BASE/api/v1/perps/positions/f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55/reduce" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "reduceFraction": "0.5", "isFullClose": false }'

// Fully close
const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/perps/positions/${assignmentId}/reduce`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reduceFraction: "1", isFullClose: true }),
  },
);
const { data } = await res.json();
console.log(data.closePnlUsd, data.closeProceedsUsd);

# Fully close
res = requests.post(
    f"{base}/api/v1/perps/positions/{assignment_id}/reduce",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={"reduceFraction": "1", "isFullClose": True},
)
print(res.json()["data"])

Response (full close)

{
  "data": {
    "assignmentId": "f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55",
    "proposalId": "b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30",
    "subaccountIndex": 0,
    "txSignature": "3Kp...solana_sig",
    "marketSymbol": "BTC",
    "side": "LONG",
    "closePnlUsd": "4.20",
    "closePnlPct": "16.8",
    "closeProceedsUsd": "29.20",
    "closedBaseUnits": "18420",
    "isFullClose": true
  }
}

The response is a PerpPositionResult (table above). On a full close, closePnlUsd, closePnlPct, closeProceedsUsd, and closedBaseUnits are populated.

reduceFraction must be in (0, 1] — a value > 1, 0, or non-numeric is rejected with 400, as is a missing isFullClose. To close everything, send reduceFraction: "1" with isFullClose: true.

Close the whole proposal (creator only)

POST /api/v1/perps/proposals/{id}/close closes the proposal, keyed by proposalId. Only the creator can do this (enforced); it closes the creator’s own open position(s) and locks out new joiners. Other members’ positions are left untouched — they manage their own exits via /reduce.

curl -X POST "$MURMO_BASE/api/v1/perps/proposals/b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30/close" \
  -H "Authorization: Bearer $MURMO_API_KEY"

Response

{ "data": { "success": true } }

If you’re not the creator, this returns 403. To exit a position you joined, use /positions/{assignmentId}/reduce instead.

Claim a take-profit close

When a takeProfitPct bracket fires, the position closes automatically and becomes claimable (isClaimable: true). POST /api/v1/perps/positions/{assignmentId}/claim acknowledges that close and drains the proceeds to your wallet. It’s keyed by assignmentId.

curl -X POST "$MURMO_BASE/api/v1/perps/positions/f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55/claim" \
  -H "Authorization: Bearer $MURMO_API_KEY"

Response

{
  "data": {
    "assignmentId": "f3a1c9d2-1b44-4e77-8c0a-2d9e6b1f7a55",
    "proposalId": "b2c7f0e1-4d3a-4f9c-9a21-7e8d6c5b4a30",
    "marketSymbol": "BTC",
    "side": "LONG",
    "closePnlUsd": "25.00",
    "closePnlPct": "100.0",
    "closeProceedsUsd": "50.00",
    "closedBaseUnits": "18420",
    "claimedAt": "2026-06-03T01:12:00.000Z"
  }
}

PerpClaimResult:

Field	Type	Notes
`assignmentId`	string	The claimed position.
`proposalId`	string	Its proposal.
`marketSymbol` / `side`	string / enum	Market and direction.
`closePnlUsd`	MoneyString	Realized PnL (USD).
`closePnlPct`	DecimalString	Realized PnL, as a percent.
`closeProceedsUsd`	MoneyString	USD drained to your wallet.
`closedBaseUnits`	string	Base-unit quantity closed (a quantity, not money).
`claimedAt`	date-time	When the claim settled.

Claim is only for take-profit-triggered closes. Positions you close yourself via /reduce return proceeds directly in that call — there’s nothing to claim.

Errors you’ll hit

Status / code	Cause	Fix
`400`	Bad `side`, non-positive `collateralUsd`/`leverage`, `reduceFraction` out of `(0, 1]`, missing `isFullClose`/`groupId`/`marketSymbol`.	Fix the request body.
`401`	Missing or invalid key.	Send `Authorization: Bearer murmo_...`.
`403 NOT_GROUP_MEMBER`	Reading/joining a proposal in a group you’re not in.	Join the group first.
`403`	Closing a proposal you didn’t create, or a geo/eligibility block.	Use `/reduce` for your own position; see geo restrictions.

See Errors for the full status-code and code reference and a retry pattern.

Perps bot

Open, monitor, and close a position in one script.

Money & precision

Why collateralUsd is "25.00" and not 25.

Groups & proposals

The social model: groups, proposals, positions.

Market data (WebSocket)

Live per-symbol perp ticks for low-latency monitoring.

API Reference

Every Perpetuals endpoint, field by field.

Get started

Example flows

Core concepts

Trading guides

Real-time (WebSockets)

Two IDs: proposalId vs assignmentId

Setup

Lifecycle

Browse markets

See proposals in a group

Open a position (new proposal)

Stop-loss and take-profit brackets

Join a proposal (increase)

Monitor your positions

Reduce or close your position

Close the whole proposal (creator only)

Claim a take-profit close

Errors you’ll hit

Next

Perps bot

Money & precision

Groups & proposals

Market data (WebSocket)

API Reference

​Two IDs: proposalId vs assignmentId

​Setup

​Lifecycle

​Browse markets

​See proposals in a group

​Open a position (new proposal)

​Stop-loss and take-profit brackets

​Join a proposal (increase)

​Monitor your positions

​Reduce or close your position

​Close the whole proposal (creator only)

​Claim a take-profit close

​Errors you’ll hit

​Next

Perps bot

Money & precision

Groups & proposals

Market data (WebSocket)

API Reference

Two IDs: proposalId vs assignmentId

Setup

Lifecycle

Browse markets

See proposals in a group

Open a position (new proposal)

Stop-loss and take-profit brackets

Join a proposal (increase)

Monitor your positions

Reduce or close your position

Close the whole proposal (creator only)

Claim a take-profit close

Errors you’ll hit

Next