Spot trading

Spot trading on Murmo happens through group spot proposals: a shared token idea inside a group that a leader opens with a buy and other members can follow. Slippage and the wallet id are always resolved for you (never accepted from the caller). Everything lives under /api/v1/spot. Tokens are addressed by their Solana mint address, or the literal string "USDC".

Every monetary value — in requests and responses — is a full-precision plain decimal string in USD ("12.50", not 12.5, not 12500000, never "1.25e1"). Token quantities in base units are the one exception and are always named with a ...Raw suffix. See Money & precision.

Set up your environment the same way as the Quickstart:

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

Find a token

GET /api/v1/spot/tokens/search is a Jupiter-backed search over Solana tokens. Both q (a symbol, name, or mint) and limit (default 20) are optional.

curl "$MURMO_BASE/api/v1/spot/tokens/search?q=bonk&limit=5" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/tokens/search?q=bonk&limit=5`,
  { headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` } },
);
const { data } = await res.json();
console.log(data.map((t) => t.symbol));

res = requests.get(
    f"{base}/api/v1/spot/tokens/search",
    params={"q": "bonk", "limit": 5},
    headers={"Authorization": f"Bearer {key}"},
)
print(res.json()["data"])

data is an array of token objects. The shape passes through from Jupiter/CoinGecko, so treat the keys as opaque — but any price/volume floats are rendered as decimal strings, never JS numbers.

Search is for discovery. Once you have a candidate mint, fetch its canonical price and decimals with the by-mint endpoint below before you trade.

Get price + metadata (and `decimals`)

GET /api/v1/spot/tokens/{mint} returns price and metadata for one token by its mint address. This is how you get a token’s decimals — the number you need to humanize any ...Raw quantity returned elsewhere.

curl "$MURMO_BASE/api/v1/spot/tokens/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const mint = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263";
const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/tokens/${mint}`,
  {
    headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` },
  },
);
const { data } = await res.json();
console.log(data.decimals); // structural integer, e.g. 5

mint = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
res = requests.get(
    f"{base}/api/v1/spot/tokens/{mint}",
    headers={"Authorization": f"Bearer {key}"},
)
print(res.json()["data"]["decimals"])

data is a single token object (opaque, pass-through shape). Price fields are decimal strings; decimals is a plain integer you reuse to convert base units to human amounts.

Group spot proposals

A spot proposal is a token idea inside a group: a leader opens it with a buy, and other members buy in, sell out, and follow along. Each member manages their own position; the creator can close the whole proposal. See Groups & proposals for the social model.

Every proposal endpoint is members-only. Reading or trading a proposal in a group you don’t belong to returns 403 with code: NOT_GROUP_MEMBER. Creating a proposal additionally requires a leader/admin role. See Errors.

List a group’s proposals

GET /api/v1/spot/proposals?groupId=... returns every spot proposal in a group, each paired with your position on it. groupId is required (a missing/blank value is a clean 400).

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

const groupId = "1a9d212a-de67-45f4-88f5-6e9f41e78dc0";
const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/proposals?groupId=${groupId}`,
  { headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` } },
);
const { data } = await res.json(); // array of SpotProposalWithPosition

res = requests.get(
    f"{base}/api/v1/spot/proposals",
    params={"groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0"},
    headers={"Authorization": f"Bearer {key}"},
)
print(res.json()["data"])

data is an array of SpotProposalWithPosition:

Field	Meaning
`proposal`	The `SpotProposal` (token, creator, prices, lifecycle — see below).
`userPosition`	Your `SpotPositionSummary` on this proposal.
`participantCount`	How many members hold a position (nullable).
`participantAvatars`	Avatar URLs for participants (nullable).

Proposal detail

GET /api/v1/spot/proposals/{id} returns the same SpotProposalWithPosition shape, and additionally populates proposal.trades — the caller’s own trades on this proposal. If the proposal doesn’t exist, data is null.

curl "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/proposals/PROPOSAL_ID`,
  { headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` } },
);
const { data } = await res.json();
if (data) console.log(data.proposal.trades);

res = requests.get(
    f"{base}/api/v1/spot/proposals/PROPOSAL_ID",
    headers={"Authorization": f"Bearer {key}"},
)
data = res.json()["data"]
print(data and data["proposal"]["trades"])

`SpotProposal`

Field	Type	Meaning
`id`	string	Proposal id (use it in `/buy`, `/sell`, `/close`).
`groupId`	string	The group this proposal belongs to.
`createdByUserDynamicId`	string	The creator’s user id.
`tokenMetadataId`	string	Internal token metadata id.
`reason`	string \| null	The thesis the creator gave when opening it.
`initialPriceUsd`	MoneyString \| null	Token price (USD) when the proposal opened.
`exitPriceUsd`	MoneyString \| null	Token price (USD) when the proposal closed.
`exitPnlPct`	DecimalString \| null	Realized PnL percent at close (e.g. `"12.3"` = 12.3%).
`exitPnlUsd`	MoneyString \| null	Realized PnL in USD at close.
`closedAt`	date-time \| null	When it was closed (null while open).
`createdAt` / `updatedAt`	date-time	Timestamps.
`token`	`TokenRef` \| null	`{ contractAddress, symbol, name, logoUrl, verified, ... }`.
`group`	`GroupRef` \| null	`{ uniqueId, name, image }`.
`createdBy`	`UserRef` \| null	`{ dynamicId, username }`.
`trades`	`SpotTrade[]` \| null	Detail endpoint only — the caller’s trades on this proposal.

`SpotPositionSummary` (`userPosition`)

Field	Type	Meaning
`hasPosition`	boolean	Whether you currently hold this proposal.
`currentTokenAmountRaw`	string \| null	Your token holding in base units — humanize with the token’s `decimals`.
`totalCostUsd`	MoneyString \| null	What you’ve spent into the position, in USD.
`avgEntryPriceUsd` / `avgExitPriceUsd`	MoneyString \| null	Average entry / exit price (USD).
`unrealizedPnlUsd` / `unrealizedPnlPct`	MoneyString / DecimalString \| null	Open PnL, in USD and percent.
`realizedPnlUsd` / `realizedPnlPct`	MoneyString / DecimalString \| null	Closed PnL, in USD and percent.
`currentValueUsd`	MoneyString \| null	Current mark value of your holding (USD).
`currentPriceUsd`	MoneyString \| null	Current token price (USD).
`userExitedAt`	date-time \| null	When you fully exited (null if still in).

currentTokenAmountRaw is the only quantity here in base units (note the ...Raw suffix). Every other field is a human USD or percent string. To get a human token count, divide by 10 ** decimals.

The proposal lifecycle

Open a proposal, scale your position with buys and sells, then close it. Buy, sell, and close all return the executed SpotTrade.

Create with an opening buy

POST /api/v1/spot/proposals creates the proposal and places the proposer’s opening buy in a single call. Leader/admin only.

Field	Type	Notes
`groupId`	string (required)	The group to open the proposal in.
`contractAddress`	string (required)	The token’s Solana mint.
`reason`	string (optional)	Your thesis, shown to the group.
`amountUsd`	MoneyString (required)	The opening buy size in USDC (human string).

curl -X POST "$MURMO_BASE/api/v1/spot/proposals" \
  -H "Authorization: Bearer $MURMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
    "contractAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "reason": "Momentum breakout",
    "amountUsd": "50.00"
  }'

const res = await fetch(`${process.env.MURMO_BASE}/api/v1/spot/proposals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupId: "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
    contractAddress: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    reason: "Momentum breakout",
    amountUsd: "50.00",
  }),
});
const { data } = await res.json();
console.log(data.proposal.id, data.trade.txSignature);

res = requests.post(
    f"{base}/api/v1/spot/proposals",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={
        "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0",
        "contractAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
        "reason": "Momentum breakout",
        "amountUsd": "50.00",
    },
)
print(res.json()["data"]["proposal"]["id"])

Returns { data: { proposal, trade } } — a SpotProposal and the opening SpotTrade. Keep proposal.id for the calls below.

Response

{
  "data": {
    "proposal": { "id": "prop_abc123", "groupId": "1a9d212a-...", "reason": "Momentum breakout", "...": "..." },
    "trade": {
      "tradeType": "BUY",
      "tokenAmount": "1380000",
      "tokenDecimals": 5,
      "pricePerTokenUsd": "0.0000362",
      "totalCostUsd": "50",
      "alphaFeeUsd": "0.10",
      "pnlUsd": null
    }
  }
}

Buy in

POST /api/v1/spot/proposals/{id}/buy adds to your position. Send amountUsd (USDC to spend), or max: true to spend your full USDC balance (then amountUsd is ignored).

# Buy a fixed $20
curl -X POST "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID/buy" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "amountUsd": "20.00" }'

# Or go all-in on available USDC
curl -X POST "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID/buy" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "max": true }'

const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/proposals/PROPOSAL_ID/buy`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amountUsd: "20.00" }), // or { max: true }
  }
);
const { data } = await res.json();
console.log(data.trade.tradeType, data.trade.totalCostUsd);

res = requests.post(
    f"{base}/api/v1/spot/proposals/PROPOSAL_ID/buy",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={"amountUsd": "20.00"},  # or {"max": True}
)
print(res.json()["data"]["trade"])

Returns { data: { trade } } (a SpotTradeEnvelope).

Sell out

POST /api/v1/spot/proposals/{id}/sell trims or exits your position. Here amountUsd is your desired USDC output (how much cash you want back), or max: true to sell the full token position.

# Take $10 of USDC back out
curl -X POST "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID/sell" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "amountUsd": "10.00" }'

# Or exit the whole position
curl -X POST "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID/sell" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "max": true }'

const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/proposals/PROPOSAL_ID/sell`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amountUsd: "10.00" }), // or { max: true }
  }
);
const { data } = await res.json();
console.log(data.trade.pnlUsd);

res = requests.post(
    f"{base}/api/v1/spot/proposals/PROPOSAL_ID/sell",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={"amountUsd": "10.00"},  # or {"max": True}
)
print(res.json()["data"]["trade"])

Returns { data: { trade } } (a SpotTradeEnvelope).

Buy amountUsd is USDC spent; sell amountUsd is USDC received. Use max: true on either side to skip sizing math — full balance on buy, full position on sell.

Close (creator only)

POST /api/v1/spot/proposals/{id}/close is for the proposal’s creator. It sells the creator’s full position and moves the proposal into a closed state.

curl -X POST "$MURMO_BASE/api/v1/spot/proposals/PROPOSAL_ID/close" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const res = await fetch(
  `${process.env.MURMO_BASE}/api/v1/spot/proposals/PROPOSAL_ID/close`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` },
  }
);
const { data } = await res.json();
console.log(data.proposal.closedAt, data.proposal.exitPnlUsd);

res = requests.post(
    f"{base}/api/v1/spot/proposals/PROPOSAL_ID/close",
    headers={"Authorization": f"Bearer {key}"},
)
print(res.json()["data"]["proposal"]["exitPnlUsd"])

Returns { data: { proposal, trade } } — the now-closed SpotProposal (with closedAt, exitPriceUsd, exitPnlUsd, exitPnlPct) and the closing SpotTrade. Other members keep their own positions and exit them with /sell.

`SpotTrade` (buy / sell / close)

Every executed trade — the opening buy on create, each /buy and /sell, and the closing trade — returns a SpotTrade. Unlike position quantities, tokenAmount here is already humanized (it uses tokenDecimals), so you don’t divide it yourself.

Field	Type	Meaning
`id`	string	Trade id.
`tradingProposalId`	string	The proposal this trade belongs to.
`groupId`	string	The group.
`walletAddress`	string	The wallet that executed the trade.
`tradeType`	`"BUY"` \| `"SELL"`	Direction.
`tokenAmount`	DecimalString	Token quantity, already humanized with `tokenDecimals`.
`tokenDecimals`	integer	The token’s decimals (structural integer).
`pricePerTokenUsd`	MoneyString \| null	Execution price per token (USD).
`totalCostUsd`	MoneyString	USD value of the trade.
`alphaFeeUsd`	MoneyString	Alpha fee for this trade (USD).
`pnlUsd`	MoneyString \| null	Realized PnL on a sell (USD); null on buys.
`pnlPct`	DecimalString \| null	Realized PnL percent on a sell; null on buys.
`txSignature`	string \| null	Solana transaction signature.
`createdAt`	date-time	When it executed.

Two quantity conventions live side by side: a trade’s tokenAmount is already humanized (uses tokenDecimals), while a position’s currentTokenAmountRaw is raw base units you humanize with decimals. The ...Raw suffix is your signal. See Money & precision → Raw vs. human quantities.

Tokenized stocks (by ticker)

Murmo lists Ondo Global Markets tokenized stocks and ETFs (e.g. NVDA, AAPL). They trade through the exact same group/proposal flow as any other spot token — position tracking and max semantics are identical — but a dedicated /api/v1/spot/stocks surface lets you trade by ticker instead of a mint, and tells you what’s supported and whether the market is open.

The tradeable universe is the Ondo catalog only. A ticker is the clean symbol ("NVDA", case-insensitive); resolution also accepts the raw on-chain symbol ("NVDAON") or the mint. Stocks observe market hours — trades outside them are rejected up front (see below).

List supported stocks

GET /api/v1/spot/stocks returns the full catalog plus the shared market status. There are no parameters.

curl "$MURMO_BASE/api/v1/spot/stocks" \
  -H "Authorization: Bearer $MURMO_API_KEY"

const res = await fetch(`${process.env.MURMO_BASE}/api/v1/spot/stocks`, {
  headers: { Authorization: `Bearer ${process.env.MURMO_API_KEY}` },
});
const { data } = await res.json();
console.log(data.marketStatus, data.nextOpen); // e.g. "CLOSED" "2026-06-17T13:30:00.000Z"
console.log(data.stocks.map((s) => s.ticker));

Returns { data: { marketStatus, nextOpen, stocks } }. marketStatus is OPEN, PAUSED, or CLOSED; nextOpen is the ISO instant trading resumes (null when open). Each stocks[] entry:

Field	Type	Meaning
`ticker`	string	The symbol you trade by (`"NVDA"`).
`name`	string	Display name (`"NVIDIA"`).
`mint`	string	Underlying Solana (Token-2022) mint.
`kind`	`"stock"` \| `"etf"`	Catalog category.
`price`	MoneyString \| null	Real underlying equity price (USD).
`priceChange24h`	DecimalString \| null	24h change percent.
`decimals`	integer	Token decimals (structural).
`minTradeUsd`	MoneyString \| null	Minimum opening-buy size (USD).
`imageUrl`	string \| null	Logo.

Open and trade by ticker

POST /api/v1/spot/stocks/proposals opens a position by ticker (everything else matches Create with an opening buy — groupId, optional reason, amountUsd). Follow-on POST /api/v1/spot/stocks/proposals/{id}/buy and /sell take the same { amountUsd | max } body as the mint-based endpoints and return a SpotTradeEnvelope.

# Open a $50 NVDA position in a group
curl -X POST "$MURMO_BASE/api/v1/spot/stocks/proposals" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "groupId": "1a9d212a-de67-45f4-88f5-6e9f41e78dc0", "ticker": "NVDA", "amountUsd": "50.00" }'

# Add $20, then exit fully

curl -X POST "$MURMO_BASE/api/v1/spot/stocks/proposals/PROPOSAL_ID/buy" \
 -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
 -d '{ "amountUsd": "20.00" }'

curl -X POST "$MURMO_BASE/api/v1/spot/stocks/proposals/PROPOSAL_ID/sell" \
 -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
 -d '{ "max": true }'

const open = await fetch(`${process.env.MURMO_BASE}/api/v1/spot/stocks/proposals`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MURMO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ groupId: GROUP_ID, ticker: "NVDA", amountUsd: "50.00" }),
});
const { data } = await open.json();
console.log(data.proposal.id, data.trade.txSignature);

Stock-specific errors on these endpoints: 404 TOKEN_NOT_FOUND (ticker not in the catalog — check GET /spot/stocks), 409 MARKET_CLOSED (market paused/closed; details.nextOpenAt carries the next open instant), and 422 ORDER_BELOW_MIN_SIZE (opening buy under the token’s minTradeUsd). Membership/role rules (403 NOT_GROUP_MEMBER) apply exactly as for any proposal.

Errors you’ll hit

Status / code	When	What to do
`400`	Missing/invalid body or `groupId`, or an unroutable trade.	Fix the request; read `message`/`code`.
`401`	Missing or invalid key.	Check the `Authorization: Bearer murmo_...` header.
`403` `NOT_GROUP_MEMBER`	Reading/trading a proposal in a group you’re not in (or not leader/admin on create).	Don’t retry as-is.
`404` `TOKEN_NOT_FOUND`	Stock ticker not in the Ondo catalog.	List `GET /spot/stocks` first.
`409` `MARKET_CLOSED`	Stock market paused/closed.	Wait until `details.nextOpenAt`.
`422` `ORDER_BELOW_MIN_SIZE`	Opening buy under the stock’s `minTradeUsd`.	Increase `amountUsd`.
`422` `ROUTE_NOT_FOUND`	No swap route / no quote for this size right now.	Often transient — retry or adjust size.
`502` `UPSTREAM_REJECTED`	The swap venue rejected the trade (`details.upstream` carries the raw reason).	Don’t auto-retry; inspect and adjust.

See Errors for the full list, status-code semantics, and a ready-made handler. Note that proposal detail returns data: null for an unknown id.

Where to next

Spot momentum bot

The whole flow as one copy-pasteable script.

Money & precision

Decimal strings, and humanizing ...Raw quantities.

Groups & proposals

The social model: groups, proposals, positions.

Errors

Error shapes, status codes, and the codes worth handling.

API Reference

Every Spot endpoint, parameter, and response schema.

Get started

Example flows

Core concepts

Trading guides

Real-time (WebSockets)

Find a token

Get price + metadata (and `decimals`)

Group spot proposals

List a group’s proposals

Proposal detail

`SpotProposal`

`SpotPositionSummary` (`userPosition`)

The proposal lifecycle

`SpotTrade` (buy / sell / close)

Tokenized stocks (by ticker)

List supported stocks

Open and trade by ticker

Errors you’ll hit

Where to next

Spot momentum bot

Money & precision

Groups & proposals

Errors

API Reference

​Find a token

​Get price + metadata (and decimals)

​Group spot proposals

​List a group’s proposals

​Proposal detail

​SpotProposal

​SpotPositionSummary (userPosition)

​The proposal lifecycle

​SpotTrade (buy / sell / close)

​Tokenized stocks (by ticker)

​List supported stocks

​Open and trade by ticker

​Errors you’ll hit

​Where to next

Spot momentum bot

Money & precision

Groups & proposals

Errors

API Reference

Find a token

Get price + metadata (and `decimals`)

Group spot proposals

List a group’s proposals

Proposal detail

`SpotProposal`

`SpotPositionSummary` (`userPosition`)

The proposal lifecycle

`SpotTrade` (buy / sell / close)

Tokenized stocks (by ticker)

List supported stocks

Open and trade by ticker

Errors you’ll hit

Where to next