Skip to main content

Shift Integration Guide

Integrating Fixed and Variable Shifts​

Best Practices​

  1. Set up environment variables for sensitive data:

    SIDESHIFT_SECRET=your_account_private_key
    AFFILIATE_ID=your_affiliate_id
    API_BASE_URL=https://sideshift.ai/api/v2

  2. Error handling and monitoring:

    • Implement logging system
    • Monitor API response times
    • Track failed requests

Fixed Shift​

Request a Quote: The first step is to request a quote using the /quotes endpoint. This will provide you with a quoteId that you will use in the next step. Always include the x-sideshift-secret header, and if the request originates from the integration's server, the end user’s IP address should be forwarded in the x-user-ip header.

Example of a quote request
curl -L -X POST 'https://sideshift.ai/api/v2/quotes' \
-H 'Content-Type: application/json' \
-H 'x-sideshift-secret: ACCOUNT_PRIVATE_KEY' \
-H 'x-user-ip: END_USER_IP_ADDRESS' \
--data-raw '{
    "affiliateId": "ACCOUNT_AFFILIATE_ID",
    "depositCoin": "BTC",
    "depositNetwork": "bitcoin",
    "settleCoin": "ETH",
    "settleNetwork": "ethereum",
    "depositAmount": "0.01"
}'

Implementation notes:

  • Store the returned quoteId
  • Implement quote expiration handling
  • Add error handling for network issues

Create a Fixed Shift: After obtaining the quoteId, you can create a fixed rate shift using the /shifts/fixed endpoint. The affiliateId used in this step must match the one used to request the quote.

Example of creating a fixed shift
curl -L -X POST 'https://sideshift.ai/api/v2/shifts/fixed' \
-H 'x-sideshift-secret: ACCOUNT_PRIVATE_KEY' \
-H 'x-user-ip: END_USER_IP_ADDRESS' \
--data-raw '{
    "settleAddress": "SETTLE_ADDRESS",
    "affiliateId": "ACCOUNT_AFFILIATE_ID",
    "quoteId": "QUOTE_ID"
}'

Implementation notes:

  • Validate quote hasn't expired
  • Implement proper error handling
  • Start status monitoring after creation

Variable Shift​

Create a Variable Shift: To create a variable shift, use the /shifts/variable endpoint with the required parameters. Always include the x-sideshift-secret header, and if the request originates from the integration's server, the end user’s IP address should be forwarded in the x-user-ip header.

Example of creating a variable shift
curl -L -X POST 'https://sideshift.ai/api/v2/shifts/variable' \
-H 'Content-Type: application/json' \
-H 'x-sideshift-secret: ACCOUNT_PRIVATE_KEY' \
-H 'x-user-ip: END_USER_IP_ADDRESS' \
--data-raw '{
    "settleAddress": "SETTLE_ADDRESS",
    "affiliateId": "ACCOUNT_AFFILIATE_ID",
    "depositCoin": "BTC",
    "depositNetwork": "bitcoin",
    "settleCoin": "ETH",
    "settleNetwork": "ethereum",
}'

Implementation notes:

  • Display min/max deposit ranges
  • Show real-time rate updates
  • Implement proper error handling
  • Start status monitoring

Monitor Status:

  • Poll the shift status every few seconds by using /shift endpoint
  • Handle all possible status states
  • Implement proper UI feedback for each status

Key Integration Guidelines:​

User Permissions​

The /permissions endpoint can be used to determine if the user is allowed to use SideShift.ai. This endpoint can be called before any shift creation.

Deposit​

For fixed rate shifts, a deposit of exactly the amount of depositAmount must be made before the expiresAt timestamp, otherwise the deposit will be refunded. For variable rate shifts, the user can send any amount within the minimum and maximum deposit ranges. The exchange rate will be determined when the user's deposit is received.

Set Refund Address (Optional)​

refundAddress and refundMemo are optional. If not defined, the user will be prompted to enter a refund address manually on the SideShift.ai order page if the shift needs to be refunded. Alternatively, the /shifts/{shiftId}/set-refund-address endpoint can also be used to set the refund address if the shift has a refund status.

Handle Memos (Optional)​

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 hasMemo is true in the /coins endpoint, integrations can specify a settleMemo field.

Receive Settlement​

Once the deposit is confirmed in the blockchain, SideShift.ai will process the shift and send the settled amount to the settleAddress.

Live Demo App​

Try out this Demo App.