Deploy

Deploy the multi-release escrow contract and define its milestone payouts.

Builds the unsigned transaction that deploys a new multi-release v2 escrow through the Trustless Work factory. Each milestone carries its own amount and settles independently. You sign with the signer wallet and submit via Send Transaction — the API never holds keys.

The request and response reference below is generated from the live API spec and always matches what the server actually accepts. If anything on this page ever disagrees with it, the reference wins.

Authentication

Send your API key on every call: x-api-key: <id>.<secret> (or a wallet-session Authorization: Bearer <jwt>). Body is JSON (Content-Type: application/json).

Endpoint

Build the unsigned transaction to deploy a new multi-release v2 escrow

post

Returns the XDR that you sign with the signer wallet. Differs from multi-release v1 in that roles are pluralised arrays + admin + observers, each milestone carries its own amount/dispute/released, and the factory first arg is signer (V1 used deployer).

Authorizations

x-api-keystringRequired

Body

signerstringRequired

Wallet that will sign the deploy transaction.

Example: GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

engagementIdstringRequired

Stable identifier the platform uses to correlate the escrow.

Example: ENG-67890

titlestringRequired

Short human-readable title for the escrow.

Example: Multi-phase product launch — Q3 2026

descriptionstringRequired

Long-form description.

Example: Multi-release v2 escrow with three independently releasable milestones.

platformFeenumberRequired

Platform fee in percent (1 = 1%). Scaled to basis points on-chain.

Example: 1

receiverMemonumberOptional

Optional receiver memo (u32 on-chain).

Example: 0

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/multi-release/v2/deploy

POST /escrow/multi-release/v2/deploy HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1096

{
  "signer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "engagementId": "ENG-67890",
  "title": "Multi-phase product launch — Q3 2026",
  "description": "Multi-release v2 escrow with three independently releasable milestones.",
  "roles": {
    "approvers": [
      "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    ],
    "serviceProviders": [
      "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    ],
    "platform": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
    "releaseSigners": [
      "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    ],
    "disputeResolvers": [
      "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    ],
    "admin": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
    "observers": []
  },
  "platformFee": 1,
  "milestones": [
    {
      "description": "Phase 1 — UI design delivery",
      "amount": 250,
      "receiver": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "status": "pending",
      "approvalsTarget": 1
    }
  ],
  "trustline": {
    "contractId": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    "symbol": "USDC",
    "address": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
  },
  "receiverMemo": 0
}

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

Field notes

Cross-field rules the schema alone cannot express:

• Every milestone has its own amount (> 0, human token units). The escrow total is the sum of milestone amounts.

• roles.admin must be distinct from every other role. It later signs update-escrow, manage-milestones and extend-ttl.

• Each milestone's approvalsTarget must be ≤ the number of roles.approvers.

• trustline accepts either the token's contractId (C…) or the classic symbol + address pair.

• platformFee is a percent (1 = 1%).

What this endpoint returns

• unsignedXdr — sign it exactly as returned; re-preparing it changes the transaction hash.

• txHash — hash of the prepared transaction.

• contractId — the address (C…) the escrow will have once the transaction lands. Known upfront and stable — use it to track the escrow: GET /escrows/{contractId}.

Usage example

Same build → sign → submit flow as single-release — see the worked example on the Single Release Deploy page and swap the path for /escrow/multi-release/v2/deploy.

Next steps

• Lock the funds: Fund Escrow

• Read it back: GET /escrows/{contractId}