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

# Stop Loss

> Create non-custodial Solana stop-loss orders with Mobula Advanced Orders. Deposit tokens, sign an intent, and execute automatically when the quote falls to your protection threshold.

<Warning>
  **Alpha feature**: Advanced Orders are gated and not publicly available yet. Reach out to the Mobula team to enable access for your account.
</Warning>

Stop Loss Advanced Orders help users protect downside without giving Mobula custody of their wallet or a reusable approval. The user deposits the exact `tokenIn` amount for the order, signs a canonical intent, and Mobula executes only when the fresh quote for `amountRaw` is less than or equal to `triggerAmountOutRaw`.

Use this flow for Solana token stop-loss automation, SL lines on charts, protected exits, and any UX where the user wants a swap to execute only after the market falls to a defined output.

## POST / GET

| Method | Path                                          | Purpose                                       |
| ------ | --------------------------------------------- | --------------------------------------------- |
| `POST` | `/api/2/swap/advanced-orders/intent`          | Build the canonical intent message to sign.   |
| `POST` | `/api/2/swap/advanced-orders`                 | Create the signed order.                      |
| `GET`  | `/api/2/swap/advanced-orders`                 | List owner orders. Requires a read signature. |
| `GET`  | `/api/2/swap/advanced-orders/:orderId`        | Read one order. Requires a read signature.    |
| `POST` | `/api/2/swap/advanced-orders/:orderId/cancel` | Cancel an open or triggered order.            |

## End-to-End Flow

Advanced Orders are deposit-backed intents. The user keeps custody of their wallet keys and never gives Mobula a reusable approval, session key, or delegated signing power. The only funds Mobula can execute with are the exact tokens the user transfers to the Mobula deposit wallet for that order.

<Note>
  The deposited amount is held in the Mobula deposit wallet while the order is open. If the order is cancelled, expires, or cannot execute, the settlement flow refunds the confirmed deposit to the owner.
</Note>

| Step | Actor                   | What happens                                                                                                                                                                                                                |
| ---- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | Integrator              | Use the Mobula-provided deposit wallet for the environment. The end user must not choose this address.                                                                                                                      |
| 2    | User wallet             | Transfer exactly `amountRaw` of `tokenIn` from `ownerAddress` to the Mobula deposit wallet.                                                                                                                                 |
| 3    | Client                  | Call `POST /api/2/swap/advanced-orders/intent` with the deposit transaction hash and all order parameters.                                                                                                                  |
| 4    | Mobula API              | Normalizes the payload, resolves the server deposit wallet, validates addresses and amounts, then returns the canonical `message` to sign.                                                                                  |
| 5    | User wallet             | Signs the canonical `message`. This signature covers the chain, owner, recipient, tokens, amounts, trigger settings, expiry, deposit transaction, routing restrictions, and fees.                                           |
| 6    | Client                  | Call `POST /api/2/swap/advanced-orders` with the same fields plus `intentSignature`.                                                                                                                                        |
| 7    | Mobula API              | Verifies the owner signature and stores the order idempotently by intent hash.                                                                                                                                              |
| 8    | Mobula worker           | Polls open orders every few seconds and verifies the deposit transaction on-chain. The deposit must be finalized, successful, sent by `ownerAddress`, sent to the Mobula deposit wallet, and match `tokenIn` + `amountRaw`. |
| 9    | Mobula worker           | Watches `swaps-stream` for relevant token/pair updates. For TP/SL it pre-checks quote movement; for Triggers it confirms the configured Token Details fields through `getTokenData`.                                        |
| 10   | Mobula execution engine | Claims the order, builds a fresh quote with the order constraints, checks `minAmountOutRaw`, signs only the swap transaction for the deposit wallet, and broadcasts it.                                                     |
| 11   | Mobula settlement       | Confirms the broadcasted transaction. If filled, output funds are sent to `recipientAddress`. If cancelled, expired, or non-executable, the confirmed deposit is refunded to `ownerAddress`.                                |

## Non-Custodial Guarantees

| Guarantee                                    | How it is enforced                                                                                                                          |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Mobula cannot trade from the user's wallet   | The user only signs an intent message, not a transaction spending future wallet balances.                                                   |
| Mobula cannot mutate the order after signing | The canonical message includes the full order payload. Changing any signed field changes the intent hash and invalidates the signature.     |
| Mobula cannot use a different deposit        | Deposit verification checks the exact finalized transfer: owner, deposit wallet, token, and raw amount.                                     |
| Mobula cannot bypass the output guard        | Execution always checks the fresh quote against `minAmountOutRaw` before sending.                                                           |
| The user can exit before execution           | The owner can cancel open/triggered orders with a signed cancel message. Confirmed deposits are then handled by the refund settlement flow. |

## Client Checklist

1. Build and send the token transfer to the Mobula deposit wallet.
2. Wait for the deposit transaction signature.
3. Call `POST /advanced-orders/intent`.
4. Ask the owner wallet to sign `data.message`.
5. Call `POST /advanced-orders` with `intentSignature`.
6. Poll `GET /advanced-orders` or `GET /advanced-orders/:orderId`.
7. To cancel, sign the canonical cancel message and call `POST /advanced-orders/:orderId/cancel`.

## Stop Loss Parameters

| Field                 | Value                                                   |
| --------------------- | ------------------------------------------------------- |
| `orderKind`           | `stop_loss`                                             |
| `triggerDirection`    | `lte`                                                   |
| `triggerAmountOutRaw` | Stop threshold.                                         |
| `minAmountOutRaw`     | Hard execution floor. Must be `<= triggerAmountOutRaw`. |
| `expiresAt`           | Future ISO date, max 90 days.                           |

## Stop Loss Intent Body

```json theme={null}
{
  "chainId": "solana:solana",
  "ownerAddress": "<OWNER>",
  "recipientAddress": "<OWNER>",
  "tokenIn": "<TOKEN_MINT>",
  "tokenOut": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amountRaw": "1000000000",
  "minAmountOutRaw": "830000",
  "triggerAmountOutRaw": "850000",
  "triggerDirection": "lte",
  "orderKind": "stop_loss",
  "slippage": 2,
  "depositTransactionHash": "<DEPOSIT_TX_SIGNATURE>",
  "expiresAt": "2026-08-01T00:00:00.000Z",
  "onlyRouters": ["mobula"]
}
```

<Note>
  For `lte` orders, `minAmountOutRaw` cannot be higher than `triggerAmountOutRaw`.
</Note>

## Create a Stop Loss Order

```ts theme={null}
const intent = await fetch("https://api.mobula.io/api/2/swap/advanced-orders/intent", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>",
  },
  body: JSON.stringify(intentBody),
}).then((res) => res.json());

const intentSignature = await wallet.signMessage(intent.data.message);

await fetch("https://api.mobula.io/api/2/swap/advanced-orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>",
  },
  body: JSON.stringify({ ...intentBody, intentSignature }),
});
```

## Read

Read signatures use:

```txt theme={null}
Mobula Advanced Order Read v1
{"ownerAddress":"<OWNER_ADDRESS>"}
```

```bash theme={null}
curl "https://api.mobula.io/api/2/swap/advanced-orders?ownerAddress=<OWNER>&readSignature=<SIGNATURE>" \
  -H "x-api-key: <YOUR_API_KEY>"
```