Atomic Swaps

Exchanging one token against another.

When exchanging tokens, an Atomic Swaps are essential to guarantee that both tokens are exchanged instantaneously and without the ability of any party to default on their commitment.

Atomic swaps are single transactions that contain partially signed peaces of the transaction from both parties. Only when the transaction piece gets completed by the counterparty, the transaction can get send to the mining network.

Atomic Swaps either accept the transaction and do the swap or make no transaction at all (thus neither party looses their respective asset). Since the function has no room for one-sided failure, it is a ideal to be implemented in any kind of value exchange, since it reduces fraud levels and security risk. Moreover, the exchange can happen in a peer 2 peer fashion, without any additional intermediary other than the exchanging parties.

In the relysia API, the first atomic swap partial transaction gets created with the /offer endpoint and later completed with the /swap endpoint by the counter party.

The partially signed transaction hex, created by the /offer endpoint, is shared to the party wanting to complete the transaction (e.g. a buyer of an asset).

Swap Types

There are three swap types that can be used to create an offer. Note that the token quantities will be represented as Integers (without decimal places), while the BSV amounts will be of type Number with native decimal representation (e.g. 0.0000001) Token for BSV This type of swap will return an offer hex containing a token input from a user and a desired output amount in BSV. The "sn" parameter is optional and will specify a specific serial number value for an NFT collection. Token for Token This type of swap will return an offer hex containing a token input from a user and a specified token to swap with. The "sn" and "wantedSn" parameters are optional and will specify a specific serial number value for an NFT collection. Alternatively, the "wantedScript" parameter can be used instead of "wantedTokenId" to specify an entire script hex value of a token, regardless of the owner of that token script. BSV for Token This type of swap will return an offer hex containing a specified BSV amount UTXO as an input and a specified token to swap with. Like the previous type, the "wantedSn" parameter is optional and will specify a specific serial number value for an NFT collection. The "wantedScript" parameter can also be used instead of "wantedTokenId" to specify an entire script hex value of a token, regardless of the owner of that token script.

Token for BSV

const dataArray = [{
    "tokenId": "d4b5ec377fa847b53b0e08459326817000886af4-USD",
    "amount" : 10,
    "wantedAmount" : 0.001
}];

Token for Token

const dataArray = [{
    "tokenId": "d4b5ec377fa847b53b0e08459326817000886af4-USD",
    "amount" : 10,
    "wantedTokenId" : "ca7a5c64543850de318639334a5aaa65947914cb-MYNFT",
    "wantedSn" : 1, // optional
    "wantedAmount" : 1
}];

BSV for Token

const dataArray = [{   
    "amount" : 0.001,
    "wantedTokenId" : "d4b5ec377fa847b53b0e08459326817000886af4-USD", 
    "wantedAmount" : 10
}];

Create an Atomic Swap

POST https://api.relysia.com/v1/offer

This endpoint allows user to create a swap offer. The amount is the value in satoshis wanted in exchange for the token

Headers

Name	Type	Description
walletID	string

Request Body

Name	Type	Description
dataArray	array	as per above

200: OK

{
  "statusCode": 200,
  "data": {
    "status": "success",
    "msg": "Operation completed successfully",
    "contents": [
      "0100000001046ae503360b130eb8c1da56c96b9776aade49333550bca085153978dde308c5010000006b483045022100ce974678e2ef48c42dd80e100f8637545e4da32e5d9bdd622066a86187d4a49f0220046b187e4e9b92d62a2edc893fe580f98e8f45fd090a7e175ea87e1ca3b62d88c3210387d82034a417c41916f212a70978c199fead7a3a2769f4d3ed0ebce8f361f835ffffffff0100e1f505000000001976a914ec83f1fb2c52dbd7b2d4c70cf95150560d611b9088ac00000000"
    ]
  }
}

After defining the token asset to sell and the token asset or BSV and amount to receive, a partially signed transaction is created, and the hex value returned. This signature will bind the input provided by the user to the single output value in the offer hex

The hex value can be read by any third party services to complete the transaction in a decentralized way without reliance on the Relyisa infrastructure.

Before accepting an atomic swap, the 2nd party might want to inspect the partially signed transaction hex to ensure they actually receive the asset they expect to get at the right conditions. For that we created the /inspect endpoint. Add any partially signed transaction hex to the endpoint to decode the insights/conditions.

const dataArray = [{
    "swapHex": "string",
}];

Inspect an atomic swap offer.

POST https://api.relysia.com/v2/inspect

This endpoint allows users to inspect an atomic swap hex to verify the validity of the offer.

Request Body

Name	Type	Description
dataArray*	array	as per above

200: OK

{
  "statusCode": 200,
  "data": {
    "status": "success",
    "msg": "Operation completed successfully",
    "offerDetails": [
      {
        "tokenOwnerAddress": "1DuxjqtUenBrXBsLSYn4UEFP8MKXSLfuq4",
        "tokenCreatorAddress": "114pj3BWST7zXWbYpHUyPhR83r9SHFwSN2",
        "tokenSatoshis": 1,
        "wantedSatoshis": 1,
        "tokenImage": "https://upload.wikimedia.org/wikipedia/en/9/95/Test_image.jpg",
        "serialNumber": 1,
        "splittbale": false,
        "contractTxid": "441e1695a5ea130b9b5a7beda88afc75c47f9f4e868e0e025ca51788555010a0",
        "tokenId": "00b91626e0a4b97f624bc1f0d8fa3a3ef35ac664",
        "symbol": "dwE1u6",
        "tokenSupply": 1,
        "verified": true,
        "tokenName": "Test Token - Generated automatically form tests",
        "tokenDescription": "Test Token - Generated automatically form tests"
      }
    ]
  }
}

Finally, after ensuring the partially signed transaction is indeed having the assets one wants to buy for the given price, the atomic swap gets completed by the counterparty with the /swap endpoint.

The /swap endpoint accepts the partially signed transaction hex as input (and thus also works cross platforms with external atomic swap offers).

Always ensure the asset you buy is actually the asset you want. While we try to warn users of "fake" assets, the user is signing whatever the counter party provides (especially when from external counter parties).

const dataArray = [{
    "swapHex": "string"
}];

Accepting atomic swap offers.

POST https://api.relysia.com/v1/swap

This endpoint allows users to accept swap offers by passing respective hex value values.

Headers

Name	Type	Description
walletID	string

Request Body

Name	Type	Description
dataArray	array	as per above

200: OK

{
  statusCode: 200,
  data: {
    status: 'success',
    msg: 'Operation completed successfully',
    txIds: [
      '698080e9917a576a1451770c2cb91b50d27b54c3ecaca663fb54f3ed1b143789'
    ]
  }
}

After completing the atomic swap by counter signing the offer transaction (and adding their piece of information to the puzzle), the transaction is directly submitted and the transaction id returned.