1 of 2

WebSocket API

Introduction

Our WebSocket API uses socket.io. You must use a socket.io client to interact with the Redshift WebSocket API.

If you are building a JavaScript or TypeScript application, we have a JavaScript client package that does a lot of the heavy lifting for WebSockets.

Client Example

import { WebSocketClient } from "@radar/redshift-api-client";

const client = new WebSocketClient();

await client.connect();

const quoteRequest = {
    market: "BTC_LBTC",
    invoice: "lnbc1m1p0zwsllpp5np23cxgafxcqnk434v86rlnpght09gvnzwtrvy0y704nqtjtffvqdqdgdf4wgztv4uhxcqzpg3awyquek08frfexrphkm9sjwdggkfepm6uxex0lg4m8s0s59d7z8kdf9cajvc00cwl2nzu57qe9n92fv2mzm4hlgctw2x3v0lxcjrrcpul9wen",
    refundAddress: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
};

const quote = await client.requestQuote(quoteRequest);

console.log(quote);

// {
//   orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
//   expiryTimestampMs: 1578598212267;
//   amount: "0.001056000000000000";
//   details: {
//     payToAddress: "3LKomc2i3rLm2TnA36U4pGH25cFWvRMnJB";
//     redeemScript: "76a914d5846ccb08521347c1d5718ec460656d67427cbf8763752102369b4d174f601239daef6a83bf553092e139901e6ed19ffbcbedcee07be7a4ae6703575709b17576a914c1e27ac884310271f04dd1ebe9eb4e135113a1d08868ac";
//     refundableAtBlockHeight: 612183;
//   }
// }

JavaScript Example

import io from "socket.io-client";

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
    market: "BTC_LBTC",
    invoice: "lnbc1m1p0pv6fepp5kjf5zgm6590w77u3qtg38cjwxwz36l505q3gurl4nl8xw47t33msdqsgdf4wfmnyp9k27tncqzpgwrdthp4apgu7v4s53xc27clm82nkchmylm5huvwdd660q36e82vske04eeesljjyt89q3aglzr9l7l3yxpy5pwfl08unztfrqhcndesqyym288",
    refundAddress: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
};

socket.emit(
  "requestQuote",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    console.log("Successful:", success, "Response Message:", message);
  },
);

Other Language Clients:

Events

Websocket information to communicate with REDSHIFT.

Messages:

requestQuote

Use this endpoint to request a quote to exchange an on-chain asset for Lightning Bitcoin (LBTC). Available markets are in docs.

// Request
{
    market: Market;
    invoice: string;
    refundAddress?: string;
}

// Bitcoin Response
{
    success: boolean,
    message: {
        orderId: string;
        expiryTimestampMs: number;
        amount: string;
        details: {
            payToAddress: string;
            redeemScript: string;
            refundableAtBlockHeight: number;
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        orderId: string,
        expiryTimestampMs: number,
        amount: string,
        details: {
          unsignedFundingTx: string,
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  market: "BTC_LBTC";
  invoice: "lnbc1m1p0pv6fepp5kjf5zgm6590w77u3qtg38cjwxwz36l505q3gurl4nl8xw47t33msdqsgdf4wfmnyp9k27tncqzpgwrdthp4apgu7v4s53xc27clm82nkchmylm5huvwdd660q36e82vske04eeesljjyt89q3aglzr9l7l3yxpy5pwfl08unztfrqhcndesqyym288";
  refundAddress: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
}

socket.emit(
  "requestQuote",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
      // {
      //   orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
      //   expiryTimestampMs: 1578598212267;
      //   amount: "0.001056000000000000";
      //   details: {
      //     payToAddress: "3LKomc2i3rLm2TnA36U4pGH25cFWvRMnJB";
      //     redeemScript: "76a914d5846ccb08521347c1d5718ec460656d67427cbf8763752102369b4d174f601239daef6a83bf553092e139901e6ed19ffbcbedcee07be7a4ae6703575709b17576a914c1e27ac884310271f04dd1ebe9eb4e135113a1d08868ac";
      //     refundableAtBlockHeight: 612183;
      //   }
      // }
    }
    return reject(new Error(message));
  },
);

subscribeToOrderState

Use this endpoint to subscribe to an order's state. If an order's state changes, subscribers will be sent a message with the new state of the order. This may be useful to notify users how their order is progressing.

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "subscribeToOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromOrderState

Use this endpoint to unsubscribe from an order's state. If an order's state changes in the future, the client will not be notified.

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "unsubscribeFromOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Unsubscribed!");
    }
    return reject(new Error(message));
  },
);

subscribeToBlockHeight

Use this endpoint to subscribe to a blockchain's current block height. If the blockchain's current block height changes, subscribers will be sent a message with the new block height. This might be useful to notify users whether they can refund their transaction.

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "subscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromBlockHeight

Use this endpoint to unsubscribe from a blockchain's current block height. If the blockchain's current block height changes in the future, the client will not be notified.

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "unsubscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

requestRefundDetails

Use this endpoint to request the refund details for a particular order. This information can also be retrieved using the requestRefundDetails HTTP endpoint, but it may make more sense to use an already established WebSocket connection depending on your application.

// Request
{
    orderId: string
}

// Bitcoin Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            refundAddress: string;
            redeemScript: string;
            currentBlockHeight: number;
            feeTokensPerVirtualByte: number;
            utxos: TxOutput[];
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            to: string;
            data: string;
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
}

socket.emit(
  "requestRefundDetails",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   state: "Completed";
        //   blocksRemaining: 0;
        //   refundableAtBlockHeight: 607878;
        //   refundableBalance: "0.0005263";
        //   details: {
        //     refundAddress: "bc1q50qmmgf3mtp95qesqq27h8gsdx9syuzv9p8qfa";
        //     redeemScript: "76a9148ec7c524f0cfca47daaa56827c76d94e0ea47c2c8763752103698deb28d5807611b0545b2c0b59ea4ae84393b2e22b7f131f1b89694b43749a6703864609b17576a914a3c1bda131dac25a03300015eb9d10698b02704c8868ac";
        //     currentBlockHeight: 612073;
        //     feeTokensPerVirtualByte: 30;
        //     utxos: [
        //       {
        //         "txId": "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        //         "index": 1,
        //         "tokens": 52630
        //       }
        //     ];
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);

broadcastTransaction

Use this endpoint broadcasts a signed transaction to the specific network. This can be used to broadcast refund transactions directly from your app without needing to run a node.

Valid onchainTickers are defined in the docs.

// Request
{
    onchainTicker: OnChainTicker;
    signedTxHex: string;
}

// Response
{
    success: boolean,
    message: {
        txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678"
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  onchainTicker: "BTC",
  signedTxHex: "8adb7454fe7d8d0f55ee89c592926d6f6f032207020e4ad56ff7ca3c80cbe26e"
}

socket.emit(
  "broadcastTransaction",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        // }
        
    }
    return reject(new Error(message));
  },
);

requestMarketRequirements

Use this endpoint to get the market requirements.

N/A

// Response
{
    market: Market;
    payReq: {
        minExpirationSeconds: string;
        minBaseUnits: string;
        maxBaseUnits: string;
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = { }

socket.emit(
  "requestMarketRequirements",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   payReq:{
        //     minExpirationSeconds:"2400",
        //     minBaseUnits:"30000",
        //     maxBaseUnits:"1000000"
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);

Events

Websocket information to communicate with REDSHIFT.

Messages:

requestQuote

Use this endpoint to request a quote to exchange an on-chain asset for Lightning Bitcoin (LBTC). Available markets are in docs.

// Request
{
    market: Market;
    invoice: string;
    refundAddress?: string;
}

// Bitcoin Response
{
    success: boolean,
    message: {
        orderId: string;
        expiryTimestampMs: number;
        amount: string;
        details: {
            payToAddress: string;
            redeemScript: string;
            refundableAtBlockHeight: number;
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        orderId: string,
        expiryTimestampMs: number,
        amount: string,
        details: {
          unsignedFundingTx: string,
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  market: "BTC_LBTC";
  invoice: "lnbc1m1p0pv6fepp5kjf5zgm6590w77u3qtg38cjwxwz36l505q3gurl4nl8xw47t33msdqsgdf4wfmnyp9k27tncqzpgwrdthp4apgu7v4s53xc27clm82nkchmylm5huvwdd660q36e82vske04eeesljjyt89q3aglzr9l7l3yxpy5pwfl08unztfrqhcndesqyym288";
  refundAddress: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa";
}

socket.emit(
  "requestQuote",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
      // {
      //   orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
      //   expiryTimestampMs: 1578598212267;
      //   amount: "0.001056000000000000";
      //   details: {
      //     payToAddress: "3LKomc2i3rLm2TnA36U4pGH25cFWvRMnJB";
      //     redeemScript: "76a914d5846ccb08521347c1d5718ec460656d67427cbf8763752102369b4d174f601239daef6a83bf553092e139901e6ed19ffbcbedcee07be7a4ae6703575709b17576a914c1e27ac884310271f04dd1ebe9eb4e135113a1d08868ac";
      //     refundableAtBlockHeight: 612183;
      //   }
      // }
    }
    return reject(new Error(message));
  },
);

subscribeToOrderState

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "subscribeToOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromOrderState

Use this endpoint to unsubscribe from an order's state. If an order's state changes in the future, the client will not be notified.

// Request
{
    orderId: string
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e"
}

socket.emit(
  "unsubscribeFromOrderState",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Unsubscribed!");
    }
    return reject(new Error(message));
  },
);

subscribeToBlockHeight

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "subscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

unsubscribeFromBlockHeight

Use this endpoint to unsubscribe from a blockchain's current block height. If the blockchain's current block height changes in the future, the client will not be notified.

Valid Networks:

bitcoin
ethereum

Valid Subnets:

Bitcoin:

simnet
testnet
mainnet

Ethereum:

ganache_simnet
kovan_testnet
mainnet

// Request
{
    network: Network;
    subnet: Subnet;
}

// Response
{  
    success: boolean 
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  network: "bitcoin";
  subnet: "mainnet";
}

socket.emit(
  "unsubscribeToBlockHeight",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      return resolve("Subscribed!");
    }
    return reject(new Error(message));
  },
);

requestRefundDetails

// Request
{
    orderId: string
}

// Bitcoin Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            refundAddress: string;
            redeemScript: string;
            currentBlockHeight: number;
            feeTokensPerVirtualByte: number;
            utxos: TxOutput[];
        }
    }
}


// Ethereum Response
{
    success: boolean,
    message: {
        market: Market;
        state: UserSwapState;
        blocksRemaining: number | undefined;
        refundableAtBlockHeight: number | undefined;
        refundableBalance: string;
        details: {
            to: string;
            data: string;
        }
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  orderId: "13283979-2c0b-45e4-b2e0-2a487535822e";
}

socket.emit(
  "requestRefundDetails",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   state: "Completed";
        //   blocksRemaining: 0;
        //   refundableAtBlockHeight: 607878;
        //   refundableBalance: "0.0005263";
        //   details: {
        //     refundAddress: "bc1q50qmmgf3mtp95qesqq27h8gsdx9syuzv9p8qfa";
        //     redeemScript: "76a9148ec7c524f0cfca47daaa56827c76d94e0ea47c2c8763752103698deb28d5807611b0545b2c0b59ea4ae84393b2e22b7f131f1b89694b43749a6703864609b17576a914a3c1bda131dac25a03300015eb9d10698b02704c8868ac";
        //     currentBlockHeight: 612073;
        //     feeTokensPerVirtualByte: 30;
        //     utxos: [
        //       {
        //         "txId": "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        //         "index": 1,
        //         "tokens": 52630
        //       }
        //     ];
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);

broadcastTransaction

Use this endpoint broadcasts a signed transaction to the specific network. This can be used to broadcast refund transactions directly from your app without needing to run a node.

Valid onchainTickers are defined in the docs.

// Request
{
    onchainTicker: OnChainTicker;
    signedTxHex: string;
}

// Response
{
    success: boolean,
    message: {
        txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678"
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = {
  onchainTicker: "BTC",
  signedTxHex: "8adb7454fe7d8d0f55ee89c592926d6f6f032207020e4ad56ff7ca3c80cbe26e"
}

socket.emit(
  "broadcastTransaction",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   txId: "d2a153c4024152a06cb1ee6e5da1fac3548085ed77dc75f438586c37fed26678",
        // }
        
    }
    return reject(new Error(message));
  },
);

requestMarketRequirements

Use this endpoint to get the market requirements.

N/A

// Response
{
    market: Market;
    payReq: {
        minExpirationSeconds: string;
        minBaseUnits: string;
        maxBaseUnits: string;
    }
}

import io from 'socket.io-client';

const socket = io.connect("https://api.redshift.radar.tech/user/v1");

const request = { }

socket.emit(
  "requestMarketRequirements",
  request,
  ({ success, message }: WebSocketResponse<Quote | string>) => {
    if (success) {
      console.log(message)
        // {
        //   market: "BTC_LBTC";
        //   payReq:{
        //     minExpirationSeconds:"2400",
        //     minBaseUnits:"30000",
        //     maxBaseUnits:"1000000"
        //   }
        // }
        
    }
    return reject(new Error(message));
  },
);