Escrow Container Management

In order to use a user’s assets for your application, you must first require the user to transfer their ownership temporarily to Upland. Upland, in turn, locks these assets in a vault-like account. In Upland terminology, this vault-like account, controlled by Upland, is called an escrow account.

The developer is responsible for specifying necessary assets the users have to transfer to the escrow account to use your application (for example, a drag car-racing application will need a user to place at least one block explore and one car in the escrow to participate).

Within the escrow account, each application is assigned an escrow container, which contains transferred assets necessary to use the application.

At junctions determined by your application logic, your application can request a resolution of its escrow container (for example, at the end of a drag car-racing application, the loser loses his block explore to the winner).

You can also query the content of your application’s escrow container, request to extend its validity, etc.

The available assets the developers can use so far are:

1. Block Explorers

2. Structured Ornaments

3. Spirit Legits

4. Upx

5. 3D Assets

Branded assets such as FIFA, Stock Car, and others need permission to be used.

Escrow Containers Transactions Status

Expired - Transactions not accepted/rejected in time;

Rejected - Transaction which players rejected;

User_signature_requested - When the app sends the request to players';

Changing_ownership - When the transaction is being registered in the blockchain (It can take up to three minutes); - Player to Escrow or Escrow to player

In_escrow - Assets inside the container ready for resolution;

Refunded - Transactions in which assets were given back to players;

Removed - Transactions that were deleted from the container before players' acceptance or rejection;

API Definition

These endpoints require Basic Authentication. Click here to read more about how to generate valid credentials.

Create a new escrow container

post

The third-party application will be able to create a new container in the escrow to receive user assets.

The container times out after the lesser of the developer’s desired container time to live.

The webhook URL will be used by the escrow service to communicate with third-party apps about the transaction status in the container.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Responses

201Success

application/json

post

/containers

HTTPcURLJavaScriptPython

POST /containers HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

201Success

{
  "id": 25,
  "appId": 56,
  "expirationDate": "2022-09-30T09:15:46.993Z",
  "status": "created"
}

Query Escrow Container

get

Retrieve container information by id, including expiration time. The possible values for the container status are created, locked, processing, resolved, and expired.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

Responses

201Success

application/json

get

/containers/{containerId}

HTTPcURLJavaScriptPython

GET /containers/{containerId} HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

201Success

{
  "id": 25,
  "appId": 56,
  "expirationDate": "2022-09-30T09:15:46.996Z",
  "status": "created",
  "upx": 10000,
  "spark": 5,
  "assets": [
    {
      "id": 25,
      "transactionId": "e5e0df15-16d8-4dd4-9ecf-669dee4a80e3",
      "amount": 25,
      "assetId": 2,
      "category": "essential",
      "ownerEosId": "df8447hf",
      "status": "in_escrow"
    }
  ]
}

Refresh Expiration time of Escrow Container

post

Refresh the container expiration for the same amount of time previously informed.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

Responses

204Success

post

/containers/{containerId}/refresh-expiration-time

HTTPcURLJavaScriptPython

POST /containers/{containerId}/refresh-expiration-time HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

204Success

No content

Locks the escrow container (Optional)

post

This action will lock the container. After this action users can not join this container. This doesn't apply to all 3p apps. It's an optional call if a third party wants to make sure that no one else will enter the container.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

Responses

204Success

post

/containers/{containerId}/lock

HTTPcURLJavaScriptPython

POST /containers/{containerId}/lock HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

204Success

No content

To use the resolve endpoint, all assets inside the container must have the status "in_scrow".

Execute operations over the escrow assets and resolve container

post

Send some operations in batch to be executed over the escrow assets and UPXs.

This call is the final resolution. At this moment Escrow Service will execute transactions and close the container. If there are assets remaining, they will return to the account source.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

Body

application/json

Responses

200Success

application/json

post

/containers/{containerId}/resolve

HTTPcURLJavaScriptPython

POST /containers/{containerId}/resolve HTTP/1.1
Host: 
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "actions": [
    {
      "assetId": 2,
      "amount": 25,
      "category": "spark",
      "targetEosId": "df834yr3",
      "isRefund": true
    }
  ]
}

200Success

{
  "transactionId": "e5e0df15-16d8-4dd4-9ecf-669dee4a80e3"
}

Refund container assets

post

It sends back the assets inside the container to the original owners (no fees) and resolves the container.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

Responses

200Success

application/json

post

/containers/{containerId}/refund

HTTPcURLJavaScriptPython

POST /containers/{containerId}/refund HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

200Success

{
  "transactionId": "e5e0df15-16d8-4dd4-9ecf-669dee4a80e3"
}

Remove a transaction from container

delete

Removes a transaction that has not been signed by the user from container.

Authorizations

basic

AuthorizationstringRequired

Basic access authentication is a method to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of (Authorization: Basic [credential]), where credentials is the Base64 encoding of ID and password joined by a single colon :. For our case, you must consider Username as app ID and password as secret key (this information can be generated in endpoint to create application).

Path parameters

containerIdnumberRequired

transactionIdstringRequired

Responses

204Success

delete

/containers/{containerId}/transactions/{transactionId}

HTTPcURLJavaScriptPython

DELETE /containers/{containerId}/transactions/{transactionId} HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

204Success

No content

You must provide a Code to your users generated across the endpoint /auth/opt/init. Then, when Upland User grants access to the developer App, a webhook will be sent with a valid access token. Click here to check the authentication session.

Put assets in escrow container

post

Send a list of user assets that will be added to the escrow container. This action must be approved by Upland User inside the Upland Application to be performed.

Authorizations

bearer

AuthorizationstringRequired

You must provide a Code to your users generated across the endpoint /auth/opt/init. When Upland User grants access for the developer App, a webhook will be sent with a valid access token.

Body

application/json

containerIdnumberRequired

Container Id

Default: 123

upxAmountnumberOptional

Amount of UPX to include in escrow

Default: 10000

sparkAmountnumberOptional

Amount of SPARK to include in escrow (IMPORTANT: SPARK transactions are temporarily blocked)

Default: 1.5

Responses

200Success

application/json

post

/user/join

HTTPcURLJavaScriptPython

POST /user/join HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "containerId": 123,
  "upxAmount": 10000,
  "sparkAmount": 1.5,
  "assets": [
    {
      "id": 124,
      "category": "blkexplorer"
    }
  ]
}

200Success

{
  "transactionId": "ac60eb8a-9c32-4f78-b407-1c0396a645e2"
}