Skip to main content
When a risk rule breaches, the engine always opens an alert. What it does beyond that is decided by the rule’s outcome.

​
The three outcomes

​
alert

Notify only. The engine opens an alert and emits the portfolio_wallet.risk.alert.triggered webhook. No funds move and no action is created. Use this to observe a source before deciding to act.

​
prevent_additional_allocation

While the alert is open, the rebalancer is blocked from buying into the affected yield source. Funds already in the source stay put; the engine simply stops adding more. Once the metric recovers and the alert resolves, allocation into the source is allowed again.

​
exit_position

The engine exits the position in the affected source. It redeems the holdings and redeploys them into the wallet’s other eligible yield sources, falling back to the wallet’s cash account when no other yield source is available. This is the strongest response and is meant for a source you want out of entirely on breach.

​
Approval modes

Any non-alert outcome requires an approvalMode:
  • automatic: the engine carries out the outcome on its own as soon as the rule breaches.
  • approval_required: the engine creates the action and waits for you to approve it before anything happens.
alert outcomes have no approval mode.

​
Actions

For prevent_additional_allocation and exit_position outcomes (and any approval_required outcome), the engine creates a risk action tied to the alert. The action moves through these statuses:
StatusMeaning
pending_approvalWaiting for you to approve or reject (approval_required)
pending_auto_executionQueued to run on its own (automatic)
executingIn progress
executedCompleted
rejectedDeclined, or cancelled because the rule changed, paused, or was deleted
failedExecution did not complete
Every status change emits the portfolio_wallet.risk.action.status_changed webhook.

​
List actions

curl -X GET "$BASE_URL/v2/wallets/risk/actions?status=pending_approval" \
  -H "Authorization: Bearer $API_TOKEN"
You can filter by status and outcome, and scope to one or more wallets.

​
Approve or reject an action

For approval_required actions, submit your decision with a PATCH: 
curl -X PATCH "$BASE_URL/v2/wallets/risk/actions/$RISK_ACTION_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'
Send "approved" to execute the action, or "rejected" to decline it. Approving an exit_position action begins the redeem-and-redeploy flow; rejecting it leaves the position untouched (the alert stays open until the metric recovers).
If a rule is edited, paused, or deleted while one of its actions is still pending, that action is rejected automatically and a portfolio_wallet.risk.action.status_changed webhook is emitted.

​
Monitoring

Drive your automation off the webhooks rather than polling:
  • portfolio_wallet.risk.alert.triggered: a rule breached and an alert opened.
  • portfolio_wallet.risk.action.status_changed: an action was created, approved, executed, rejected, or failed.
See Webhooks to register endpoints and verify deliveries. Webhooks are best-effort, so back them with periodic GET /v2/wallets/risk/actions polling.

​
Next steps