API referenceWebhooks
Webhook event catalogue
Every webhook event the platform sends today, grouped by domain, with its lifecycle state, its trigger and the action your endpoint takes.
This page lists every webhook event the platform sends today: its lifecycle state, when the platform sends it and what your endpoint does with it. Payload fields, schemas and examples are not here. They live in the machine-readable event definitions and in the Webhook types of @settlemint/dalp-sdk. Subscriptions, lifecycle states and consuming rules have their own pages.
In a State cell, beta is an event-contract maturity label. It is not a value of the envelope's lifecycle_state field.
Before using payload fields
New endpoints use thin payloads, which omit personal data fields. Some actions below need fields such as accountAddress or subjectAddress. Configure fat payloads and acknowledge the required fields before the platform records those events if your receiver needs the addresses. The payload-shape rules describe this change. Replay sends the stored payload, so it cannot recover fields already removed from a thin event.
Find the event for your question
| Question | Go to |
|---|---|
| Did a transfer settle, or did a reorg undo it? | Token |
| Did a mint or burn happen, or was an asset paused? | Asset |
| Was a corporate action announced or completed, a fee charged, or a document published? | Token |
| Was a holder's balance frozen or released, or did a provider return a verification verdict? | Compliance |
| Was a role granted or revoked? | Access control |
| Was an identity registered or recovered, or a claim issued or revoked? | Identity |
| Does an address need gas funding before a write can run? | Funding |
| Did a deposit or withdrawal change a custody participant's balance, or did a smart account change? | Custody |
| Did a token sale open, take a purchase, pay a refund or close? | Primary market |
| Was an exchange-versus-payment settlement approved, executed, cancelled or expired? | XvP settlement |
| Did an order change, a trade settle, or a bust reverse a trade? | Trading venue |
| Is there a confirmation of a token movement for one wallet? | Reporting |
Access control
An access manager is the contract that records which accounts hold which roles. A role change has no final event: apply it when the provisional event arrives, and undo it when the matching retracted event arrives. A chain reorganization (reorg) replaces recent blocks. After a reorg removes the block of a role change, the platform sends a retracted event only when it recorded a successful delivery of the provisional event. If your acknowledgement was lost, the platform can cancel the event and send no retraction. Reconcile an uncertain role against the current canonical transaction receipt and its logs. Retractions states the rule.
| Event | State | Sent when | What to do |
|---|---|---|---|
access-control.role-granted.provisional | provisional | The platform reads a role grant on an access manager in a block that has not reached chain finality. | Add the role for accountAddress on accessManagerAddress. A role applies to that access manager only, not to the account on other managers. |
access-control.role-granted.retracted | retracted | A reorg removes the block of a role grant after the platform recorded a successful delivery of access-control.role-granted.provisional to your endpoint. | Remove the role that the event named in supersedes added. |
access-control.role-revoked.provisional | provisional | The platform reads a role revocation on an access manager in a block that has not reached chain finality. | Remove the role for accountAddress on accessManagerAddress. Roles on other access managers stay as they are. |
access-control.role-revoked.retracted | retracted | A reorg removes the block of a role revocation after the platform recorded a successful delivery of access-control.role-revoked.provisional to your endpoint. | Restore the role that the event named in supersedes removed. |
Asset
Asset events report changes to a tokenized asset, read from chain logs. A block reaches chain finality when the chain is the reorg depth past it, a number of blocks set for the network. The platform sends a final asset event at that point and never retracts it.
| Event | State | Sent when | What to do |
|---|---|---|---|
asset.burn.final | final | Token units are burned from a holder on chain. | token.transfer.final also reports the burn. Match transferSourceId to that event's source_id and book the burn once. |
asset.created.final | final | An asset factory deploys a new asset token, and the platform indexes the token for the first time. | Register the asset by assetAddress. The event reports no supply: each mint arrives as an asset.issuance.final event. |
asset.issuance.final | final | New token units are minted to a recipient on chain. | token.transfer.final also reports the mint, with the all-zero address as sender. Match transferSourceId to that event's source_id and book the issuance once. |
asset.issuance.provisional | provisional | The platform indexes a block that holds a mint of token units, before the block reaches chain finality. | asset.issuance.final confirms the mint. If a reorg removes the block, asset.issuance.retracted replaces this event. |
asset.issuance.retracted | retracted | A reorg removes the block of a mint after the platform recorded a successful delivery of asset.issuance.provisional to your endpoint. | Reverse the issuance you recorded for the event named in supersedes. |
asset.pause.final | final | A token contract logs a pause. | The pause already took effect on chain. Stop submitting transfers for the asset until asset.unpause.final arrives. |
asset.unpause.final | final | A token contract logs an unpause. | Allow transfers for the asset again. |
Compliance
Freeze events report that a holder's balance of an asset was frozen or released, and the platform reads them from the logs of the asset contract. The verification verdict event reports a connected provider's decision and has no chain log behind it.
| Event | State | Sent when | What to do |
|---|---|---|---|
compliance.freeze.final | final | The block that froze a holder's balance of an asset reaches chain finality. scope is address when the whole address is frozen and amount when a set number of token units is frozen. | Treat the freeze as confirmed: the platform does not retract a final event. Skip it if you already applied compliance.freeze.provisional with the same transactionHash and logIndex. |
compliance.freeze.provisional | provisional | The platform reads a freeze on a holder's balance of an asset in a block that has not reached chain finality. | Apply the freeze. compliance.freeze.final confirms it after chain finality, and compliance.freeze.retracted replaces it if a reorg removes the block. |
compliance.freeze.retracted | retracted | A reorg removes the block of a freeze after the platform recorded a successful delivery of compliance.freeze.provisional to your endpoint. | Reverse the freeze that the event named in supersedes applied. |
compliance.unfreeze.final | final | The block that released a freeze on a holder's balance reaches chain finality. scope is address when a whole-address freeze is released and amount when a set number of token units is released. | Lift the freeze only on this event: the platform sends no provisional event for a release. |
compliance.verification-verdict.final | final beta | The platform applies a connected provider's verdict on a subject, such as a know-your-customer (KYC) check, and completes any claim write the verdict needs. A verdict that the platform does not apply, such as an out-of-date one, sends nothing. | Read status for the verdict and claimEffect to see whether the platform issued a claim, revoked one or changed none. The claim change reaches you later as identity.claim-issued.final or identity.claim-revoked.final. |
Custody
A System is an organization's on-chain DALP deployment, and its account factory creates smart accounts, which are contract wallets. Custody events report those accounts, including changes to their signing rules, and the cash balances of custody participants, and the account events reach only endpoints on the System that owns the account. The deposit, withdrawal and fee events give amount as a decimal string in base units, the smallest unit of the asset that assetKey names.
| Event | State | Sent when | What to do |
|---|---|---|---|
custody.account-created.final | final | A System's account factory creates a smart account, and its block reaches chain finality. The platform sends nothing when it cannot match the factory to a System. | Record accountAddress and its first owner, ownerAddress. identityAddress is null when the account has no identity bound at creation. |
custody.deposit-held.retracted | retracted beta | After a reorg, the chain no longer shows a deposit that custody.deposit.held reported before it cleared. The platform takes the value back from the participant's held balance and sends this event. | Remove the held amount you booked for the same depositId. supersedes is optional and names custody.deposit.held when the platform queued it for your endpoint, so match on depositId if it is absent or you never received that event. |
custody.deposit.final | final beta | A custodial deposit reaches a participant's free balance, the part the participant can spend, either directly or when screening and chain finality release a held deposit. A deposit held for screening or finality first sends custody.deposit.held. | Credit the participant's free balance for depositId. If custody.deposit.held reported the same depositId, move that amount from held to free. A later custody.deposit.retracted event for the same deposit has the same depositId. |
custody.deposit.held | provisional beta | A custodial deposit reaches a participant's held balance while screening or chain finality is pending, so the participant cannot spend it yet. | Record the amount as held for depositId, not as spendable. custody.deposit.final reports the same depositId when the deposit clears, or custody.deposit-held.retracted when a reorg undoes it first. |
custody.deposit.retracted | retracted beta | After a reorg, the chain no longer shows a deposit at the block where the platform credited it. The platform takes the value back from the participant's free balance and sends this event. | Reverse the credit you booked for the same depositId. supersedes is optional and names custody.deposit.final when the platform queued it for your endpoint, so match on depositId if it is absent or you never received that event. |
custody.fee.final | final beta | A withdrawal completes and its hold, the reservation the platform placed on the funds, has a fee. The platform sends this event with custody.withdrawal.final for the same hold. | Match the fee to its withdrawal by holdId. feeId is the holdId followed by :withdrawal-fee, and assetKey can differ from the withdrawn asset. |
custody.signer-changed.final | final | The signing rules of a System smart account change: a signer is added or removed, a signer's weight or the signing threshold changes, or the owner is replaced. The platform sends one event for each change, once its block reaches chain finality. | Branch on change: weight is set only for signer-weight-changed, threshold only for threshold-changed and previousSignerHash only for owner-changed. A signer appears only as signerHash, the keccak-256 hash of the signer bytes. |
custody.withdrawal.final | final beta | A participant's withdrawal completes: the platform consumes the hold and the withdrawn amount leaves custody. It sends one event for each hold it consumes, and a hold released back to the participant sends nothing. | Close the withdrawal identified by withdrawalId. When the hold has a fee, custody.fee.final arrives for the same holdId. |
Funding
A funding requirement records that an address needs more of the chain's native currency to pay gas, the fee for a transaction. The platform opens one when a write, a transaction it sends to the chain, pauses for lack of gas, and closes it when the address is funded or the wait ends. Match the events of one requirement by requirementId, and read requiredWei as an amount in wei, the smallest unit of the native currency.
| Event | State | Sent when | What to do |
|---|---|---|---|
funding.requirement.expired | final | A funding requirement ends unfunded: its deadline passes before the address holds the required amount, or the last write waiting on it is cancelled. | Treat the writes that waited on the requirement as not executed. Fund the address and submit them again. |
funding.requirement.raised | final | A write pauses because an address that must pay gas cannot cover the cost. The platform opens one requirement for that address on that chain and sends this event once, even when more writes pause on the same requirement. | Fund subjectAddress with at least requiredWei by expiresAt. Keep the requirement open in your records until funding.requirement.resolved or funding.requirement.expired arrives. |
funding.requirement.resolved | final | The platform sees that the address holds at least the required amount and resumes the writes that waited on the requirement. | Close the requirement that you opened for the earlier funding.requirement.raised event. The waiting writes continue without further action. |
Identity
Each System, an organization's on-chain DALP deployment, has an identity registry that links account addresses to identity contracts, which hold the claims about each account. These events report changes to registry entries and to claims on registered identities. The platform sends a final identity event after chain finality and never retracts it.
| Event | State | Sent when | What to do |
|---|---|---|---|
identity.claim-issued.final | final | A claim is added to a registered identity, or changed. The platform sends one event for each System whose identity registry holds the identity. | change is added for a new claim and changed for an update to one. Use claimId to identify the claim; the event has no claim data. |
identity.claim-revoked.final | final | The identity removes a claim, or its issuer revokes it. The platform sends one event for each System whose identity registry holds the identity. | change is removed when the identity removed the claim and revoked when the issuer revoked it. Use claimId to find the claim in your records. |
identity.registration.provisional | provisional | The platform reads an account address being registered in a System's identity registry, as active or pending, in a block that has not reached chain finality. It sends nothing when a pending registration is accepted later. | Record the registration as unconfirmed, and read status to tell an active registration from a pending one. identity.status.final confirms it after chain finality. |
identity.registration.retracted | retracted | A reorg removes the block of a registration after the platform recorded a successful delivery of identity.registration.provisional to your endpoint. | Remove the registration you recorded for the event named in supersedes. |
identity.status.final | final | A registration in a System's identity registry is added, accepted after it was pending, moved to a replacement identity contract, removed, or recovered to a new wallet after the account's wallet is lost. | change is registered, accepted, identity-replaced, removed or recovered, and status is the resulting pending, active or removed. After a recovery, accountAddress is the new wallet and previousAccountAddress is the lost one. |
Primary market
Primary market events report the life of a token sale, and the platform sends each one after the block that holds its chain log reaches chain finality. Every event names the sale in saleAddress. An amount is an integer in base units, the smallest unit of its token or currency, so apply the asset's decimals before you show it.
| Event | State | Sent when | What to do |
|---|---|---|---|
primary-market.delivery.final | final | An investor withdraws purchased tokens from a token sale. The sale holds tokens back for a soft cap, the minimum it must sell, or for a vesting schedule, which releases tokens over time. | Mark the investor's tokens as delivered by the amount in the event. If the investor lost a wallet and recovered the identity, the tokens go to the replacement wallet, so match on the investor in the event. |
primary-market.proceeds-withdrawn.final | final | A funds manager withdraws a token sale's proceeds in one payment currency to a recipient. A withdrawal of zero sends no event. | Record the amount against the currency and the recipient in the event. A sale that accepts several currencies sends one event for each currency withdrawn. |
primary-market.refund.final | final | A token sale pays an investor back in one payment currency. This happens when the sale fails its soft cap and the investor claims a refund, or when the sale pays back a purchase whose tokens cannot be delivered. | Read reason: sale-failed refunds a contribution to a failed sale, and undeliverable-purchase refunds the payment for tokens that could not be delivered. Reduce the investor's recorded contribution in that currency by the amount in the event. |
primary-market.sale-activated.final | final | A sale administrator opens a token sale for subscriptions, in its presale round if one is configured and in its public round otherwise. Resuming a paused sale sends no event. | Open subscriptions in your own systems. phase says which round the sale started in: presale, which admits whitelisted investors only, or public-sale. |
primary-market.sale-closed.final | final | A sale administrator ends a token sale, before or after its end time or before it opened, so it takes no more subscriptions. A sale that reaches its end time without being ended sends no closed event. | Stop offering subscriptions in your systems. Expect the outcome in primary-market.sale-finalized.final, and do not require an earlier primary-market.sale-activated.final. |
primary-market.sale-extended.final | final | A sale administrator moves the end time of an active or paused token sale to a later time. | Replace the end time you stored for the sale with saleEndTime from the event. |
primary-market.sale-finalized.final | final | A token sale that is closed or past its end time is finalized. outcome is succeeded when the sale met its soft cap or has none, and failed otherwise. | After succeeded, investors can withdraw held tokens and the sale's proceeds can be withdrawn. After failed, investors can claim refunds. |
primary-market.subscription.final | final | An investor pays into a token sale with one payment currency to purchase tokens. | Record the purchase with the token and payment amounts in the event. Tokens arrive later with primary-market.delivery.final only when the sale holds them for a soft cap or vesting, because a sale with neither delivers at purchase. |
Reporting
Reporting events confirm a token movement for one wallet. The platform sends each event only to endpoints of an organization with a member who holds the wallet or signs for it, once the block reaches chain finality.
| Event | State | Sent when | What to do |
|---|---|---|---|
reporting.confirmation-created.final | final | A mint, burn or transfer moves tokens in a wallet. The platform confirms each wallet affected: a transfer between two wallets confirms both, and a transfer to the same wallet confirms it once. | Fetch the confirmation by confirmationId from the reporting confirmations endpoint of the Platform API, which returns not found for a wallet that is not the caller's. |
Token
The platform reads transfer and fee events from chain logs, and records corporate action and document events itself, with no chain log behind them. A corporate action is a planned change to a token and its holders' positions, such as a dividend, a coupon or a stock split. A mint or burn also produces the transfer events, with the all-zero address as sender or recipient.
| Event | State | Sent when | What to do |
|---|---|---|---|
token.corporate-action.announced | final beta | A corporate action is cleared for execution: an approver signs it off, or the action needs no approval. | Read the action's record through the corporate actions endpoint of the Platform API. The event names the action, the token and the action type only. |
token.corporate-action.completed | final beta | A corporate action finishes executing and reaches the completed state. | Read the final record through the corporate actions endpoint of the Platform API. A completed action cannot be aborted, so no retraction follows. |
token.corporate-action.paid | final beta | A cash dividend, a distribution or a coordinated distribution that pays in cash reaches the completed state. The platform sends it with token.corporate-action.completed. | Use it to separate cash payouts from other completed actions. Other action types, and payouts made in kind rather than in cash, send only token.corporate-action.completed. |
token.corporate-action.retracted | final beta | A corporate action that was approved, or needs no approval, is aborted before it completes. An action that was denied, expired or still awaiting approval sends nothing. | Match on corporateActionId to cancel what you expected from token.corporate-action.announced. This event has no supersedes and can arrive without an earlier announcement. |
token.document.published | final beta | A document upload is confirmed with holders visibility, and each replacement version sends its own event. Other visibility levels send nothing. | Fetch the file through the documents endpoints of the Platform API, which apply the caller's visibility. The event names the document, its type, its title and its publish time only. |
token.fee-period-close.final | final beta | A token's fee accounting feature closes a fee period for a recipient. A close with a zero amount sends nothing. | Use it to end an accrual period: token.fee.final events with basis accrued since the previous close belong to this period. |
token.fee.final | final beta | A token charges a fee: a fee feature collects or accrues it, or a fund collects its management fee. A fee of zero sends nothing. | A management fee or an assets-under-management fee mints the fee to the recipient, so asset.issuance.final and token.transfer.final also report it. Post the fee once, and read basis for collected or accrued. |
token.transfer.final | final | The platform indexes a transfer, mint or burn of a token. | Treat the movement as confirmed: a reorg never retracts version 2, and a reorg that removes the block before finality cancels the event unsent. The platform no longer sends version 1, which went out when the block was included. |
token.transfer.provisional | provisional | The platform indexes a block that includes a transfer, mint or burn of a token, before the block reaches chain finality. | token.transfer.final confirms the movement. If a reorg removes the block, version 2 of token.transfer.retracted replaces this event. |
token.transfer.retracted | retracted | A reorg removes the block of a transfer, mint or burn after the platform recorded a successful delivery of the event it supersedes to your endpoint. | Reverse the record for the event named in supersedes, and branch on the envelope version. Version 2 replaces a token.transfer.provisional event, and version 1 replaces a version 1 token.transfer.final event that the platform no longer sends. |
Trading venue
A trading venue matches orders off chain, settles each trade on chain, and delivers the assets when the market's holding period, the delay between settlement and delivery, ends. A bust is an approved reversal of a trade. A provisional event reports matched activity that has not settled, and the chain events trading-venue.trade.final and trading-venue.trade.retracted have the state final because the platform sends them after chain finality.
| Event | State | Sent when | What to do |
|---|---|---|---|
trading-venue.announcement.published | final beta | A venue operator publishes an announcement, for the whole venue or for one market. | Use the title, category and severity in the event to alert your users. The event has no body: read it from the announcements endpoint of the Platform API, which applies the caller's audience. |
trading-venue.announcement.withdrawn | final beta | A venue operator withdraws a published announcement. Withdrawing an announcement that is not published sends no event. | Stop showing the announcement. The announcements endpoint of the Platform API no longer returns it to callers other than operators. |
trading-venue.order-status.provisional | provisional beta | The venue matching engine changes an order: the order is placed or replaced, filled, or changes status in another way. The platform sends one event for each order the change touches. | Update your copy of the order and keep the event with the highest sequence for each order. A filled status is not a settled trade: wait for trading-venue.trade-settled.final. |
trading-venue.price-alert.triggered | provisional beta | The price of a matched trade crosses a user's price alert on a market. An alert set above fires at or over its threshold, an alert set below fires at or under it, and each alert fires once. | Notify the user who set the alert. The price comes from a matched trade that has not settled, so match tradeId against trading-venue.trade-settled.final before you treat the price as settled. |
trading-venue.trade-fee.final | final beta | The venue charges one side of a settled trade a fee, and the platform records it with the settlement. The platform sends one event for each charged side, together with trading-venue.trade-settled.final. | Book the fee against the payer in the event, in the base units of the market's quote token, the token that prices its trades. orderRecipientAddress is the order's asset destination, not the account that receives the fee. |
trading-venue.trade-fee.retracted | retracted beta | A bust reverses a settled trade that charged fees. The platform sends one event for each fee the trade charged, together with trading-venue.trade-settled.retracted. | Reverse the fee you booked from trading-venue.trade-fee.final. supersedes is optional and names that event when the platform queued it for your endpoint, so match the fee by feeId if it is absent or you never received that event. |
trading-venue.trade-settled.final | final beta | A matched trade settles on chain and the platform records it. The platform sends one event for each trade after the settlement transaction is confirmed and its logs show the fill. | Book the trade as settled. delivery is delivered when the assets already moved and pending-delivery while the market's holding period still applies. |
trading-venue.trade-settled.retracted | retracted beta | A bust reverses a settled trade, and the reversal is complete on chain. The platform sends nothing while a reversal transfer is queued, has reverted, or has not completed. | Reverse the settlement you booked from trading-venue.trade-settled.final. supersedes is optional and names that event when the platform queued it for your endpoint, so match the trade by tradeId if it is absent or you never received that event. |
trading-venue.trade.final | final beta | The venue contract delivers a trade on chain: its holding period ends and the assets move. | Treat the trade as delivered. A market with no holding period delivers inside the settlement transaction and sends no trading-venue.trade.final, so read delivery on trading-venue.trade-settled.final for those markets. |
trading-venue.trade.retracted | final beta | The venue contract undoes a trade because of a bust while the delivery of the trade is still pending. An undo for any other reason sends nothing. | Mark the trade as undone. Its delivery was still pending, so the platform never sent trading-venue.trade.final for it, and the event has no supersedes: match the trade by venueTradeId. |
Transaction request
A transaction request is one on-chain write that the platform accepts and tracks. These events report the request's progress, not the finality of a token movement. Each event reaches the organization and chain of the request. Match events by transactionId; use the asset and token events to record movements.
| Event | State | Sent when | What to do |
|---|---|---|---|
transaction.request.broadcast | pending | The request enters a broadcast state with a transaction hash. | Store the hash and mark the request as awaiting an outcome. Do not book a token movement from this event. |
transaction.request.cancelled | final | The request reaches CANCELLED. | Mark the request as cancelled. Read the transaction request record if you need the reason. |
transaction.request.confirmed | final | The request reaches COMPLETED. | Mark the request as complete. Match the token or asset events before recording the resulting movement. |
transaction.request.dead-lettered | final | The request reaches DEAD_LETTER. | Flag the request for operator review. A request with no retries left normally reaches FAILED, so do not rely on this event for every exhausted retry. |
transaction.request.failed | final | The request reaches FAILED. | Mark the request as failed and read the transaction request record for details. An operator can retry it, so another outcome can follow. |
The platform records the event together with the state change. Setting a request to the state it already holds sends nothing. Leaving the broadcast states and entering them again with a hash sends another broadcast event; replacing a hash while confirming sends nothing. A request that fails, is retried by an operator, and fails again sends two failed events with different source_id values.
A thin delivery omits fromAddress, errorMessage, and revertReason. The platform limits the two error fields to 1,024 characters. Read the full record with GET /api/v2/transaction-requests/{transactionId}.
The default subscriptions skip all five events. Use transaction.request.*, transaction.*, exact names, or *, as the subscriptions reference describes.
XvP settlement
XvP stands for exchange-versus-payment: an XvP settlement is a contract that exchanges assets between parties in transfers called legs, after each sending participant approves it and locks its assets in the contract, called escrow. A settlement with a leg on another chain also has a hashlock, a hash that blocks execution until its secret is revealed. Every event includes settlementAddress and reaches only endpoints on the System, an organization's on-chain DALP deployment, that owns the settlement's factory, once the block reaches chain finality.
| Event | State | Sent when | What to do |
|---|---|---|---|
xvp.approval-revoked.final | final | A settlement participant withdraws its approval while the settlement is open. The contract returns any escrow that participant locked in the same transaction, so refund events can come from it. | Store the new approvedCount and requiredCount, and mark accountAddress as not approved. Take the escrow change from xvp.assets-refunded.final or xvp.refund-deferred.final, because this event has no amount. |
xvp.assets-locked.final | final | A settlement participant locks an asset in the settlement's escrow while approving it. The platform sends one event for each asset that the approval adds escrow for. | Add amount to the escrow you track for accountAddress and assetAddress. amount is the extra escrow this approval adds to what the participant already locked. |
xvp.assets-refunded.final | final | Escrow that a participant locked leaves the settlement for that participant. This follows a revoked approval, a cancellation, a withdrawal after the settlement expires, or a claimRefund call. | Subtract amount from the escrow you track for accountAddress and assetAddress. After a claimRefund call the participant can send the tokens to another address, and the event does not identify that address. |
xvp.delivery-claimed.final | final | A recipient calls claimSettled to pull a delivery that xvp.delivery-deferred.final parked in the settlement. The asset leaves the settlement at this point. | Mark the parked delivery for accountAddress and assetAddress as delivered. The recipient can choose another receiving address, and the event does not identify it. |
xvp.delivery-deferred.final | final | A settlement executes but the transfer to a recipient fails, for example because the token blocks that recipient, so the contract parks the amount in the settlement. Only a settlement with a leg on another chain parks a delivery this way, and only after its secret is revealed. | Do not book the asset as delivered to accountAddress. It stays in the settlement until the recipient calls claimSettled, which produces xvp.delivery-claimed.final. |
xvp.refund-deferred.final | final | The contract cannot transfer a participant's escrow back, for example because the token blocks that participant, so it parks the amount in the settlement. The revoked approval, cancellation or withdrawal after expiry that triggered the refund still completes. | Keep the amount in escrow for accountAddress and assetAddress. It leaves only when the participant calls claimRefund, which produces xvp.assets-refunded.final. |
xvp.settlement-approved.final | final | A settlement participant approves the settlement. The event includes the approval count after the change. | Compare approvedCount with requiredCount: when they are equal, every approval is in. A settlement with autoExecute set then executes in the same transaction, unless it has a leg on another chain whose secret is not yet revealed. |
xvp.settlement-cancelled.final | final | A settlement is cancelled before it executes. A fully approved settlement with a leg on another chain cancels only after every participant that sends an asset on this chain votes to cancel, and the votes alone send no event. | Mark the settlement as cancelled. cancellerAddress identifies the caller that completed the cancellation, and xvp.assets-refunded.final or xvp.refund-deferred.final events from the same transaction return the escrow. |
xvp.settlement-created.final | final | A settlement factory creates a settlement and fixes its legs and its cutoff, the time after which the settlement expires. The event includes the hashlock and never the secret that opens it. | Store the settlement by settlementAddress and its legs by legIndex. xvp.settlement-executed.final uses the same leg indexes. |
xvp.settlement-executed.final | final | A settlement executes: the contract uses the paying parties' escrow and transfers the assets to the receiving parties. This happens when a caller runs execute, or with the last approval when autoExecute is set. | Mark the settlement as executed and match flows to your stored legs by legIndex. A recipient the contract could not pay appears in xvp.delivery-deferred.final from the same transaction, and stays parked until xvp.delivery-claimed.final. |
xvp.settlement-expired.final | final | A caller withdraws the escrow of a settlement that passed its cutoff without executing. Reaching the cutoff alone sends nothing. | Mark the settlement as expired. callerAddress identifies the account that withdrew the escrow, and xvp.assets-refunded.final or xvp.refund-deferred.final events from the same transaction return it. |
Reserved names
These event names are registered, but no action in the platform sends them today.
| Event | Status |
|---|---|
compliance.freeze.recalled | Reserved. No action sends this event today. |
settlement.transfer.retracted | Reserved. No action sends this event today. |
token.transfer.pending | Reserved. No action sends this event today. |