Withdraw Remaining Funds

This function is used to withdraw any residual funds remaining in the escrow contract after all milestones have been released or a dispute has been resolved.

In a single-release escrow, the main dispute flow operates at the escrow level via the resolve-dispute endpoint. However, small residual balances can remain in the contract after resolution — for example, due to rounding in fee calculations or a partial distribution that did not consume the full escrow balance. This endpoint allows the dispute resolver to sweep and redistribute those remaining funds.

Headers

Name	Value
Content-Type	application/json
x-api-key	<token>

Open API

Distribute the residual escrow balance after a release or resolution

post

Sweeps any leftover balance once the escrow is fully processed. Same DistributionV2Dto shape as /resolve-dispute.

Authorizations

x-api-key

x-api-keystringRequired

Body

application/json

contractIdstringRequired

Deployed v2 escrow contract (C...).

Example: CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB

disputeResolverstringRequired

Dispute resolver wallet — signs the transaction.

Example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

Responses

200

Unsigned XDR built successfully.

application/json

unsignedXdrstringRequired

Base64-encoded unsigned XDR. Sign it with the appropriate wallet and submit to Soroban / Horizon to execute the operation on-chain.

Example: AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=

txHashstringRequired

SHA-256 hash of the prepared transaction. NOTE: it only matches the executed transaction if you sign the XDR exactly as returned — re-preparing (re-simulating) it changes the hash. Prefer contractId for correlation when present.

Example: b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a

contractIdobject · nullableOptional

Deploys only: the address (C…) the new escrow contract WILL have once this transaction executes — known upfront because the service generates the deploy salt. Track your escrow with it (e.g. GET /escrows/:contractId) as soon as the transaction lands; it is stable even if your wallet/SDK re-prepares the transaction.

Example: CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526

400

Request body or query params fail schema validation (wrong type, missing required field, unknown property).

application/json

401

Missing, malformed, expired, revoked or invalid API key.

application/json

403

API key is valid but does not have the role required for this operation.

application/json

422

Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).

application/json

500

Unexpected server-side failure. Use the traceId to look up the incident in server logs or contact support.

application/json

post/escrow/single-release/v2/withdraw-remaining-funds

HTTPcURLJavaScriptPython

POST /escrow/single-release/v2/withdraw-remaining-funds HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 252

{
  "contractId": "CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB",
  "disputeResolver": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "distributions": [
    {
      "address": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "amount": 500
    }
  ]
}

{
  "unsignedXdr": "AAAAAgAAAAAtWsgedQ...AAAAAQAAAAA=",
  "txHash": "b1946ac92492d2347c6235b4d2611184a8d53f7a8e6e9b4f0c79a2b30e5c4f3a",
  "contractId": "CAAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQCAIBAEAQC526"
}

What this Endpoint returns?

This endpoint returns the transaction unsigned so that the transaction can be signed by means of a customer wallet.

Use Example:

import axios from "axios";

const http = axios.create({
  baseURL: "https://dev.api.trustlesswork.com",
  timeout: 10000,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": your_api_key,
  },
});

export const useExample = async () => {
    // Get the signer address
    const { address } = await kit.getAddress();

    const response = await http.post(
      "/escrow/single-release/v2/withdraw-remaining-funds",
      {
        // body requested for the endpoint
      },
    ); 
    
    // Get the unsigned transaction hash
    const { unsignedTransaction } = response.data;

    // Sign the transaction by wallet
    const { signedTxXdr } = await signTransaction(unsignedTransaction, {
      address,
      networkPassphrase: WalletNetwork.TESTNET,
    });

    // Send the transaction to Stellar Network
    const tx = await http.post("/stellar/submit-transaction", {
      signedXdr: signedTxXdr,
    });

    const { data } = tx;

    return data;
}