Skip to main content

Refunds

SideShift.ai may have to refund the user’s deposit for multiple reasons mentioned in Deposit Issues.

Refunds are processed automatically if a refundAddress is set when creating shifts. This applies to both fixed rate shifts via the /v2/shifts/fixed endpoint and variable rate shifts via the /v2/shifts/variable endpoint.

For coins that require a memo, the refundMemo is optional but can be included.

Refund Flow

Refund flow example​

The example below shows a fixed rate shift where the user sends the wrong deposit amount. Because the integration already supplied a refundAddress, SideShift.ai can move from detecting the issue into the refund flow without waiting for additional user input.

Create a fixed shift with a predefined refund destination
curl -L -X POST 'https://sideshift.ai/api/v2/shifts/fixed' \
-H 'Content-Type: application/json' \
-H 'x-sideshift-secret: ACCOUNT_PRIVATE_KEY' \
-H 'x-user-ip: END_USER_IP_ADDRESS' \
--data-raw '{
  "settleAddress": "0xF189eD5F2102402B5E8BD03936b009030f5732c7",
  "refundAddress": "0xd1a8ADC8ca3a58ABbbD206Ed803EC1F13384ba3c",
  "affiliateId": "ACCOUNT_AFFILIATE_ID",
  "quoteId": "46a272bb-0234-4429-ac30-135dc9a92477"
}'
  1. The integration creates the shift and stores the returned data.
  2. The user sends funds to the depositAddress, but the amount does not match the fixed quote.
  3. When SideShift.ai detects the deposit, the shift enters refund with an issue such as incorrect amount.
  4. Because refundAddress is already known, SideShift.ai can create and broadcast the refund transaction without waiting for user input.
  5. After the refund transaction is created and confirmed, the shift eventually progresses through refunding to refunded.
Status after the bad deposit is detected
{
  "id": "3907c0c08d9791ed1fc1",
  "createdAt": "2024-05-24T23:40:35.726Z",
  "depositCoin": "BNB",
  "settleCoin": "USDT",
  "depositNetwork": "bsc",
  "settleNetwork": "bsc",
  "depositAddress": "0x9Ee1119931c1C0C1aCF49c82E8D68532E665e066",
  "settleAddress": "0xF189eD5F2102402B5E8BD03936b009030f5732c7",
  "depositMin": "0.0167",
  "depositMax": "0.0167",
  "type": "fixed",
  "quoteId": "46a272bb-0234-4429-ac30-135dc9a92477",
  "depositAmount": "0.01",
  "expiresAt": "2024-05-24T23:55:27.526Z",
  "status": "refund",
  "averageShiftSeconds": "24.435887",
  "updatedAt": "2024-05-24T23:41:44.181Z",
  "depositHash": "0x9b56e915677ab1bfb678d9ad6846cd724c538496cb199a4045032745f719a88a",
  "depositReceivedAt": "2024-05-24T23:41:32.305Z",
  "rate": "586.537938323353",
  "issue": "incorrect amount"
}
Status after the refund is completed
{
  "id": "3907c0c08d9791ed1fc1",
  "createdAt": "2024-05-24T23:40:35.726Z",
  "depositCoin": "BNB",
  "settleCoin": "USDT",
  "depositNetwork": "bsc",
  "settleNetwork": "bsc",
  "depositAddress": "0x9Ee1119931c1C0C1aCF49c82E8D68532E665e066",
  "settleAddress": "0xF189eD5F2102402B5E8BD03936b009030f5732c7",
  "depositMin": "0.0167",
  "depositMax": "0.0167",
  "refundAddress": "0xd1a8ADC8ca3a58ABbbD206Ed803EC1F13384ba3c",
  "type": "fixed",
  "quoteId": "46a272bb-0234-4429-ac30-135dc9a92477",
  "depositAmount": "0.01",
  "expiresAt": "2024-05-24T23:55:27.526Z",
  "status": "refunded",
  "averageShiftSeconds": "24.435887",
  "updatedAt": "2024-05-24T23:41:44.181Z",
  "depositHash": "0x9b56e915677ab1bfb678d9ad6846cd724c538496cb199a4045032745f719a88a",
  "settleHash": "0xccf5021fcadd7ca624ae89a2a16ba70c28f39ff3beafddb2dfaa0adcde427d4b",
  "depositReceivedAt": "2024-05-24T23:41:32.305Z",
  "rate": "586.537938323353"
}

settleHash contains the refund transaction hash once the refund has been broadcast and confirmed.

If a refundAddress was not provided when the shift was created, it can be added later with /v2/shifts/{shiftId}/set-refund-address, or the user can enter it manually at https://sideshift.ai/orders/{shiftId}.

Without a refund address, a shift can still move to refund, but it cannot progress through the refund flow until the refund destination is supplied. Integrations should treat refund as an actionable state and prompt the user immediately.

tip

Replace {shiftId} with the actual shift ID, for example 3907c0c08d9791ed1fc1.