Propose creating, editing or deleting an alert (user approves)
propose_alert_changePropose a change to the user's price and value alerts: create a new one, edit one, or delete one, picked by action. Use this when the user asks to be told when something happens ("alert me if BTC drops below 60k", "email me when my portfolio passes 100k") or to change or remove an alert; to see which alerts exist, and their ids, call get_alerts instead, and always call it before an update or delete. This does NOT take effect when you call it: it returns a link the user has to open and approve in their own browser, so tell them to open it rather than saying it is done. Alerts are a Pro feature: an account without Pro gets upgrade_required, and a connection the user did not grant "propose changes" gets write_not_permitted; read either out and stop. Arguments by action. create: kind, op, threshold, plus subject for the asset kinds, optional repeat, cooldownSec, channels, note. update: alertId plus only the fields to change (op, threshold, enabled, repeat, cooldownSec, channels, note); kind and subject cannot be edited, so delete and re-create instead. delete: alertId only. An argument the action does not take is refused, not ignored.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | Fire when the watched value goes above or below the threshold. | |
| kind | No | create only. What the alert watches: asset_price (one asset's USD price), asset_pct (one asset's 24h % change), portfolio_value (total USD value), portfolio_pct (portfolio 24h % change), holding_value (USD value of the user's position in one asset), holding_weight (one asset's share of the portfolio, %). | |
| note | No | A short note shown with the alert, up to 200 characters. On update, an empty string clears it. | |
| action | Yes | create a new alert, update an existing one (by alertId), or delete one (by alertId). | |
| repeat | No | once (default): fire one time, then pause. recurring: fire every time the level is crossed again, no more often than cooldownSec. | |
| alertId | No | update and delete only: the `id` of the alert, exactly as get_alerts returns it. | |
| enabled | No | update only: false pauses the alert, true turns it back on. | |
| profile | No | Which portfolio to read, for accounts with more than one: its id, or its name (exact, case-insensitive, e.g. "Trading"). Omit to read this connection's default portfolio; every answer names the portfolio it read in `profile`. An unknown or shared name returns profile_not_found or profile_ambiguous listing the real ones, and list_profiles shows them up front. | |
| subject | No | create only, and required for asset_price, asset_pct, holding_value and holding_weight: the ticker, e.g. BTC. Omit for the portfolio kinds. | |
| channels | No | Where it is delivered. ["inapp"] (default) shows it in the app's notifications; ["inapp", "email"] also emails the user (the app's "Also email me" option). | |
| threshold | No | The trigger level, in the kind's unit: USD for asset_price, portfolio_value and holding_value (greater than 0); percent for asset_pct and portfolio_pct (signed, so -10 means a 10% drop); percent of the portfolio, 0 to 100, for holding_weight. | |
| cooldownSec | No | recurring alerts: minimum seconds between two notifications, 60 to 604800. Omit for the default (1 hour, or 6 hours for the % and allocation kinds). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present ONLY when the call was refused instead of answered: upgrade_required (Pro plan needed), not_found, profile_not_found, profile_ambiguous, invalid_arguments, write_not_permitted. No data fields come with it; read `message` to the user rather than retrying the same call. | |
| title | No | What the change does. | |
| status | No | Always this: nothing has been applied yet. | |
| message | No | Plain-language explanation that accompanies `error`, `data_status` or a proposed change. Read it to the user. | |
| preview | No | Courtesy diff; the authoritative one is on the confirm page. | |
| profile | No | The portfolio these figures belong to (absent on list_profiles). | |
| next_step | No | What the user should do about data_status. | |
| expires_at | No | When the link stops working, epoch ms. | |
| source_url | No | Link to the page in the WhereItGoes app that shows this data. | |
| confirm_url | No | The link the user must open and approve; tell them to open it. | |
| data_status | No | Present only when the portfolio has no data yet. nothing_connected: no exchange and no wallet is connected, so empty lists and zeros mean "no data", NOT a $0 portfolio, and no data fields come with it (except on get_connections, get_alerts, get_target_allocation and list_profiles, which also answer). Send the user to next_step. syncing: a source is connected but its first sync is still running, so figures are partial and not final. | |
| upgrade_url | No | Where the user can upgrade, on an upgrade_required refusal. | |
| stock_assets | No | Present when the answer mentions Binance Stocks shares (EQ_<ticker>): they are US stocks, not crypto. |