DOCSEARCHbyAlgolia
Submit Docs

SideShift.ai API Documentation

website·Indexed 35 days ago

https://docs.sideshift.ai/

Documentation for integrating SideShift's trading infrastructure to enable fast, direct-to-wallet crypto swaps. Includes guides on creating fixed and variable rate shifts, requesting quotes, managing accounts, and earning crypto commissions. Features detailed references for V1 and V2 API endpoints, including coin and pair lookups, deposit mechanics, and network fee structures.

Tokens
30.8K
Snippets
105
Records
230
Agent score
55%

What's inside SideShift

  1. Identify deposit issues via API

    When a deposit cannot be automatically processed, the status will be set to review or refund. In these cases, the issue field in the deposit object will contain details about the problem. If the status is multiple, check the individual deposit objects within the deposits array for the issue field.

  2. Migrate from SideShift.ai V1 to V2 API

    SideShift.ai has deprecated the V1 API and strongly advises all integrators to migrate to the V2 API. The V2 version provides more efficient handling of multi-network coins and uses simplified terminology. V1 is no longer under active development.

  3. Create a Fixed Rate shift

    Fixed rate shifts lock in an exchange rate for 15 minutes. They are recommended when the settleAmount must be exact or when users cannot change the amount they send.

    Important: If the exact expected amount is not sent to a fixed order, the transaction will fail and must be refunded. It is strongly advised to set a refundAddress (ideally the user's sending address) during shift creation to streamline the refund process.

    Workflow:

    1. Request a quote using the /v2/quotes endpoint.
    2. Use the returned quoteId to create the shift via the /v2/shifts/fixed endpoint.
    # Step 1: Get Quote
POST /v2/quotes

# Step 2: Create Fixed Shift
POST /v2/shifts/fixed

  4. Handle multiple deposits for Fixed and Variable shifts

    The behavior for multiple deposits depends on the shift type:

    • Fixed Shifts: Only the first valid deposit is settled. Subsequent deposits are refunded.
    • Variable Shifts: Multiple deposits are processed individually. They are not merged; each is handled based on its own conditions and the market rate at the time of processing.

    Integrators are advised to discourage users from making multiple deposits to the same shift.

  5. Set up a SideShift.ai account for API integration

    To use the SideShift API, you must create an account. This account represents your integration (not individual end-users). You can create an account via the website, the account page, or programmatically using POST /v2/create-account.

    Once created, you must secure two pieces of information:

    1. Private Key: Used as the x-sideshift-secret header for authentication. This is your 'soft authentication' key; SideShift does not issue traditional API keys.
    2. Account ID: Passed as the affiliateId in requests to attribute shifts to your integration.
    # Example .env configuration
SIDESHIFT_SECRET=YOUR_ACCOUNT_SECRET
AFFILIATE_ID=YQMi62XMb

  6. Handle user deposits and QR codes

    The SideShift REST API returns the deposit address (and a memo if required by the coin). Developers should use this address to display a QR code on their own site. To redirect a user directly to SideShift to manage their order, use the URL: https://sideshift.ai/orders/.

  7. Set a refund address for a shift

    A refund address can be set during the creation of a shift or updated later using the /v2/shifts/:shiftId/set-refund-address endpoint. It is highly recommended to set the refundAddress at creation to ensure automatic refunds and to prevent unauthorized users from specifying a refund destination if they obtain the shift ID.
    POST /v2/shifts/:shiftId/set-refund-address

  8. Manage deposit addresses and their lifecycle

    Deposit addresses are temporary and have a specific expiration window. Once unassigned, an address may be reused for other shifts.

    • Lifespan: Addresses stay assigned for 60 days (40 days for EVM token deposit addresses).
    • Persistence: Developers should persist the address upon shift creation and treat the depositAddress field as nullable when calling /v2/shifts/{shiftId} or /v2/shifts.
    • Constraint: Never send funds to an address from an expired shift.

  9. Handle multiple deposits in Fixed and Variable shifts

    The behavior for multiple deposits depends on the shift type. Integrators should discourage users from making multiple deposits to a single shift.

    • Fixed Shifts: Only the first valid deposit is settled. All subsequent deposits are refunded to the user.
    • Variable Shifts: Multiple deposits can be processed individually. They are not merged and are handled based on market rates at the time of processing.

  10. Rotate SideShift account credentials

    To rotate credentials, call the POST /v2/create-account endpoint. This action creates a completely new account with a new id and secret; it does not rotate the secret on an existing account. You must replace both the SIDESHIFT_SECRET and AFFILIATE_ID in your configuration with the new values.
    # Call this endpoint to generate a new account ID and secret
POST /v2/create-account

  11. Handle user permissions and IP proxying

    SideShift.ai is unavailable in certain jurisdictions. Integrators should use the /v2/permissions endpoint to verify if a user is allowed to use the service.

    Proxying Requirements: SideShift does not allow proxying user requests. If API requests are sent from your server rather than the user's client, you must set the x-user-ip header to the end-user's actual IP address to ensure security and compliance with regional restrictions.

  12. Set and manage refund addresses

    Refund addresses are used to automatically return funds if a shift expires, the user sends an incorrect amount, or the amount is outside the allowed range. You can set a refund address in two ways:

    1. During the initial shift creation request.
    2. By using the /v2/shifts/:shiftId/set-refund-address endpoint.

    For wallet integrations, it is recommended to set the refundAddress to the address the user is sending from to ensure a smooth refund process.

    POST /v2/shifts/:shiftId/set-refund-address