Kaleido Logo
Documentation Powered by ReDoc

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:
app_creds
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

Request samples

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

Response samples

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

Get the details of a particular token trade

Authorizations:
app_creds
path Parameters
trade_id
required
string

Responses

Response samples

Content type
application/json
{
  • "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:
app_creds
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

Request samples

Content type
application/json
{
  • "secret": "string",
  • "from": "string"
}

Response samples

Content type
application/json
{
  • "transactionHash": "string",
  • "success": true
}

Refund the token(s) from a trade

Authorizations:
app_creds
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

Request samples

Content type
application/json
{
  • "from": "string"
}

Response samples

Content type
application/json
{
  • "transactionHash": "string",
  • "success": true
}

Token Swaps

Get the secret for a particular swap

Authorizations:
app_creds
path Parameters
hash_lock
required
string

Responses

Response samples

Content type
application/json
{
  • "secret": "string"
}

Save the secret for a Kaleido managed swap

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

The secret to store

Responses

Request samples

Content type
application/json
{
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get the current state of all Token Swaps

Authorizations:
app_creds

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the state of a swap by hash_lock

Authorizations:
app_creds
path Parameters
hash_lock
required
string

Responses

Response samples

Content type
application/json
{
  • "initiator":
    {
    },
  • "counterparty":
    {
    }
}

Get the state of a swap by trade_id

Authorizations:
app_creds
path Parameters
trade_id
required
string

Responses

Response samples

Content type
application/json
{
  • "initiator":
    {
    },
  • "counterparty":
    {
    }
}

Get the swaps involving a certain sender address

Authorizations:
app_creds
path Parameters
sender
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the swaps involving a certain receiver address

Authorizations:
app_creds
path Parameters
receiver
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]