Swaping Use Case

(Mandatory for Graduation) - Swap Notification for Different Scenarios

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.

A notification is important in this case because cross-chain swaps often involve operations that occur outside of the ACP platform, such as third-party routers, external bridges, or off-platform settlement mechanisms. Since ACP cannot display real-time progress for these external steps, the user would otherwise have no visibility into what is happening after they initiate the swap.

You can choose which phases to implement depending on your agent’s flow, but this represents the best-case, fully transparent UX.

Bridge Transfer Initiated (Cross-chain only)

Sent when bridging begins (this is the part happening outside ACP).

Notification Example:

“Cross-chain transfer initiated. Your tokens are now moving to ${network_to}. This step may take a few minutes.”

Bridge Transfer Completed (Cross-chain only)

Once funds arrive on destination chain.

Notification Example:

“Cross-chain transfer completed on ${network_to}. Finalizing swap…”

Final Swap Settlement

Two Approaches for Settlement Notifications

In both cases, the notification must include a transaction explorer link so the user can verify the on-chain transaction directly.

A. Settlement From System Wallet → Service Provider Wallet → User

This applies when the system wallet sends funds to the service provider wallet (seller wallet), which then returns funds to the user through a payable notification.

Implementation

• The system wallet handles the settlement logic.

• Use job.createPayableNotification() to return funds back to the user.

• Transaction link is not needed as the memo itself serves as the transfer transaction.

Notification Example

await job.createPayableNotification(
  "Swap completed and settlement processed. Payout has been returned to your wallet",
  new FareAmount(
    totalDistributed,
    config.baseFare
  )
);

B. Settlement From System Wallet → User (job.clientAddress)

This applies when your system wallet performs the settlement transaction directly and funds are sent straight to the user’s wallet.

Implementation

• Recipient is job.clientAddress.

• Use job.createNotification() since the settlement happens outside ACP.

• Include a full transaction explorer link inside the notification.

Notification Example

await job.createNotification(
    `Swap settled successfully. Funds have been sent to your wallet. 
    View transaction: https://basescan.org/tx/${txnHash}`
);