> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/deploy/initialize-escrow.md). # Deploy ### Headers
NameValue
Content-Typeapplication/json
x-api-key<token>
### Milestone | Name | Type | Description | | --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | description | string | Text describing the function of the milestone | | status | string (Default value: "pending") | Milestone status. Ex: Approved, In dispute, etc... | | approved | boolean (Default value: false) | Flag indicating whether a milestone has been approved by the approver | | evidence | string (optional) | Evidence reference (URL, IPFS hash, etc.) attached to the milestone | | approvalsTarget | number (optional, default: 1) | Number of distinct approvers required to consider the milestone approved. Must be ≥ 1 and ≤ the length of roles.approvers | ### Roles: | Name | Type | Description | | ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | approvers | string\[] (1–5, no duplicates) | Addresses of the wallets allowed to approve milestones | | serviceProviders | string\[] (1–5, no duplicates) | Addresses of the wallets that perform the work and change milestone status | | plataformAddress | string | The address that receives the fee set for the platform | | releaseSigners | string\[] (1–5, no duplicates) | Addresses of the wallets authorised to release funds once milestones are met | | disputeResolvers | string\[] (1–5, no duplicates) | Addresses of the wallets that resolve disputes. Cannot overlap with any other role | | receiver | string | Address where escrow proceeds will be sent to | | admin | string | Wallet that authorises update, manage-milestones, and extend-ttl operations. Must be distinct from every other role | | observers | string\[] | Read-only wallets attached to the escrow. No on-chain authority. Defaults to \[] | ### Trustline: | Name | Type | Description | | ------- | ------ | -------------------------------------------------------------------------------------- | | address | string | Public address establishing permission to accept and use a specific token. | | symbol | string | Official abbreviation representing the token in wallets, exchanges, and documentation. | ### Initialize Escrow ## Build the unsigned transaction to deploy a new v2 escrow > Returns the XDR that you sign with the \`signer\` wallet. v2 differs from v1 only in that \`roles\` accepts an optional \`observers\` list. ```json {"openapi":"3.0.0","info":{"title":"👋🏼 Trustless Work Core API — All Endpoints (Unified)","version":"1.0"},"security":[{}],"paths":{"/escrow/single-release/v2/deploy":{"post":{"description":"Returns the XDR that you sign with the `signer` wallet. v2 differs from v1 only in that `roles` accepts an optional `observers` list.","operationId":"DeployEscrowV2Controller_deploy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployEscrowV2Dto"}}}},"responses":{"200":{"description":"Unsigned XDR built successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsignedTransactionResponse"}}}},"400":{"description":"Request body or query params fail schema validation (wrong type, missing required field, unknown property).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"401":{"description":"Missing, malformed, expired, revoked or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"403":{"description":"API key is valid but does not have the role required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"422":{"description":"Payload is well-formed but a business rule rejects it (e.g. amount out of range, role not allowed for this user).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}},"500":{"description":"Unexpected server-side failure. Use the `traceId` to look up the incident in server logs or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetailsResponseDto"}}}}},"summary":"Build the unsigned transaction to deploy a new v2 escrow","tags":["Single Release Escrow V2"]}}},"components":{"schemas":{"DeployEscrowV2Dto":{"type":"object","properties":{"signer":{"type":"string","description":"Wallet that will sign the deploy transaction."},"engagementId":{"type":"string","description":"Stable identifier the platform uses to correlate the escrow."},"title":{"type":"string","description":"Short human-readable title for the escrow."},"description":{"type":"string","description":"Long-form description."},"roles":{"$ref":"#/components/schemas/RolesV2Dto"},"amount":{"type":"number","description":"Total escrow amount in human-readable decimals."},"platformFee":{"type":"number","description":"Platform fee in percent (1 = 1%). Scaled to basis points on-chain."},"milestones":{"description":"Milestones to register at deploy time. Optional — the contract accepts deploys with an empty (or absent) milestones array since contract commit `b8738b9`. Use `POST /escrow/single-release/v2/manage-milestones` afterwards to add them. Max 50 entries when present.","type":"array","items":{"$ref":"#/components/schemas/MilestoneV2Dto"}},"trustline":{"$ref":"#/components/schemas/TrustlineV2Dto"},"receiverMemo":{"type":"number","description":"Optional receiver memo (u32 on-chain)."}},"required":["signer","engagementId","title","description","roles","amount","platformFee","trustline"]},"RolesV2Dto":{"type":"object","properties":{"approvers":{"description":"Wallets allowed to approve milestones. Up to 5, no duplicates.","type":"array","items":{"type":"string"}},"serviceProviders":{"description":"Wallets that perform the work and change milestone status. Up to 5.","type":"array","items":{"type":"string"}},"platform":{"type":"string","description":"Trustless Work platform wallet. Receives the platform fee."},"releaseSigners":{"description":"Wallets authorised to release the funds once milestones are met. Up to 5, no duplicates.","type":"array","items":{"type":"string"}},"disputeResolvers":{"description":"Wallets that resolve disputes when they are raised. Up to 5, no duplicates. Cannot overlap with any other role.","type":"array","items":{"type":"string"}},"receiver":{"type":"string","description":"Final beneficiary of the released funds."},"admin":{"type":"string","description":"Admin wallet — authorises update_escrow, manage_milestones and extend_contract_ttl. MUST be distinct from every other role."},"observers":{"description":"Read-only observer wallets attached to the escrow. They have no on-chain authority. Defaults to an empty list when absent.","type":"array","items":{"type":"string"}}},"required":["approvers","serviceProviders","platform","releaseSigners","disputeResolvers","receiver","admin"]},"MilestoneV2Dto":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable milestone description."},"status":{"type":"string","description":"Initial status. Convention: pending → in_progress → completed. Defaults to \"pending\"."},"approvalsTarget":{"type":"number","description":"Number of distinct approvers required for the milestone. Must be > 0 and ≤ roles.approvers.length. Defaults to 1."}},"required":["description"]},"TrustlineV2Dto":{"type":"object","properties":{"contractId":{"type":"string","description":"Soroban contract address of the asset (C...). Required if symbol+address are not provided."},"symbol":{"type":"string","description":"Asset code / symbol. Required if contractId is not provided; ignored otherwise."},"address":{"type":"string","description":"Issuer account address (G...). Required if contractId is not provided; ignored otherwise."}}},"UnsignedTransactionResponse":{"type":"object","properties":{"unsignedXdr":{"type":"string","description":"Base64-encoded unsigned XDR. Sign it with the appropriate wallet and submit to Soroban / Horizon to execute the operation on-chain."},"txHash":{"type":"string","description":"SHA-256 hash of the prepared transaction. Use as a correlation key between this build call and any follow-up (pending-write tracking, idempotency keys, audit logs)."}},"required":["unsignedXdr","txHash"]},"ProblemDetailsResponseDto":{"type":"object","properties":{"type":{"type":"string","description":"Stable URI identifying the error type. Hash-link points to the docs."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"status":{"type":"number","description":"HTTP status code, repeated here for typed clients."},"code":{"type":"string","description":"Machine-readable error code. Stable across versions; safe to switch on."},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI of the request that triggered the error."},"traceId":{"type":"string","description":"Correlation id propagated from the `X-Trace-Id` header (or generated). Use it when contacting support to reference a specific request."},"extensions":{"type":"object","description":"Optional structured context. Shape depends on the error code; documented per-endpoint when relevant.","additionalProperties":true}},"required":["type","title","status","code","detail"]}}}} ```
### **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();

    // Execute the endpoint
    const response = await http.post(
      "/escrow/single-release/v2/deploy",
      {
        // 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; 
}
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/deploy/initialize-escrow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.