Base URL: https://api.trustlesswork.com

Before you start:

A public and private address must be generated with this stellar resource:

Then stellar funds must be given to this address by placing the public key in this stellar resource:

USDC on testnet faucet Stellar testnet:

1. To be able to interact with USDC from a stellar address you have to define the trustline. For this you can use this api endpoint:

Case 1:

Normal case where a escrow is created and the escrow are completed correctly:

1. The escrow contract must be deployed, which in turn initializes the escrow with its metadata.

Among the information returned you will get the id of the contract you have just deployed, which you will need to enter to be able to use the other endpoints.

NOTE: This 50 percent that is being transferred goes directly to the balance of the deployed contract, not to the service provider. The escrow must then be funded so that the service provider can be assured of 50 percent of the escrow value.

1. To do this, the following endpoint must be executed:

1. The following endpoint must be executed in order to complete the escrow after mutual agreement:

With this step the other 50 percent of the escrow value will be transferred to the balance of the deployed contract.

1. After the escrow is completed, the service provider may claim the proceeds of the escrow through this endpoint:

Case 2:

Case in which the contract is deployed and the escrow is initialized and funded but the service provider decides to cancel the escrow:

1. The escrow contract must be deployed, which in turn initializes the escrow with its metadata.

Among the information returned you will get the id of the contract you have just deployed, which you will need to enter to be able to use the other endpoints.

NOTE: This 50 percent that is being transferred goes directly to the balance of the deployed contract, not to the service provider.

1. The escrow must then be funded so that the service provider can be assured of 50 percent of the escrow value.

1. Due to an external cause the service provider decided to cancel the escrow.

1. The escrow owner (signer) will be able to refund to his account the 50 percent that he financed for the escrow due to the above mentioned situation.

IMPORTANT NOTE: All endpoints related to escrow management return the transaction unsigned. This is done by means of a string returned in XDR (External Data Representation) format, which is a format that stellar uses to encode transactions. This string is what you should use to sign the transaction with the wallet of your choice. After being signed it will return the transaction signed in the same way by means of a string in XDR format.

1. This string is the one that must be sent to the next endpoint for the transaction to be sent to the Stellar network:

The only endpoints that do not require the previous step since they are signed and sent to the network directly when executed, are the following (mentioning them by the name they have in the documentation):

1. Invoke Deployer Contract

2. Get Escrow by Engagement ID

3. Set Trustline

Responsible for setting the escrow in dispute state. Changes the value of the escrow's "dispute_flag" property to true.

URL: /escrow/change-dispute-flag

Body params:

contractId: ID (address) that identifies the escrow contract

signer: Address of the user who will sign the transaction

Example:

Allows flexible USDC amounts to be transferred to the escrow contract.

URL: /escrow/fund-escrow

Body params:

contractId: ID (address) that identifies the escrow contract

signer: Address of the user signing the contract transaction

amount: Amount to transfer to the escrow contract

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	signer: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP", 
	amount: "500.00"
};

Previous Version:

POST escrow/fund-escrow

Headers

Body

engagementId

contractId

signer

Example of Request Body:

{
  "engagementId": "test",
  "contractId": "GD2SVFOJ...",
  "signer": "SCMXDC..."
}

Possible Responses

{
    "status": "SUCCESS",
    "unsignedTransaction": "AAAAAgAAAABfQAm/gS..."  // XDR Hash Transaction
}

{
  "error": "Only the signer can fund the escrow"
}

{
  "error": "Escrow already funded"
}

{
  "error": "This escrow is already fully funded"
}

{
  "error": "The signer does not have sufficient funds"
}

{
  "error": "Escrow not found"
}

{
  "error": "Not enough allowance to fund this escrow"
}

{
    "message": "Message",
    "error": "Bad Request",
    "statusCode": 400
}

{
    "statusCode": 429,
    "message": "ThrottlerException: Too Many Requests"
}

What this Endpoint returns?

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

Responsible for modifying the "flag" property of a specific milestone in the escrow to approve that milestone.

URL: /escrow/change-milestone-flag

Body params:

contractId: ID (address) that identifies the escrow contract

milestoneIndex: Position that identifies the milestone within the group of milestones in the escrow

newFlag: New value for the "flag" property within the escrow milestone

client: Address of the client who will approve the milestone

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	milestoneIndex: "0", 
	newFlag: true,
	client: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP"
};

Handles the resolution of disputes within an escrow by transferring the amounts entered so far in the escrow to the client and service provider according to what the dispute resolver deems appropriate.

URL: /escrow/resolving-disputes

Body params:

contractId: ID (address) that identifies the escrow contract

disputeResolver: Address of the user defined to resolve disputes in an escrow

clientFunds: Amount to transfer to the client for dispute resolution

serviceProviderFunds: Amount to transfer to the service provider for dispute resolution

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	disputeResolver: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP", 
	clientFunds: "100",
	serviceProviderFunds: "50"
};

Returns the balance of an escrow

URL: /helper/get-escrow-balance

Body params:

contractId: ID (address) that identifies the escrow contract

signer: Address of the user who will sign the transaction

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	signer: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP"
};

Responsible for modifying the "status" property of a specific milestone in the escrow

URL: /escrow/change-milestone-status

Body params:

contractId: ID (address) that identifies the escrow contract

milestoneIndex: Position that identifies the milestone within the group of milestones in the escrow

newStatus: New value for the "status" property within the escrow milestone

serviceProvider: Address of the service provider who will modify the contract's "status" property

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	milestoneIndex: "0", 
	newStatus: "Approved",
	serviceProvider: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP"
};

Initialize escrow

Deploys the escrow contract and defines its properties.

URL: /deployer/invoke-deployer-contract

Body params:

signer: Entity that signs the transaction that deploys and initializes the escrow engagementId: Unique identifier for the escrow

title: Name of the escrow

description: Text describing the function of the escrow

client: Address of the entity requiring the service

serviceProvider: Address of the entity providing the service

platformAddress: Address of the platform that owns the escrow

amount: Amount to be transferred upon completion of escrow milestones

platformFee: Commission that the platform will receive when the escrow is completed

milestones: Objectives to be completed to define the escrow as completed releaseSigner: Address of the entity in charge of releasing escrow funds

disputeResolver: Address in charge of resolving disputes within the escrow

Example:

{
	signer: "GAD4T6Z63N5NJLQYY3J5MVYFHH5I5UB7NDUUYZD7HHB3RMS6X3H4YK7P", 
	engagementId: "ENG12345",
	title: "Project Title",
	description: "This is a detailed description of the project.",
	client: "GAHJZHVKFLATA7RVGXSFKXAKT5H4RXJ4LU2UR2W2IDFXOJQ2BR7RHW62",
	serviceProvider: "GDWPCWWH7IXQJHDF7FJUI7VOGD5IT72T7YX55F4BR2H4WXFRBVMBK6A3", 
	platformAddress: "GBC5DVYUBTBSXJ3ZMRPGXDDDLKTALIFGRW73B33AF5EFSZBUECKSFO4R",
	amount: "1000.00",
	platformFee: "50.00", 
	milestones: [
		{ description: "Initial phase of the project", status: "Pending" },
		{ description: "Completion of design work", status: "Pending" }
	],
	releaseSigner: "GBDKXCG6FHJMTUBWGAVVOD5PB5QXLYTRJGCH4NR4IMJVPXHHTBBXPY3V",
	disputeResolver: "GDJVCNR5GPOJH7XMOVMHBKZV7V7WQ3B7QK75C76HLOBD4AKHFG5OCARJ"
};

Prievious Version:

POST escrow/initialize-escrow

Headers

Body

engagementId

description

issuer

serviceProvider

amount

signer

Example of Request Body:

{
  "engagementId": "test",
  "description": "description test",
  "issuer": "GD2SVFOJ...",
  "serviceProvider": "GD2SVFOJ...",
  "amount": "100",
  "signer": "GD2SVFOJ..."
}

Possible Responses

{
    "status": "SUCCESS",
    "message": "The escrow has been successfully initialized"
}

{
  "error": "Amount cannot be zero"
}

{
    "message": "Message",
    "error": "Bad Request",
    "statusCode": 400
}

{
    "statusCode": 429,
    "message": "ThrottlerException: Too Many Requests"
}

Distributes escrow earnings after the escrow is marked as complete.

URL: /escrow/distribute-escrow-earnings

Body params:

contractId: ID (address) that identifies the escrow contract

releaseSigner: Address of the user defined to release the funds

Example:

{
	contractId: "GC3DJY4LLQYJHEONXFDLQVVRCFZQCPFX7VD33KP4P7QSVZY3SJHQBZGV",
	releaseSigner: "GBY3PAJY5R3ZIXTYBGFW4URB4RINEXQBC3T4RWDDKJ5TZXQYZUN6A4TP", 
};

This was previously called complete escrow:

POST escrow/complete-escrow

Headers

Body

engagementId

signer

contractId

Example of Request Body:

{
  "engamentId": "test", 
  "signer": "GD2SVFOJ...",
  "contractId": "SCMXDC..."
}

Possible Responses

{
    "status": "SUCCESS",
    "unsignedTransaction": "AAAAAgAAAABfQAm/gS..."  // XDR Hash Transaction
}

{
  "error": "Only the signer can complete the escrow"
}

{
  "error": "Escrow not funded"
}

{
    "error": "Escrow already completed"
}

{
  "error": "Escrow not found"
}

{
  "error": "The signer does not have sufficient funds"
}

{
    "message": "Message",
    "error": "Bad Request",
    "statusCode": 400
}

{
    "statusCode": 429,
    "message": "ThrottlerException: Too Many Requests"
}

What this Endpoint returns?

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

GitHub Repository

API Swagger

Warning!

You'll have 50 as a request rate limit per client in the API every 60 seconds.

Introduction to the Trustless Work REST API

The Trustless Work REST API is designed to offer decentralized escrow solutions by leveraging the power of smart contracts on the Stellar blockchain through Soroban. This API enables platforms and businesses to integrate secure, fast, and transparent escrow services, eliminating the need to rely on centralized intermediaries.

What is the API for?

The Trustless Work API is a key component for any platform that requires secure conditional payments. It allows the creation, management, and automation of escrow contracts, providing security for both payers and payees. This API can be used across various industries including e-commerce, SaaS, real estate, freelance marketplaces, and more.

Key API Functions:

• Create and manage escrow contracts: Users can set up payment agreements with specific conditions that must be met before funds are released.

• Real-time status updates: The API provides real-time access to escrow statuses, allowing users to verify the state of funds at any time.

• Process automation: Through the use of smart contracts, actions such as fund releases, milestone verification, or dispute resolution can be automated.

Why is the API important?

This API is critical for offering businesses an efficient and secure way to manage payments without relying on third-party services. Trustless Work’s decentralized nature eliminates the risks associated with centralized intermediaries, such as delays or failures. Additionally, being blockchain-based guarantees full transparency and a significant reduction in operational costs.

REST API Advantages:

• Transparency: Every transaction is recorded on the blockchain, making it auditable and ensuring that all parties can track the flow of funds.

• Low Costs: Built on Stellar, the API benefits from minimal transaction fees compared to traditional solutions or even other blockchain platforms.

• Speed: Stellar's fast transaction finality ensures that payments are processed almost in real-time.

• Cross-chain compatibility: With USDC and Circle’s cross-chain transfer protocol, the API can operate across multiple blockchains, offering flexibility to businesses.

API Use Cases

1. Freelance marketplaces: Freelance platforms can use the API to manage milestone-based payments, enhancing trust and reducing disputes between clients and freelancers.

2. High-value e-commerce: In peer-to-peer transactions, escrow ensures that payment is only released once the product has been received and verified.

3. SaaS providers: Platforms managing recurring payments can leverage the API to release payments upon successful service delivery.

4. International real estate: Trustless Work helps secure funds in cross-border real estate transactions by releasing them only when all legal and contractual obligations are met.

5. Legal services: Law firms can manage complex multi-party agreements or settlements without needing manual escrow services.

In summary, the Trustless Work REST API provides a robust, transparent, and cost-effective solution for managing escrowed funds, catering to a wide range of industries and promoting security and trust in digital transactions.

POST helper/set-trustline

Headers

Params

Example of Request Body:

{
  "sourceSecretKey": "GDN6I...", 
}

Possible Responses

{
    "status": "SUCCESS",
    "message": "The trust line has been correctly defined in the USDC token"
}

{
  "error": "Internal server error"
}

{
    "message": "Message",
    "error": "Bad Request",
    "statusCode": 400
}

{
    "statusCode": 429,
    "message": "ThrottlerException: Too Many Requests"
}

POST helper/send-transaction

Headers

Body

Example of Request Body:

{
  "signedXdr": "AAAAAgAAAAB...",
}

Possible Responses

{
    "status": "SUCCESS",
    "message": "The transaction has been successfully sent to the Stellar network"
}

{
  "error": "Internal server error"
}

{
    "message": "Message",
    "error": "Bad Request",
    "statusCode": 400
}

{
    "statusCode": 429,
    "message": "ThrottlerException: Too Many Requests"
}