Using Swaps

📘

NEW! Instant Swaps, Guaranteed Rates

Wyre is thrilled to announce we now support instant swaps and guarantee exchange rates, eliminating friction and slippage from the process entirely!

Supported Currencies

The Swaps service currently supports BTC, ETH, LINK, USDC, USDT, ALGO, AUSDC (Algorand USDC), AUSDT (Algorand USDT), DAI, AAVE, BAT, COMP, XLM, and SUSDC (Stellar USDC).

Prerequisites

UPDATE:
User data is optional, meaning you may submit a blank User object. Any data submitted will be put through standard KYC checks.

RATE LOCKING
Simply specify 'sourceAmount' in Create Swap to generate a rate locked Swap. Including this parameter results in a 'destAmount' property being returned and the expiration period adjusted.

Create 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": {
        }
    }
}'

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 '{
    "dest": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "refundTo": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "notifyUrl": "https://requestinspector.com/inspect/swap",
    "sourceCurrency": "XLM",
    "sourceAmount": 3,
    "destCurrency": "SUSDC"
}'

{
    "id": "SW_VLZD8JZTH9A",
    "owner": "user:US_4PMWPPJ9PET",
    "status": "CREATED",
    "sourceCurrency": "XLM",
    "destCurrency": "SUSDC",
    "dest": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "refundTo": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "fundingAddress": "stellar:GD7WXI7AOAK2CIPZVBEFYLS2NQZI2J4WN4HFYQQ4A2OMFVWGWAL3IW7K:HELJJLFVBAG",
    "createdAt": 1660604060000,
    "updatedAt": 1660604060000,
    "expiresAt": 1660604960000,
    "sourceAmount": 3,
    "destAmount": 0.363524,
    "swapTransfers": [],
    "networkTxId": null
}

Confirm Swap Status

When a swap is completed Wyre will push an event to the 'notifyUrl', use this as the trigger to query the swap status.

{
    "swapId": "SW_6W42ZTHZ682"
}

{
    "id": "SW_VLZD8JZTH9A",
    "owner": "user:US_4PMWPPJ9PET",
    "status": "COMPLETED",
    "sourceCurrency": "XLM",
    "destCurrency": "SUSDC",
    "dest": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "refundTo": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
    "fundingAddress": "stellar:GD7WXI7AOAK2CIPZVBEFYLS2NQZI2J4WN4HFYQQ4A2OMFVWGWAL3IW7K:HELJJLFVBAG",
    "createdAt": 1660604060000,
    "updatedAt": 1660604277000,
    "expiresAt": 1660604960000,
    "sourceAmount": 3,
    "destAmount": 0.363524,
    "swapTransfers": [
        {
            "id": "ZA7EMTZBMZC",
            "swapId": "SW_VLZD8JZTH9A",
            "transferId": "TF_PVL9NGZ3UMT",
            "type": "SWAP",
            "reason": null,
            "refundedTo": null,
            "createdAt": 1660604199000,
            "source": "swap:SW_VLZD8JZTH9A",
            "dest": "stellar:GBSJNVALLZMYVWIPV4C2DNGV2MP7JNIEFJXXYFKK2MNRSVFB6TLEVBGH",
            "sourceCurrency": "XLM",
            "destCurrency": "SUSDC",
            "sourceAmount": 3,
            "destAmount": 0.363524,
            "transferStatus": "COMPLETED",
            "networkTxId": "e884acf59e0b0c82c0d1b2eed2c83ccb8a53915465e587f372fd1ce4e3db405d"
        }
    ],
    "networkTxId": null
}

Note, that the amount received at the destination address, 0.363524 exactly matches the initial 'destAmount' returned at Swap creation.

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

By default swaps are valid for 72 hours. 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.

Rate locked swaps expire much sooner than swaps without rate locking. For most networks it will be around 15 minutes but is such to change. Always pay attention to the 'expiresAt' property returned for rate locked Swaps.

🚧

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.