sideshift-api Node.js - REST API Client

TypeScript client for the official Sideshift API

Use Cases

Good job Human! You've just unlocked the sideshift-api module's potential. This package offers a developer-friendly interface to the official SideShift API, enabling seamless cryptocurrency swapping integration into diverse applications including:

• Cryptocurrency Wallets: Enhance your wallet app by allowing users to swap coins directly within the interface.

• Decentralized Exchanges: Create decentralized exchange platforms with real-time coin swapping capabilities.

• Payment Gateways: Offer customers the flexibility to pay in their preferred cryptocurrency and automatically convert it to your desired coin for processing.

Note: You might also find the sideshift-api-payment-toolkit useful for integrating payment processing functionality.

Key features

• Easy Integration: With just a few lines of code to integrate cryptocurrency swapping capabilities into your Node.js applications.

• Wide Coin Support: Access the full spectrum of 250+ coins supported by SideShift, allowing users to swap seamlessly between various cryptocurrencies.

• Support all sideshift API endpoints

Installation

This module requires Fetch to work.

For Node.js versions 18+, no additional dependencies are needed as Fetch is built-in.

npm install sideshift-api

For Node.js < 18, install fetch before the module.

npm install --save node-fetch // Only for Node.js version < 18

npm install sideshift-api

Note: To use with Node.js < 18, you may need to update tsconfig.json (change ES2022 to ES2015 or ES2020) and compile manually

Prerequisites

SideShift account: Ensure you have an active SideShift account.

• Account ID: Your unique identifier on SideShift Website/API. It can also be used as the affiliateId to receive commissions.
• Private Key: Your API secret key used for authentication.

Detailled explanation: Navigate to SideShift.ai, click on the "Account" option in the top right corner menu, and you will find your SideShift ID and Private Key on the dashboard (if this is your first visit, you will be prompted to save your private key)

Initialize module

Compatible with both CommonJS and ESM

// CJS
const SideshiftAPI = require('sideshift-api');

// ESM
import { SideshiftAPI } from 'sideshift-api';

Important: This package contains both ESM and CJS exports, which can cause harmless notification error in certain environments. If you encounter thoses errors at server start, make sure your project configuration matches your import style.

Common solutions:

• Use appropriate file extensions (.js for CJS, .mjs for ESM)
• Set the correct "type" field in your package.json ("commonjs" for CJS or "module" for ESM)

Note: These are typically warning messages rather than fatal errors and won't prevent the application from running.

Module setting:

const SIDESHIFT_ID = "Your_ShideShift_Account_ID";
const SIDESHIFT_SECRET = "Your_ShideShift_Private_Key";
const COMMISSION_RATE = "0.5"; // Set your commission rate from 0 to 2%. Default: 0.5
const RETRIES =  {
    maxRetries: 5,
    retryDelay: 2000,
    retryBackoff: 2,
    retryCappedDelay: 10000
}; // Optional

Initialize:

const sideshift = new SideshiftAPI({
    secret: SIDESHIFT_SECRET,
    id: SIDESHIFT_ID,
    commissionRate: COMMISSION_RATE, // Optional
    verbose: true, // Optional
    retries: RETRIES // Optional retries settings
});

Test:

async function test(){
    try {
        console.log(await sideshift.getCoins());
        console.log(await sideshift.getPermissions());
    } catch (error) {
        console.error('SideShift API Error:', error.message);
    }
}
test();

Custom Commission Rate Setting

Allows you to set custom commission rates for each request.

Commission rates are 0-2% fees charged on transactions and paid to the SideShift account owner.

Usage example: Premium members or logged-in users can have lower commission rates.

customCommissionRate is an optional setting that overrides the initial commissionRate configuration without modifying the original setting.

Supported Methods

• getPair
• getPairs
• requestQuote
• createFixedShift
• createVariableShift
• createCheckout

Verbose mode

When verbose mode is enabled, all requests are logged with:

• URL and HTTP method
• Request headers
• Request body (stringified)
• Full request/response details for troubleshooting
• API private key is hidden from the log

Log example

=== DEBUG REQUEST ===
URL: https://sideshift.ai/api/v2/cancel-order
Method: POST
Headers: {
    "Content-Type": "application/json",
    "x-sideshift-secret": '[FILTERED]'
}
Body: {"orderId":"4f72a1852d8b2c10537b"}
=====================

Error Handling

When encountering errors, the module returns an error object with the following format:

{
    "status": 400,
    "statusText": "Bad Request",
    "url": "https://sideshift.ai/api/v2/cancel-order",
    "options": {"Fetch options"}
    "error": {
        "message": "Order already expired"
    },
    "stack": "error stack" // if available
}

Server call and response

For detailed API call and response examples, see Github Repo ENDPOINTS_AND_RESPONSES.md

For detailed SideShift API endpoints, see the SideShift API official documentation

Get endpoints

| SideShift Endpoints | Module Methods | |--------|--------| | coins | getCoin | | coin icon | getCoinIcon | | permissions | getPermissions | | pair | getPair | | pairs | getPairs | | shift | getShift | | bulk shifts | getBulkShifts | | recent shifts | getRecentShifts | | xai stats | getXaiStats | | account | getAccount | | checkout | getCheckout |

Post endpoints

| SideShift Endpoints | Module Methods | |--------|--------| | request quote | requestQuote | | create fixed shift | createFixedShift | | create variable shift | createVariableShift | | set refund address | setRefundAddress | | cancel order | cancelOrder | | create checkout | createCheckout |

Release note v1.1.0

Minor update

Validation helper

• Updated: _validateNumber
• Added: sanitizeNumber

Benetifs: More flexibility with number input, now supports both numbers and string numbers

Max retries configurations

Minor logic update: Changed some ?? operators to ||

_isValidCommissionRate

Bug Fix: Now properly accepts 0 as a valid commission rate

_filterHeaders

• Added: try...catch block for error handling

_calculateBackoffDelay

• Added: Input validation

_handleResponse

• Updated: Enhanced error handling
• Added: originalError to error response
• Added: BaseError interface

_createError,

• Added: BaseError interface
• Added: response to error data

_request, _requestImage

• Added: BaseError interface

Changelog

1.0.9 (2025-11-20)

Minor update

Source map removal

• Removed all sourcemaps from production release
• Unpacked size reduced by 15 KB

Helper Functions

• Added _get helper function for GET requests with headers

Add customCommissionRate setting

customCommissionRate overrides the initial commissionRate configuration setting without modifying the original setting.

• Added to getPair, getPairs, requestQuote, createFixedShift, createVariableShift, createCheckout
• Updated _getSpecialHeader
• Added _isValidCommissionRate to check customCommissionRate validity

Benefits: Allows you to set custom commission rates for specific customers (e.g., logged-in users can have lower commission rates)

1.0.8 (2025-11-18)

Interface correction

Coins interface:

• Added missing mainnet key
• Made tokenDetails optional
• Corrected TokenDetails network key
• Made hasMemo optional (will be deprecated in SideShift API)

BaseShiftData interface:

• Added missing issue and refundMemo key
• Added MultipleFixedShiftData

1.0.7 (2025-11-16)

• V1.0.7 With index.cjs.d.ts.map and index.d.ts.map generation for production build
• V1.0.7-dev Development version includes all sourcemaps

1.0.0 - 1.0.6

• Removed: Compilation errors related to dual CJS/ESM support

Licence

MIT