API Reference for the Token Swap Service (1.0)

Download OpenAPI specification:Download

Token Swaps are a mechanism to allow two parties to securely trade tokens. Each swap is made up of two trades between the swap initiator and the counterparty. One trade per token contract. For a swap to work, the initiator creates a trade to transfer the token(s) owned by the initiator to the counterparty. In response, the counterparty creates a 2nd trade to transfer the token(s) owned by the counterparty to the initiator.

Token Trades are part of a Token Swap. Each swap is made up of two trades between the swap initiator and the counterparty. One trade per token contract. For a swap to work, the initiator creates a trade to transfer the token(s) owned by the initiator to the counterparty. In response, the counterparty creates a 2nd trade to transfer the token(s) owned by the counterparty to the initiator.

The Token Swap service makes it trivial to trade tokens across token contracts in an atomic manner. Utilizing the Hashed Timelock Contract under the cover, tokens can be securely traded such that the parties of the trades never lose their tokens due to fraud behaviors of their trading partners. The multiple steps involved in the trading flow are all exposed as simple-to-use REST endpoints.

tokenswap

Authentication

app_creds

Kaleido API for marketplace services are authenticated using application credentials. The username and password must be created in the environment containing the service instance as "Application Credentials". For more details see the documentation on App Credentials.

Security scheme type: HTTP
HTTP Authorization Scheme basic

Token Trades

Initiate or respond to a token swap trade

Authorizations:
Request Body schema: application/json
token-address
required
string

The address of the Token Contract

from
required
string

The from account address to debit the token(s) from

to
required
string

The target account address to receive the token(s)

amount
string

The amount of tokens to trade (erc20 only)

token-id
string

The tokenId to trade (erc721 only)

timeout
integer

The number of seconds before the trade times out and tokens are able to be refunded

hash-lock
string

The hash lock that must be sent if responding to a token swap trade offer

Responses

200

Token Swap Trade Complete

500

Internal Error

post /trades

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/trades

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token-address": "string",
  • "from": "string",
  • "to": "string",
  • "amount": "string",
  • "token-id": "string",
  • "timeout": 0,
  • "hash-lock": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secret": "string",
  • "hash-lock": "string",
  • "trade-id": "string"
}

Get the details of a particular token trade

Authorizations:
path Parameters
trade_id
required
string

Responses

200

Trade retrieved

500

Internal Error

get /trades/{trade_id}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/trades/{trade_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "sender": "string",
  • "receiver": "string",
  • "token-contract": "string",
  • "hash-lock": "string",
  • "time-lock": 0,
  • "withdrawn": true,
  • "refunded": true,
  • "secret": "string",
  • "token-id": "string",
  • "amount": "string"
}

Withdraw / claim the token(s) from a trade

Authorizations:
path Parameters
trade_id
required
string
Request Body schema: application/json
secret
required
string

The secret that is used to claim the tokens from a completed trade

from
required
string

The from account address used to sign the withdraw transaction

Responses

200

Token Withdraw Complete

500

Internal Error

post /trades/{trade_id}/withdraw

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/trades/{trade_id}/withdraw

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secret": "string",
  • "from": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "transactionHash": "string",
  • "success": true
}

Token Swaps

Refund the token(s) from a trade

Authorizations:
path Parameters
trade_id
required
string
Request Body schema: application/json
from
required
string

The from account address used to sign the refund transaction

Responses

200

Token Refund Complete

500

Internal Error

post /trades/{trade_id}/refund

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/trades/{trade_id}/refund

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "from": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "transactionHash": "string",
  • "success": true
}

Get the secret for a particular swap

Authorizations:
path Parameters
hash_lock
required
string

Responses

200

Secret retrieved

500

Internal Error

get /swaps/{hash_lock}/secret

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/{hash_lock}/secret

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secret": "string"
}

Save the secret for a Kaleido managed swap

Authorizations:
path Parameters
hash_lock
required
string
Request Body schema: application/json
secret
required
string

The secret to store

Responses

200

Save Token Secret Complete

500

Internal Error

post /swaps/{hash_lock}/secret

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/{hash_lock}/secret

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secret": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "success": true
}

Get the current state of all Token Swaps

Authorizations:

Responses

200

Swaps retrieved

500

Internal Error

get /swaps

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get the state of a swap by hash_lock

Authorizations:
path Parameters
hash_lock
required
string

Responses

200

Swap retrieved

500

Internal Error

get /swaps/{hash_lock}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/{hash_lock}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "initiator":
    {
    },
  • "counterparty":
    {
    }
}

Get the state of a swap by trade_id

Authorizations:
path Parameters
trade_id
required
string

Responses

200

Swap retrieved

500

Internal Error

get /swaps/byTradeId/{trade_id}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/byTradeId/{trade_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "initiator":
    {
    },
  • "counterparty":
    {
    }
}

Get the swaps involving a certain sender address

Authorizations:
path Parameters
sender
required
string

Responses

200

Swap retrieved

500

Internal Error

get /swaps/bySender/{sender}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/bySender/{sender}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get the swaps involving a certain receiver address

Authorizations:
path Parameters
receiver
required
string

Responses

200

Swap retrieved

500

Internal Error

get /swaps/byReceiver/{receiver}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/swaps/byReceiver/{receiver}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]