> ## 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.

# Quickstart

> From an API key to your first on-chain trade in a few minutes.

This walks you from zero to a live trade. You'll authenticate, check your wallet, fund it, then open
your first position through a group spot proposal.

<Note>
  All money in and out is a **decimal string** (`"25.00"`, not `25` and not `25000000`).
  See [Money & precision](/concepts/money-and-precision).
</Note>

## 1. Get your key

Create an API key in the Murmo app. At **app.murmo.xyz**, go to **Account → Settings → REST** and
click **Generate key** (on mobile: **Settings → API keys → Generate key**). Give it a label,
optionally set an expiry, and **copy the key — it's shown once**. Production keys start with
`murmo_live_`.

Treat it like a password — it can move funds on your behalf. Store it in an environment variable:

```bash theme={null}
export MURMO_API_KEY="murmo_your_key_here"
export MURMO_BASE="https://api.alpha-labs.trade"
```

## 2. Confirm who you are

```bash theme={null}
curl "$MURMO_BASE/api/v1/me" -H "Authorization: Bearer $MURMO_API_KEY"
```

A `200` with your `userId` means the key works. A `401` means the header is missing or the key is
invalid — check it starts with `murmo_` and is sent as `Authorization: Bearer ...`.

## 3. Check your wallet

```bash theme={null}
curl "$MURMO_BASE/api/v1/account" -H "Authorization: Bearer $MURMO_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "totalValueUsd": "0",
    "cashBalanceUsd": "0",
    "deposit": {
      "walletAddress": "5xY...wallet",
      "token": "USDC",
      "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "chain": "solana"
    }
  }
}
```

## 4. Fund it

Funding is one step: **send USDC on Solana to the `deposit.walletAddress` above.** USDC is the only
token you ever hold; once the transfer lands, `cashBalanceUsd` reflects it. (Withdrawals aren't
available over the API; they require the app.)

## 5. Your first trade

Trades on Murmo live as **proposals** inside **groups** (your trading circles). Spot, predictions, and
perps all work the same way. Opening a proposal is leader/admin only, so first create a group to trade
in (you become its admin):

```bash theme={null}
curl -X POST "$MURMO_BASE/api/v1/groups" \
  -H "Authorization: Bearer $MURMO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "My bot", "joiningFee": "0", "groupAccessType": "PRIVATE" }'
# returns { "data": { "groupId": "...", ... } }
```

Then open a **proposal** in that `groupId`. Creating it places the opening buy in a single call:

| 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](/concepts/money-and-precision) (required) | The opening buy size in USDC (human string). |

<CodeGroup>
  ```bash curl theme={null}
  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": "25.00"
    }'
  ```

  ```javascript JavaScript theme={null}
  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: "DezXAZ8z7...263",
      reason: "Momentum breakout",
      amountUsd: "25.00",
    }),
  });
  const { data } = await res.json();
  console.log(data.proposal.id, data.trade.txSignature);
  ```

  ```python Python theme={null}
  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": "DezXAZ8z7...263",
          "reason": "Momentum breakout",
          "amountUsd": "25.00",
      },
  )
  print(res.json()["data"]["proposal"]["id"])
  ```
</CodeGroup>

Returns `{ data: { proposal, trade } }` — keep `proposal.id` to buy more, sell, or close later.

```json Response theme={null}
{
  "data": {
    "proposal": { "id": "prop_abc123", "groupId": "1a9d212a-...", "reason": "Momentum breakout", "...": "..." },
    "trade": {
      "tradeType": "BUY",
      "tokenAmount": "690000",
      "tokenDecimals": 5,
      "pricePerTokenUsd": "0.0000362",
      "totalCostUsd": "25",
      "alphaFeeUsd": "0.05",
      "pnlUsd": null
    }
  }
}
```

## 6. Buy into an existing proposal

To add to a proposal — your own or one a groupmate opened — call `/buy` with `amountUsd` (USDC to
spend), or `max: true` to spend your full USDC balance:

```bash theme={null}
# List the proposals in a group (each with your position)
curl "$MURMO_BASE/api/v1/spot/proposals?groupId=GROUP_ID" \
  -H "Authorization: Bearer $MURMO_API_KEY"

# Buy $20 more into one
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" }'
```

From here you can `buy`, `sell`, or `close` the proposal, and others in the group can follow it.
See the [Spot trading guide](/guides/spot-trading) and [Groups & proposals](/concepts/groups-and-proposals).

## Predictions

Prediction markets work as soon as you're funded — no extra setup. The only gate is regional: the
two calls that **open or add to** a position — `POST /api/v1/predictions/proposals` and
`POST /api/v1/predictions/proposals/{id}/predict` — return `403` with `code: "GEO_RESTRICTED"` in
restricted regions. Reads, selling, and claiming are never gated.

<Note>
  See [Eligibility & geo restrictions](/concepts/geo-restrictions) for the details, and the
  [Prediction agent](/examples/prediction-agent) flow for an end-to-end example.
</Note>

## Where to next

<CardGroup cols={2}>
  <Card title="Money & precision" icon="coins" href="/concepts/money-and-precision">
    The one rule that prevents the most bugs.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Keys, the Bearer header, and rate limits.
  </Card>

  <Card title="Prediction markets" icon="chart-line" href="/guides/prediction-markets">
    Predict YES/NO on real-world events.
  </Card>

  <Card title="Perpetuals" icon="gauge-high" href="/guides/perpetuals">
    Leverage, brackets, and live PnL.
  </Card>
</CardGroup>