Create variable shift

POST 
/shifts/variable

For variable rate shifts, the settlement rate is determined when the user's deposit is received.

For shifts that return a depositMemo, the deposit transaction must include this memo, otherwise the deposit might be lost.

For shifts settling in coins where the network is included in the networksWithMemo array in the /v2/coins, integrations can specify a settleMemo field, for example "settleMemo": "123343245".

When defining non-native tokens like AXS and USDT for depositCoin and/or settleCoin, the depositNetwork and settleNetwork fields must also be specified. This also applies to native tokens like ETH that supports multiple networks. depositCoin can also be a token contract address for the selected depositNetwork when you need to target a specific token implementation.

info

When a shift is created with a contract address in depositCoin, the response will normalize depositCoin back to the canonical asset ticker, such as USDC.

Authentication is required: sign the request or send the legacy x-sideshift-secret header, found on the account page under the account secret.

warning

Authenticate by signing the request or with the legacy x-sideshift-secret header. Your Ed25519 secret key and your account secret each grant full access to your account. Never share them.

refundAddress and refundMemoare optional, if not defined, user will be prompted to enter a refund address manually on the SideShift.ai order page if the shift needs to be refunded.

commissionRate optional parameter can be used to adjust rates for your users. The default commission rate is 0.5%. Rates below the default offer better rates by reducing affiliate commission, while rates above the default are passed on to the user. The maximum commission rate is 2%.

info

Use the same commissionRate in the /v2/pair and /v2/pairs endpoints as when creating the shift/quotes to get an accurate rate information. See Monetization for detailed examples of how commission rates affect rates.

If the API requests are sent from the integration’s own server, the x-user-ip header must be set to the end-user IP address; otherwise, the requests will be blocked. See Permissions.

averageShiftSeconds represents the average time in seconds it takes for SideShift to process a shift once the user’s deposit is confirmed on the blockchain.

settleCoinNetworkFee represents the estimated sum of network fees charged for the shift denominated in settle coin.

networkFeeUsd represents the estimated sum of network fees charged for the shift denominated in USD.

externalId is an optional field that can be used to pass an integration's own ID to the API.

Request

Header Parameters

x-sideshift-key string

Your Ed25519 public key, hex encoded. Required when signing the request. See Authentication.

x-sideshift-timestamp string

Current Unix time in milliseconds, the same value used in the signed message. Must be within 60 seconds of server time. Required when signing the request.

x-sideshift-signature string

Ed25519 signature of timestamp + METHOD + path + body, hex encoded. Required when signing the request. See Authentication.

x-sideshift-secret string

Legacy account secret. Not needed when the request is signed with the x-sideshift-key, x-sideshift-timestamp and x-sideshift-signature headers. See Authentication.

x-user-ip string

end-user IP address for integrations API requests

application/json

Body

settleAddressstringrequired
settleMemostring

for coins where network is included in networksWithMemo array

refundAddressstring
refundMemostring
depositCoinstringrequired

ticker or token contract address for the selected depositNetwork

settleCoinstringrequired
depositNetworkstring

required for non-native tokens (e.g. AXS, USDT) and multi-network native tokens (e.g. ETH).

settleNetworkstring

required for non-native tokens (e.g. AXS, USDT) and multi-network native tokens (e.g. ETH).

affiliateIdstringrequired
externalIdstring

integration's own ID

Responses

201

OK

application/json

Schema

Schema

idstringrequired
createdAtstringrequired
depositCoinstringrequired
settleCoinstringrequired
depositNetworkstringrequired
settleNetworkstringrequired
depositAddressstringrequired
depositMemostring
settleAddressstringrequired
settleMemostring
depositMinstringrequired
depositMaxstringrequired
refundAddressstring
refundMemostring
typestringrequired
expiresAtstringrequired
statusstringrequired
averageShiftSecondsstring
externalIdstring
settleCoinNetworkFeestringrequired
networkFeeUsdstringrequired

Example

{
  "id": "71449070046fcfee010z",
  "createdAt": "2024-01-31T01:04:14.978Z",
  "depositCoin": "ETH",
  "settleCoin": "USDT",
  "depositNetwork": "ethereum",
  "settleNetwork": "ethereum",
  "depositAddress": "0x44642E63D5a50e872Df2d162d02f9A259b247350",
  "settleAddress": "0xde2642b2120fd3011fe9659688f76e9E4676F472",
  "depositMin": "0.021551429911",
  "depositMax": "17.06368164",
  "refundAddress": "0xde2642b2120fd3011fe9659688f76e9E4676F472",
  "type": "variable",
  "expiresAt": "2024-02-07T01:04:14.978Z",
  "status": "waiting",
  "averageShiftSeconds": "45.830392",
  "externalId": "integration-1234",
  "settleCoinNetworkFee": "4.210057",
  "networkFeeUsd": "4.21"
}

400

Bad Request

application/json

Schema

Schema

error object
messagestringrequired
codestringrequired
orderIdstring
depositRangeMinstring
depositRangeMaxstring

Example

{
  "error": {
      "message": "Bad request: Invalid parameters: settleAddress",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Unknown affiliateId",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Invalid externalId",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Invalid receiving address",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Invalid refundDestination",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "This refund address belongs to SideShift.ai",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Commission rate cannot be higher than 0.02",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Invalid parameters: commissionRate: Must be a positive number",
      "code": "BAD_USER_INPUT"
  }
}

401

Unauthorized

application/json

Schema

Schema

error object
messagestringrequired
codestringrequired
orderIdstring
depositRangeMinstring
depositRangeMaxstring

Example

{
  "error": {
      "message": "Do not use the example affiliateId and x-sideshift-secret header from the documentation. Use your own from https://sideshift.ai/account",
      "code": "SESSION_REQUIRED"
  }
}

403

Forbidden

application/json

Schema

Schema

error object
messagestringrequired
codestringrequired
orderIdstring
depositRangeMinstring
depositRangeMaxstring

Example

{
  "error": {
      "message": "Access denied. See https://sideshift.ai/access-denied",
      "code": "ACCESS_DENIED"
  }
}

404

Not Found

application/json

Schema

Schema

error object
messagestringrequired
codestringrequired
orderIdstring
depositRangeMinstring
depositRangeMaxstring

Example

{
  "error": {
      "message": "Account not found",
      "code": "NOT_FOUND"
  }
}

500

Internal Server Error

application/json

Schema

Schema

error object
messagestringrequired
codestringrequired
orderIdstring
depositRangeMinstring
depositRangeMaxstring

Example

{
  "error": {
      "message": "Invalid coin",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Invalid network",
      "code": "BAD_USER_INPUT"
  }
}

{
  "error": {
      "message": "Memo is not supported for this deposit coin",
      "code": "BAD_USER_INPUT"
  }
}