Update Escrow

Replace the on-chain escrow properties, signed by the escrow admin.

Builds the unsigned transaction that replaces the escrow's on-chain properties. In v2 this is signed by the escrow admin (roles.admin) — not the platform.

The reference below is generated from the live API spec — if anything on this page disagrees with it, the reference wins.

Endpoint

Replace the on-chain v2 escrow properties

put

Full replacement of the escrow record (roles, milestones, amount, platform fee, observers). The escrow admin signs.

Authorizations

x-api-keystringRequired

Body

contractIdstringRequired

Deployed v2 escrow contract (C...).

Example: CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB

adminstringRequired

Admin wallet authorising the update — must equal roles.admin of the on-chain escrow. 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

put/escrow/single-release/v2/update

PUT /escrow/single-release/v2/update HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1165

{
  "contractId": "CDHAZ2RTE2MDHYQQ7NATF5IVKIFVGLX6FHJ66OPK6MUXBSTRRXFXJ6QB",
  "admin": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "escrow": {
    "engagementId": "ENG-12345",
    "title": "Website redesign — Q2 2026",
    "description": "Single-release v2 escrow covering UI design and front-end delivery.",
    "amount": 1000,
    "platformFee": 1,
    "receiverMemo": 0,
    "roles": {
      "approvers": [
        "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
      ],
      "serviceProviders": [
        "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
      ],
      "platform": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "releaseSigners": [
        "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
      ],
      "disputeResolvers": [
        "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
      ],
      "receiver": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "admin": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "observers": []
    },
    "milestones": [
      {
        "description": "Phase 1 — UI design delivery",
        "status": "pending",
        "approvalsTarget": 1
      }
    ],
    "trustline": {
      "contractId": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
      "symbol": "USDC",
      "address": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    }
  }
}

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

Field notes

• This is a replace, not a patch: send the full set of properties you want the escrow to have afterwards.

• The contract enforces its own preconditions (e.g. state that can no longer be edited). A rejected update surfaces as a 422 with the on-chain error in code — nothing is charged beyond the failed simulation.

• Milestone edits have a dedicated, cheaper path: Manage Milestones.

What this endpoint returns

unsignedXdr + txHash — sign the XDR exactly as returned and submit it via Send Transaction. Full flow example on the Deploy page.