> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups & proposals

> The social model behind Murmo: groups, proposals, participants, and positions.

Most trading on Murmo is social. Understanding three nouns — **groups**, **proposals**, and
**positions** — explains almost the entire API.

## Groups

A **group** is a trading circle. You're a member of zero or more groups, each identified by a
`uniqueId`. Groups are `PUBLIC` (anyone can join instantly) or `PRIVATE` (join by request or invite).
Members have a `memberType` of `MEMBER`, `LEADER`, or the creator who is an admin.

`GET /api/v1/groups` lists the groups **you** belong to. There is deliberately no endpoint to
discover other people's groups — private group internals stay private, and every per-group read is
gated to members (you'll get `403 NOT_GROUP_MEMBER` otherwise). See the [Groups guide](/guides/groups)
to create, join, and run them.

## Proposals

A **proposal** is a trade idea inside a group, in one of three flavors:

<CardGroup cols={3}>
  <Card title="Spot" icon="arrow-right-arrow-left">
    A token a leader is buying. Members can buy in, sell out, and the creator can close it.
  </Card>

  <Card title="Prediction" icon="chart-line">
    A YES/NO position on a Polymarket event. Members can predict, sell, and claim winnings.
  </Card>

  <Card title="Perp" icon="gauge-high">
    A leveraged LONG/SHORT idea on Phoenix RISE. Members can join (increase) and reduce/close.
  </Card>
</CardGroup>

Creating a proposal includes the creator's opening trade in a single call. Other members then take
**positions** under the same proposal — each member manages their own entry and exit, but the idea is
shared. `participantCount` and `participantAvatars` show who's in.

```text theme={null}
Group  ──┬── Spot proposal (BONK)        ──> your position + others'
         ├── Prediction proposal (KC win) ──> your YES position + others'
         └── Perp proposal (BTC LONG 5×)   ──> your position + others'
```

## Positions

A **position** is your stake in a proposal. The trading guides cover the lifecycle per vertical:

* Spot: [open / buy / sell / close](/guides/spot-trading)
* Predictions: [propose / predict / sell / claim](/guides/prediction-markets)
* Perps: [open / increase / reduce / close / claim](/guides/perpetuals)

Your positions across every group and vertical are aggregated for you — see
[Portfolio & account](/guides/portfolio-and-account):

* `GET /api/v1/positions` — open positions (perps + spot + predictions)
* `GET /api/v1/positions/past` — closed/resolved positions
* `GET /api/v1/trades` — executed trade history (spot + predictions)

## Response envelopes

Every response is wrapped in a `data` envelope. The **shape inside `data`** depends on the endpoint:

| Pattern                  | `data` is                       | Endpoints                                                                                                  |
| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Homogeneous list         | an **array**                    | `GET /spot/proposals`, `/predictions/proposals`, `/perps/proposals`, `/perps/positions`, `/groups`         |
| Cross-vertical aggregate | an **object** keyed by vertical | `GET /positions`, `/positions/past`, `/trades`, `/groups/{id}/proposals`                                   |
| Named single list        | an **object** with a named key  | `GET /account/balances` → `{ balances: [...] }`, `/account/positions` → `{ positions: [...], nextCursor }` |
| Single resource          | an **object** (or `null`)       | detail and mutation endpoints                                                                              |

<Tip>
  Check the endpoint in the [API Reference](/api-reference) for the exact `data` shape before you
  write `response.data.map(...)` — the aggregate and account endpoints return an object, not an array.
</Tip>