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).
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
Token for Token
BSV for Token
const dataArray = [{
"tokenId": "d4b5ec377fa847b53b0e08459326817000886af4-USD",
"amount" : 10,
"wantedAmount" : 0.001
}];
const dataArray = [{
"tokenId": "d4b5ec377fa847b53b0e08459326817000886af4-USD",
"amount" : 10,
"wantedTokenId" : "ca7a5c64543850de318639334a5aaa65947914cb-MYNFT",
"wantedSn" : 1, // optional
"wantedAmount" : 1
}];
const dataArray = [{
"amount" : 0.001,
"wantedTokenId" : "d4b5ec377fa847b53b0e08459326817000886af4-USD",
"wantedAmount" : 10
}];
post
https://api.relysia.com
/v1/offer
Create an Atomic Swap
It only allowed maximum 2 outputs in payment
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 espect 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",
}];
post
https://api.relysia.com
/v1/inspect
Inspect an atomic swap offer.
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"
}];
post
https://api.relysia.com
/v1/swap
Accepting atomic swap offers.
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.
Last modified 1mo ago