Request a collateral decrease
Permissions required: Manage Collateral Packages and Read vault activity
Initiate 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 collateral decrease 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 collateral decrease. 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 collateral decrease are:
- The initiator (pledgor or secured party) requests the decrease 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.
- The initiator authorizes the settlement, either through the API or mobile app signing.
- [Optional] The counterparty authorizes the settlement, either through the API or mobile app signing.
- The settlement is funded from the secured party’s collateral wallets.
- 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.
idempotencyKey into the body. Replace PACKAGE_ID in the path before signing.
Authorizations
An API key associated with a security role
Headers
A hex-encoded Ed25519 signature of timestamp_epoch_seconds + uppercase(http_method) + request_path + request_body.
Construction example:
toHex(
ed25519Sign(
signing_key,
'{}{}{}{}'.format(timestamp_epoch_seconds, toUpper(httpMethod), httpRequestPath, httpBody)
)
)^[0-9A-Fa-f]{128,160}$Current timestamp, represented as unix epoch seconds
Path Parameters
The unique identifier of the collateral package to request a collateral decrease on.
Body
The details for requesting a collateral decrease
The request payload for requesting a collateral decrease on a collateral package.
Asset types and amounts to return to the pledgor. Wallet IDs are determined from the package's asset configuration.
1Idempotency key for ensuring operation uniqueness.
128Whether to use gas station for fee payment. Defaults to false.
Response
Successfully requested collateral decrease
Response from requesting a collateral decrease.
Settlement network ID for the created two-way settlement. Used to track the settlement through its lifecycle.