Permissions required: Manage Collateral Packages and Read vault activity

Initiate a margin return: a decrease in the collateral held against a collateral package by returning a list of assets from the secured party's collateral wallets to the pledgor's return wallets. The package must be in MARGIN_RETURN state.

A margin return is fulfilled by creating a two-way Atlas settlement. Unlike a freeform settlement proposal, the counterparty, vault, and the wallets on both sides are not supplied by the caller — they are resolved from the collateral package's asset tracking configuration. The caller only specifies which assets and amounts to return.

{
	"assetAmounts": [
		{ "assetTypeID": "BTC", "value": "1.1" },
		{ "assetTypeID": "ETH", "value": "20.62" }
	],
	"idempotencyKey": "my-unique-request-id-001",
	"useGasStation": false
}

For example, the above request returns 1.1 BTC and 20.62 ETH from the secured party's collateral wallets for this package to the pledgor's configured return wallets.

Either the pledgor or the secured party may initiate the margin return. When the pledgor calls this endpoint, the pledgor becomes the proposer of the underlying settlement and the associated collateral org becomes the acceptor. When the secured party calls this endpoint, the associated collateral org becomes the proposer of the underlying settlement and the pledgor becomes the acceptor. The direction of funds is always the same: assets move from the secured party's collateral wallets to the pledgor's return wallets, regardless of who initiated.

The steps to complete a margin return are:

1. The initiator (pledgor or secured party) requests the margin return via this endpoint, specifying assets and amounts. If the pledgor initiates, the pledgor is the settlement proposer and the collateral org is the acceptor. If the secured party initiates, the collateral org is the settlement proposer and the pledgor is the acceptor. Both sides' wallets are resolved automatically from the package configuration.
2. The initiator authorizes the settlement, either through the API or mobile app signing.
3. [Optional] The counterparty authorizes the settlement, either through the API or mobile app signing.
4. The settlement is funded from the secured party's collateral wallets.
5. The assets are transferred on-chain to the pledgor's return wallets.

Steps 2 and 3 can happen out of order.
Step 3 only happens if the pledgor initiates
The settlement stays in the ActionNeeded state until it reaches step 4. Then it enters the Executing state and, after that, it enters one of the final states.