Create Swap

🚧

Supported Currencies

At the moment, only BTC, USDC, ETH, USDT, and LINK are supported in our Swaps API

Prerequisites

Swaps are available for partners who have users with an approved TRANSFER scope. User's must have submitted Name, Address, and Date of Birth to qualify for an approved TRANSFER scope.

Creating an Approved User

curl --location --request POST 'https://api.testwyre.com/v3/users' \
--header 'Authorization: Bearer {Secret_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "blockchains": [
        "ALL"
    ],
    "fields": {
        "firstName": "Test",
        "lastName": "User",
        "dateOfBirth": "2000-01-01",
        "residenceAddress": {
            "street1": "1 Sunny Dr",
            "city": "Philadelphia",
            "state": "PA",
            "postalCode": "55555",
            "country": "US"
        }
    },
    "scopes": [
        "TRANSFER"
    ]
}'

Creating a Swap

curl --location --request POST 'https://api.testwyre.com/v3/swaps?masqueradeAs=user:{user_id}' \
--header 'Authorization: Bearer {Secret_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
     "sourceCurrency": "BTC",
     "destCurrency": "ETH",
     "dest": "ethereum:0x0d6E750f558226CEb5b19b236B1b882d83B18892",
     "refundTo": "{refundSRN}"
}'

{
    "id": "SW_TTBDQ69DMJM",
    "owner": "user:US_YMZDTTX8YHG",
    "status": "CREATED",
    "sourceCurrency": "BTC",
    "destCurrency": "ETH",
    "dest": "ethereum:0x0d6E750f558226CEb5b19b236B1b882d83B18892",
    "refundTo": "account:AC_YC3NT6GEZ8U",
    "fundingAddress": "bitcoin:mtbuhoLN9kakApSTmL7rFZmgXS69ZdrEsG",
    "createdAt": 1632949495000,
    "updatedAt": 1632949495000,
    "expiresAt": 1633208695000,
    "swapTransfers": [],
    "networkTxId": null
}

Swap Lifecycle

A newly created swap will have a CREATED status.

When funds arrive on the fundingAddress, the swap will either succeed or initiate a refund.

If the swap is valid, the swap status will be changed to PROCESSING when a transfer is created. When the funds are confirmed on the network, the status will be changed to COMPLETED.

In the case where the deposited funds are too small, and there would be nothing left for sending to the destination after subtracting all the fees, we will try to refund the deposit amount to the SRN in the refundTo parameter. If the refundTo is a wallet SRN, account SRN, or user SRN, there should be no issues with the refund. However, if the refundTo value is a wallet address and the amount is too small, we will refund the funding amount to the swap owner, which is the user SRN. The status will be changed from CREATED to PROCESSING_REFUND, then finally to REFUND.

Once in PROCESSING state, the exchange rate is defined and locked. You could retrieve the swap transfer by calling the Get Swap endpoint.

Expiration

After a swap has expired, it will cease to function. Funds sent to it will be sent to the refundTo parameter. In case of any error, it will refund to the swap owner, specified by the user SRN.

🚧

Use Masquerading

The endpoint only accept a valid user session. If you are creating a swap on behalf of the user, you will need to use the masqueradeAs URL parameter.

You will encounter AccessDeniedException responses if you attempt to create a swap without this.