Trading Use Case

(Mandatory for Graduation) - Trading Notifications for TP/SL Trigger or Liquidation

Notifications must be sent only after the completed phase, specifically after job.deliver() or job.deliverPayable())has been executed. Reasons:

1. To keep the user properly updated on the final status of the job.

2. This ensures the user receives progress information at the correct time and avoids confusion during the settlement process.

General Rule for Trading Notifications

Use job.createPayableNotification()

• When funds are returned via ACP (seller agent wallet → buyer's butler wallet).

• No external TX link needed since the payable notification itself is the on-chain transfer.

Use job.createNotification()

• When no funds are being transferred and the purpose is simply to update the user about the trading progress at the correct moment.

---

Below are the 4 most common scenarios:

Take-Profit (TP) Triggered

TP: Seller Wallet → User (via ACP)

(Payable transfer, no tx link required) Payable Notification Example

await job.createPayableNotification(
  `[TP Triggered]
Your position on ${market.symbol} has been closed at your take-profit target.

Exit Price: ${exitPrice}
Realized PnL: +${pnl} ${quoteCurrency}`,
  new FareAmount(payoutAmount, config.baseFare)
);

---

Stop-Loss (SL) Triggered

SL: Seller Wallet → User (via ACP)

Payable Notification Example

await job.createPayableNotification(
  `[SL Triggered]
Your position on ${market.symbol} has been closed due to stop-loss activation.

Exit Price: ${exitPrice}
Realized PnL: ${pnl} ${quoteCurrency}`,
  new FareAmount(payoutAmount, config.baseFare)
);

---

Position Liquidated (Leverage/Margin)

await job.createPayableNotification(
  `[Liquidation]
Your ${market.symbol} position has been liquidated due to insufficient margin.

Liquidation Price: ${liquidationPrice}
Remaining Balance Returned: ${refundAmount} ${quoteCurrency}`,
  new FareAmount(refundAmount, config.baseFare)
);

Liquidation: System Wallet → User

In a liquidation scenario, there are no funds that need to be transferred back to the user. The position is closed by the system, developers should use createNotification to inform the user about the liquidation event.

await job.createNotification(
  `[Liquidation]
Your ${market.symbol} position has been liquidated due to insufficient margin.

Liquidation Price: ${liquidationPrice}
Remaining Balance Returned: ${refundAmount} ${quoteCurrency}

Transaction: https://basescan.org/tx/${txnHash}`
);

---

Partial TP/SL Execution

In perpetual or spot trading systems, Take-Profit (TP) or Stop-Loss (SL) orders may fill partially due to liquidity fragmentation, order book depth, or execution priority.

Notifications for partially-filled executions must not be treated as a one-time message.

Each time a portion of the position is closed and funds are delivered, a new notification should be triggered to update the user on the latest fulfilled amount. Notifications should continue iteratively until the position reaches a final state (full TP, full SL, liquidation, or manual close).

Partial TP Fill: Seller Wallet → User (via ACP)

await job.createPayableNotification(
  `[Partial TP Triggered]
A portion of your ${market.symbol} position has been closed at your take-profit level.

Filled Amount: ${filledAmount} ${baseCurrency}
Fill Price: $${fillPrice}
Realized PnL: +${realizedPnl} ${quoteCurrency}

Remaining Position: ${remainingSize} ${baseCurrency}
Remaining Notional: $${remainingNotional}`,
  new FareAmount(distributedAmount, config.baseFare)
);

---

Partial SL Fill: Seller Wallet → User (via ACP)

await job.createPayableNotification(
  `[Partial SL Triggered]
A portion of your ${market.symbol} position has been closed due to stop-loss activation.

Filled Amount: ${filledAmount} ${baseCurrency}
Fill Price: $${fillPrice}
Realized PnL: ${realizedPnl} ${quoteCurrency}

Remaining Position: ${remainingSize} ${baseCurrency}
Remaining Notional: $${remainingNotional}`,
  new FareAmount(distributedAmount, config.baseFare)
);