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

# Notifications

> This section covers push notifications to the mobile app and to browsers, notification preferences, and the in-app notification history.

Pacifica can tell you when something happens on your account, for example when an order fills or a deposit completes. It delivers each notification on one or more channels:

| Channel | Delivery |
| - | - |
| `in_app` | Pacifica keeps the notification in the account's history. Read it with [Get notification history](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-notification-history.md) |
| `mobile_push` | Pacifica sends a push to the Pacifica mobile app through Expo |
| `web_push` | Pacifica sends a push to browsers and installed web apps (PWAs) through the Web Push protocol |

Notifications are off by default. To get a notification, turn on its channel in the master preference and for its notification type. See [Preferences](#preferences).

* [Register Expo device](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/register-expo-device.md): This endpoint allows users to register an Expo push token so that the mobile app receives push notifications.
* [Unregister Expo device](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/unregister-expo-device.md): This endpoint allows users to stop push notifications to an Expo push token or app installation.
* [Get Web Push config](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-web-push-config.md): This endpoint allows users to check if Web Push is available and to get the VAPID public key.
* [Register Web Push subscription](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/register-web-push-subscription.md): This endpoint allows users to register a browser's Web Push subscription.
* [Get Web Push subscription status](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-web-push-subscription-status.md): This endpoint allows users to check if a browser installation gets Web Push notifications.
* [Unregister Web Push subscription](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/unregister-web-push-subscription.md): This endpoint allows users to stop Web Push notifications to a browser installation.
* [List notification preferences](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/list-notification-preferences.md): This endpoint allows users to get the notification channels that are on for an account.
* [Set notification preference](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/set-notification-preference.md): This endpoint allows users to turn a channel on or off for one or more notification types.
* [Set notification master preference](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/set-notification-master-preference.md): This endpoint allows users to turn a channel on or off with the account's master switch.
* [Send test notification](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/send-test-notification.md): This endpoint allows users to send a test notification on the account's enabled channels.
* [Get notification history](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-notification-history.md): This endpoint allows users to get an account's recent in-app notifications and unread count.
* [Mark notifications seen](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/mark-notifications-seen.md): This endpoint allows users to mark notifications as seen.

### Notification types

Each notification has a `notification_type`. You set preferences for these types:

| `notification_type` | When Pacifica sends it | Title |
| - | - | - |
| `deposit_success` | A USDC or spot deposit completes | `Deposit confirmed` |
| `withdraw_success` | A USDC or spot withdrawal completes | `Withdrawal complete` |
| `order_filled` | An order fills completely | `Order filled` |
| `order_partially_filled` | A non-market order fills in part. Each partial fill sends a notification | `Order partially filled` |
| `order_canceled` | An order is cancelled, force-cancelled, or expires | `Order canceled` |
| `tp_sl_triggered` | A take profit or stop loss order triggers | `TP/SL triggered` |
| `liquidation` | A position is liquidated | `Position liquidated` |
| `strategy_update` | An [order strategy](https://docs.pacifica.fi/api-documentation/api/rest-api/order-strategies) changes state | See below |

Orders that an order strategy places also send order notifications.

[Send test notification](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/send-test-notification.md) sends the `test` type. You can't set preferences for `test`.

The API schema also lists `account`, `trading`, `risk`, `price_alert`, and `announcement`. Pacifica doesn't send these types now, and you can't set preferences for them.

**Strategy updates**

A `strategy_update` notification has an `outcome` in its `data`:

| `outcome` | Title | When |
| - | - | - |
| `triggered` | `Strategy triggered` | The strategy's trigger fires and it starts to trade, or an OCO or conditional strategy completes |
| `completed` | `Strategy completed` | Any other strategy type completes |
| `cancelled` | `Strategy stopped` | The strategy is cancelled for a reason other than your cancel |
| `expired` | `Strategy expired` | The strategy expires |
| `failed` | `Strategy failed` | The strategy or its trigger order fails |

Pacifica doesn't send a notification when a strategy starts, pauses, or resumes, or when you cancel it.

### Notification data

Each notification has a `title`, a `body`, and a `data` object. The `title` and `body` are English text for display. Use `data` to route a tap or click in your app.

`data` always contains `notification_type` and `kind`. Both are set to the notification type. The other fields depend on the type. Decimal values are strings. IDs are strings.

**Orders** (`order_filled`, `order_partially_filled`, `order_canceled`, `tp_sl_triggered`)

<table><thead><tr><th width="208">Field</th><th width="186">Type</th><th>Description</th></tr></thead><tbody><tr><td>`"order_id"`</td><td>string</td><td>Order ID</td></tr><tr><td>`"symbol"`</td><td>string</td><td>Market symbol</td></tr><tr><td>`"base_symbol"`</td><td>string</td><td>Same as `"symbol"`</td></tr><tr><td>`"side"`</td><td>string</td><td>`"buy"` or `"sell"`</td></tr><tr><td>`"order_type"`</td><td>string</td><td>`"limit"`\
`"market"`\
`"stop limit"`\
`"stop market"`\
`"take profit"`\
`"stop loss"`</td></tr><tr><td>`"price"`</td><td>decimal string</td><td>Order price</td></tr><tr><td>`"initial_amount"`</td><td>decimal string</td><td>`order_partially_filled` only. Order amount</td></tr><tr><td>`"filled_amount"`</td><td>decimal string</td><td>`order_partially_filled` and `order_filled` only. Amount filled</td></tr><tr><td>`"last_filled_price"`</td><td>decimal string</td><td>`order_filled` only. Price of the last fill</td></tr><tr><td>`"cancel_reason"`</td><td>string</td><td>`order_canceled` only:\
`"canceled"`\
`"force_canceled"`\
`"expired"`</td></tr><tr><td>`"stop_price"`</td><td>decimal string</td><td>`tp_sl_triggered` only. Trigger price. Omitted when the order has no stop price</td></tr><tr><td>`"trigger_kind"`</td><td>string</td><td>`tp_sl_triggered` only. `"take_profit"` or `"stop_loss"`</td></tr></tbody></table>

**Liquidations** (`liquidation`)

<table><thead><tr><th width="208">Field</th><th width="186">Type</th><th>Description</th></tr></thead><tbody><tr><td>`"history_id"`</td><td>string</td><td>Trade history ID</td></tr><tr><td>`"order_id"`</td><td>string or null</td><td>Order ID of the liquidation</td></tr><tr><td>`"symbol"`</td><td>string</td><td>Market symbol</td></tr><tr><td>`"base_symbol"`</td><td>string</td><td>Same as `"symbol"`</td></tr><tr><td>`"position_side"`</td><td>string</td><td>`"long"` or `"short"`</td></tr><tr><td>`"amount"`</td><td>decimal string</td><td>Amount liquidated</td></tr><tr><td>`"price"`</td><td>decimal string</td><td>Liquidation price</td></tr><tr><td>`"entry_price"`</td><td>decimal string</td><td>Entry price of the position</td></tr><tr><td>`"pnl"`</td><td>decimal string</td><td>Realized PnL</td></tr><tr><td>`"cause"`</td><td>string</td><td>`"market_liquidation"`\
`"backstop_liquidation"`\
`"insolvency_liquidation"`</td></tr></tbody></table>

**Deposits and withdrawals** (`deposit_success`, `withdraw_success`)

<table><thead><tr><th width="208">Field</th><th width="186">Type</th><th>Description</th></tr></thead><tbody><tr><td>`"history_id"`</td><td>string</td><td>`deposit_success` only. Deposit history ID</td></tr><tr><td>`"signature"`</td><td>string</td><td>`deposit_success` only. Deposit transaction signature</td></tr><tr><td>`"withdraw_id"`</td><td>string</td><td>`withdraw_success` only. Withdrawal ID</td></tr><tr><td>`"tx_hash"`</td><td>string</td><td>`withdraw_success` only. Withdrawal transaction hash</td></tr><tr><td>`"asset"`</td><td>string</td><td>`"USDC"`, or the spot asset</td></tr><tr><td>`"symbol"`</td><td>string</td><td>Spot deposits and withdrawals only. Spot asset symbol</td></tr><tr><td>`"amount"`</td><td>decimal string</td><td>Amount</td></tr></tbody></table>

**Strategy updates** (`strategy_update`)

<table><thead><tr><th width="208">Field</th><th width="186">Type</th><th>Description</th></tr></thead><tbody><tr><td>`"strategy_id"`</td><td>UUID</td><td>Strategy ID</td></tr><tr><td>`"type"`</td><td>string</td><td>Strategy type, for example `"twap"`</td></tr><tr><td>`"symbol"`</td><td>string</td><td>Market symbol that the strategy trades</td></tr><tr><td>`"base_symbol"`</td><td>string</td><td>Same as `"symbol"`</td></tr><tr><td>`"lifecycle"`</td><td>string</td><td>The strategy's [lifecycle](https://docs.pacifica.fi/api-documentation/api/rest-api/order-strategies) after the change</td></tr><tr><td>`"outcome"`</td><td>string</td><td>What happened. See Strategy updates above</td></tr><tr><td>`"terminal_reason"`</td><td>string or null</td><td>Why the strategy ended, for example `"insufficient_balance"`. Show your own label for this code</td></tr></tbody></table>

### Preferences

An account has a master preference and a preference for each notification type. Each preference is a set of channels.

* Pacifica uses a channel only when the channel is on in the master preference and in the type's preference.
* All channels start off. A missing preference counts as off.
* The master preference doesn't change the type preferences. You can turn a channel off in the master preference to pause it, and turn it on again later.
* Pacifica picks the channels when it creates a notification. A later preference change doesn't change notifications that already exist.
* Turning on a type doesn't backfill notifications for older events.
* The `test` type uses only the master preference.

For example, to get order fills on the mobile app and in the history, turn on `mobile_push` and `in_app` with [Set notification master preference](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/set-notification-master-preference.md). Then turn on the same channels for `order_filled` with [Set notification preference](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/set-notification-preference.md).

### Mobile push (Expo)

1. On the first install, generate at least 128 random bits. Encode them as a string, for example hexadecimal. Keep this installation key in the device's secure storage.
2. Get the Expo push token from the Expo SDK.
3. Call [Register Expo device](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/register-expo-device.md) with the token, the `platform`, and the installation key as `device_id`.
4. Turn on `mobile_push` in the master preference and for the types that you want.
5. When the user signs out, call [Unregister Expo device](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/unregister-expo-device.md).

Keep the installation key secret. Don't use a hardware ID or a user ID. The key proves that a request comes from the installation that owns the token.

The push `data` is the notification's `data` object. Route a tap by `data.notification_type`.

### Web Push

1. Call [Get Web Push config](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-web-push-config.md). If `enabled` is `false`, hide Web Push in your app. Otherwise, read `vapid_public_key`.
2. Generate an `installation_id` of 32 to 64 characters from `A-Z`, `a-z`, `0-9`, `-`, and `_`. Store it where the page and the service worker can both read it, for example IndexedDB.
3. In the browser, call `pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: vapid_public_key })`.
4. Call [Register Web Push subscription](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/register-web-push-subscription.md) with the subscription's endpoint and keys.
5. Turn on `web_push` in the master preference and for the types that you want.
6. In the service worker, show each push with `showNotification`. Use `notification_id` as the `tag`.
7. When the page loads, call [Get Web Push subscription status](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-web-push-subscription-status.md). If `state` is `expired` or `key_rotated`, subscribe again and register again.
8. When the user signs out or switches account, call [Unregister Web Push subscription](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/unregister-web-push-subscription.md).

Each push carries this encrypted JSON payload:

```json theme={null}
{
  "version": 1,
  "notification_id": 81234,
  "subscription_id": "3f1c2a7e-9b4d-4e8a-8c2f-6d5b1a0e9f47",
  "title": "Order filled",
  "body": "Your buy BTC order filled at 97000.",
  "data": {
    "notification_type": "order_filled",
    "kind": "order_filled",
    "order_id": "315992721",
    ...
  },
  "created_at_ms": 1716200000000
}
```

`notification_id` is the `id` that [Get notification history](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-notification-history.md) returns. Route a click by `data.notification_type`.

### History and seen

* [Get notification history](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/get-notification-history.md) returns only notifications that Pacifica created with the `in_app` channel on. Push-only notifications aren't in the history.
* It returns the 100 newest notifications, newest first. It has no pagination.
* `unread_count` counts all in-app notifications that aren't seen. It can be more than 100.
* [Mark notifications seen](https://docs.pacifica.fi/api-documentation/api/rest-api/notifications/mark-notifications-seen.md) marks the IDs that you send. There is no "mark all" call. Send the IDs that you show.
* Seen state belongs to the account. All the account's devices and browsers see the same state.

### Delivery

* Pacifica sends a push only in the first 15 minutes after it creates the notification. After that, it drops the push. The notification stays in the history if `in_app` was on.
* Pacifica sends a `mobile_push` notification to every active Expo token on the account. It turns off a token when Expo reports that the device is no longer registered.
* Pacifica sends a `web_push` notification to every active Web Push subscription on the account. It turns off a subscription when the push service reports that the subscription is gone.
* A push service accepting a push doesn't mean the device showed it.

### Signing and limits

| Endpoint | Who can sign |
| - | - |
| Register Expo device, Register Web Push subscription | The account key only |
| Get Web Push config | No signature |
| All other notification endpoints | The account key or an [agent wallet](https://docs.pacifica.fi/api-documentation/api/signing/api-agent-keys.md) |

* An account keeps up to 10 active Web Push subscriptions. When you register one more, Pacifica turns off the subscription that was registered longest ago.
* An app installation has one active Expo token for each account. When you register a new token with the same `device_id`, Pacifica turns off the old token.
* The account must exist. An account exists after its first deposit. Other accounts get status 403.
* The standard [rate limits](https://docs.pacifica.fi/api-documentation/api/rate-limits) apply.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.