Helio SDK

Introduction

The Helio SDK is a packaged module to make integrating Helio and our components as easy and as quickly as possible into your front end web site or store so you can start accepting Helio web3 payments.

It wraps and enhances the Helio API away into one NPM package which is easy to install and upgrade.

The Helio SDK is written in Typescript.

Please use the latest production version. Only used ALPHA versions if advised to do so.

Solana is currently supported with Polygon and ETH following soon.

Installation

yarn add @heliofi/sdk

After installing the SDK please import this into your project:

import { Helio } from "@heliofi/sdk";

Helio SDK Services

Detailed below are the methods used via the SDK to interact with the Helio API

Please ensure you select the correct 'Cluster' or network during deployment.

Properties table for the HelioSDK

| Methods | Params | Return | Description | |:-------------------------------|:--------------------------------------------------------------|:---------------------------------------|:------------------------------------------------------------------------| | constructor | options?: { cluster: ClusterHelioType; customApiUrl: string } | void | set properties, cluster available values: devnet, mainnet, testnet | | setCluster | cluster: ClusterHelioType | void | set cluster available value | | setCustomApiUrl | customApiUrl: string | void | set custom api url | | currencyService | none | CurrencyService, never | returns object CurrencyService | | defaultCurrencyService | none | DefaultCurrencyService, never | returns object DefaultCurrencyService | | apiService | none | HelioApiConnector, never | returns object HelioApiAdapter | | solExplorerService | none | SolExplorerService, never | returns object SolExplorerService | | polygonExplorerService | none | PolygonExplorerService, never | returns object PolygonExplorerService | | ethExplorerService | none | EthereumExplorerService, never | returns object EthereumExplorerService | | tokenConversionService | none | TokenConversionService, never | returns object TokenConversionService | | paylinkService | none | PaylinkSubmitService, never | returns object PaylinkSubmitService | | polygonPaylinkService | none | PolygonPaylinkSubmitService, never | returns object PolygonPaylinkSubmitService | | ethPaylinkService | none | EthPaylinkSubmitService, never | returns object EthPaylinkSubmitService | | paystreamStartService | none | PaystreamStartService, never | returns object PaystreamStartService | | paystreamCancelService | none | PaystreamCancelService, never | returns object PaystreamCancelService | | configService | none | ConfigService, never | returns object ConfigService | | solAvailableBalanceService | none | SolAvailableBalanceService, never | returns object SolAvailableBalanceService | | ethAvailableBalanceService | none | EthereumAvailableBalanceService, never | returns object EthereumAvailableBalanceService | | polygonAvailableBalanceService | none | PolygonAvailableBalanceService, never | returns object PolygonAvailableBalanceService | | availableBalanceService | none | AvailableBalanceService, never | returns object AvailableBalanceService |

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

Methods

Properties table for the CurrencyService

| Methods | Params | Return | Description | |:----------------------------------|:--------------------------------------------------------|:---------------------------|:----------------------------------------| | getCurrencies | none | Promise<Currency[]> | if currencies are empty adds currencies | | getCurrencyBySymbol | symbol: string | Currency, undefined, never | get currency by symbol (e.g. "SOl") | | getCurrencyByMint | mint: string | Currency, never | get currency by mint address | | getCurrencyByMintOptional | mint: string | Currency, undefined | get currency by mint address | | getCurrencyBySymbolAndBlockchain | { symbol: string; blockchain?: BlockchainSymbol; } | Currency, undefined, never | get currency by symbol and blockchain | | getCurrenciesByTypeAndBlockchain | { type: CurrencyType; blockchain?: BlockchainSymbol; } | Currency[] | get currency by type and blockchain |

import { BlockchainSymbol, Currency, CurrencyType } from '@heliofi/common';

Properties table for the DefaultCurrencyService

| Methods | Params | Return | Description | |:--------------------------------------|:-------------------|:------------------|:----------------------------------| | getNativeCurrencyByBlockchainToSymbol | blockchain: string | string, undefined | get native currency by blockchain | | getSolCurrencySymbol | none | string | get sol native currency | | getMaticCurrencySymbol | none | string | get matic native currency | | getEthCurrencySymbol | none | string | get eth native currency | | getDefaultCurrencySymbol | none | string | get usdc native currency |

Properties table for the SolAvailableBalanceService

| Methods | Params | Return | Description | |:---------------------|:----------------------------------------------|:------------------------------------|:----------------------------| | getAvailableBalance | publicKey: PublicKey, connection: Connection | Promise<AvailableBalance[]> | get available balance list |

import { Connection, PublicKey } from '@solana/web3.js';

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the EthereumAvailableBalanceService

| Methods | Params | Return | Description | |:---------------------|:-------------------------|:----------------------------------|:----------------------------| | getAvailableBalance | publicKey: EVMPublicKey | Promise<AvailableBalance[]> | get available balance list |

type EVMPublicKey = `0x${string}`;

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the PolygonAvailableBalanceService

| Methods | Params | Return | Description | |:---------------------|:-------------------------|:----------------------------------|:----------------------------| | getAvailableBalance | publicKey: EVMPublicKey | Promise<AvailableBalance[]> | get available balance list |

type EVMPublicKey = `0x${string}`;

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the AvailableBalanceService

| Methods | Params | Return | Description | |:----------------------|:------------------------------------------------------------------------|:----------------------|:-----------------------| | fetchAvailableBalance | { props: AvailableBalanceServiceProps } | Promise<number> | get available balance | | isBalanceEnough | { isTokenSwapped: boolean; quantity?: number; decimalAmount: number; } | boolean | get is balance enough |

import { Connection, PublicKey } from '@solana/web3.js';
import { BlockchainSymbol, Currency } from '@heliofi/common';

type EVMPublicKey = `0x${string}`;

interface TokenSwapQuote {
    paymentRequestId: string;
    routeTokenString: string;
    from: Currency;
    to: Currency;
    slippageBps: number;
    priceImpactPct: number;
    inAmount: number;
    outAmount: number;
    amount: number;
}

interface AvailableBalanceServiceProps {
    publicKey?: PublicKey;
    connection?: Connection;
    evmPublicKey?: EVMPublicKey;
    decimalAmount: number;
    currency?: string;
    canSwapTokens?: boolean;
    swapCurrency?: string;
    quantity?: number;
    tokenSwapQuote?: TokenSwapQuote;
    blockchain?: BlockchainSymbol;
    areCurrenciesDefined: boolean;
}

Properties table for the EthereumExplorerService

| Methods | Params | Return | Description | |:----------------------------------|:----------------------|:--------|:--------------------------------------| | getEthereumExplorerUrlByCluster | none | string | get ethereum url | | getEthereumExplorerTransactionURL | transactionID: string | string | get ethereum explorer transaction url | | getEthereumExplorerAddressURL | address: string | string | get ethereum explorer address url |

Properties table for the PolygonExplorerService

| Methods | Params | Return | Description | |:---------------------------------|:----------------------|:--------|:-------------------------------------| | getPolygonExplorerUrlByCluster | none | string | get polygon url | | getPolygonExplorerTransactionURL | transactionID: string | string | get polygon explorer transaction url | | getPolygonExplorerAddressURL | address: string | string | get polygon explorer address url |

Properties table for the HelioApiAdapter

| Methods | Params | Return | Description | |:----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------|:-----------------------------------------------------| | findAddress | query: string, country_code: string | Promise<FetchifyFindAddress> | get addresses list by area code and country code | | retrieveAddress | address_id: string, country_code: string | Promise<FetchifyRetrieveAddress> | get address more info by address id and country code | | getCurrencies | none | Promise<Currency[]> | get currencies list | | getPaymentRequestByIdPublic | id: string, paymentType: PaymentRequestType | Promise<PaymentRequest> | get payment data by req. id and payment type | | getTokenSwapMintAddresses | mintAddress: string | Promise<string[]> | get mint addresses list | | getTokenSwapQuote | paymentRequestId: string, paymentRequestType: PaymentRequestType, fromMint: string, quantity?: number, normalizedPrice?: number, toMint?: string | Promise<SwapRouteToken> | get route token for swap | | getLivePrice | amount: number, to: string, from: string, paymentRequestId?: string, paymentRequestType?: string | Promise<TokenQuoting> | get converted data | | getPreparedTransactionMessage | url: string, body: string | Promise<PrepareTransaction> | prepare transaction to send | | getPreparedTransactionSwapMessage | url: string, body: string | Promise<PrepareSwapTransaction> | prepare transaction to send for swap case | | getTransactionStatus | statusToken: string, endpoint:string = '/transaction/status' | Promise<OnlyContentAndTransactionPaylink> | get transaction status |

import {
    FetchifyFindAddress,
    PaymentRequest,
    PaymentRequestType,
    FetchifyRetrieveAddress,
    Currency,
    PrepareTransaction,
    PrepareSwapTransaction,
    TokenQuoting,
    SwapRouteToken,
    PaymentRequestType,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';

Properties table for the SolExplorerService

| Methods | Params | Return | Description | |:---------------------------------|:-----------------------|:--------|:----------------------------------| | getSolanaExplorerTransactionURL | transactionID: string | string | get transaction URL by after pay |

Properties table for the TokenConversionService

| Methods | Params | Return | Description | |:----------------------------|:---------------------------------------------------------------------|:--------|:---------------------------------------| | convertFromMinimalUnits | symbol: string, minimalAmount: bigint, blockchain?: BlockchainSymbol | number | convert from minimal amount | | convertToMinimalUnits | symbol?: any actualAmount?: number | number | convert to minimal amount | | formatPrice | currency: Currency, normalizedAmount: number | string | format price | | convertFromMinimalAndRound | symbol: string, minimalAmount: bigint | string | convert from minimal amount and round |

import { BlockchainSymbol, Currency } from '@heliofi/common';

Properties table for the PaylinkSubmitService

| Methods | Params | Return | Description | |:-------------------|:-------------------------------|:---------------------|:---------------------------------------------------------| | handleTransaction | { props: CreatePaymentProps } | Promise<void> | prepare transaction, connect to wallet, send transaction |

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';
import {
    OnlyContentAndSwapTransactionPaylink,
    OnlyContentAndTransactionPaylink,
    CustomerDetails,
    SplitWallet,
} from '@heliofi/common';

type ApproveTransactionResponse = OnlyContentAndTransactionPaylink | OnlyContentAndSwapTransactionPaylink;

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

interface BasePaymentProps<ApproveTransactionResponse> {
    onSuccess: (event: SuccessPaymentEvent<ApproveTransactionResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CreatePaymentProps
    extends BasePaymentProps<ApproveTransactionResponse> {
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    customerDetails?: CustomerDetails;
    quantity?: number;
    productDetails?: {
        name?: string;
        value?: string;
    };
    splitRevenue?: boolean;
    splitWallets?: SplitWallet[];
    wallet: AnchorWallet;
    connection: Connection;
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    rateToken?: string;
}

Properties table for the PolygonPaylinkSubmitService, EthPaylinkSubmitService

| Methods | Params | Return | Description | |:-------------------|:------------------------------|:---------------------|:----------------------------------------------------------| | handleTransaction | { props: CreatePaymentProps } | Promise<void> | prepare transaction, connect to wallet, send transaction |

import {
    BlockchainSymbol,
    CustomerDetails,
    ProductDetails,
    SplitWallet,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';
import { Web3Provider } from '@ethersproject/providers';

enum LoadingModalStep {
    GET_PERMISSION = 'GET_PERMISSION',
    SIGN_TRANSACTION = 'SIGN_TRANSACTION',
    SUBMIT_TRANSACTION = 'SUBMIT_TRANSACTION',
    DEFAULT = 'DEFAULT',
    CLOSE = 'CLOSE',
}

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

ApproveTransactionResponse = OnlyContentAndTransactionPaylink;

interface SuccessPaymentEvent<ApproveTransactionResponse> extends PaymentEvent {
    data: ApproveTransactionResponse;
    transaction: string;
    paymentPK?: string;
    swapTransactionSignature?: string;
}

interface BasePaymentProps<ApproveTransactionResponse> {
    onSuccess: (event: SuccessPaymentEvent<ApproveTransactionResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    onInitiated?: (event: PaymentEvent) => void;
    setLoadingModalStep: (step: LoadingModalStep) => void;
    onCancel?: () => void;
    symbol: string;
    blockchain?: BlockchainSymbol;
    anchorProvider: Web3Provider;
    rateToken?: string;
    customerDetails?: CustomerDetails;
    productDetails?: ProductDetails;
    mintAddress: string;
    isNativeMintAddress: boolean;
    cluster: ClusterHelioType;
}

interface CreatePaymentProps
    extends BasePaymentProps<ApproveTransactionResponse> {
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    quantity?: number;
    splitRevenue?: boolean;
    splitWallets?: SplitWallet[];
    discountToken?: string;
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    rateToken?: string;
}

Properties table for the PaystreamStartService

| Methods | Params | Return | Description | |:-------------------|:-------------------------------|:---------------------|:--------------------------------------------------------------------| | handleTransaction | { props: CreatePaymentProps } | Promise<void> | prepare transaction, connect to wallet, send pay stream transaction |

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';
import {
    CustomerDetails,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

interface CreatePaystreamResponse extends OnlyContentAndTransactionPaylink {} {
    document: {
        id: string;
        startedAt: bigint;
        endedAt: bigint;
    };
}

interface BasePaymentProps<CreatePaystreamResponse> {
    onSuccess: (event: SuccessPaymentEvent<CreatePaystreamResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CreatePaystreamProps
    extends BasePaymentProps<CreatePaystreamResponse> {
    interval: number;
    maxTime: number;
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    customerDetails?: CustomerDetails;
    quantity?: number;
    rateToken?: string;
    productDetails?: {
        name?: string;
        value?: string;
    };
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    swapSignedTx?: string;
}

Properties table for the PaystreamCancelService

| Methods | Params | Return | Description | |:-------------------|:-------------------------------|:---------------------|:--------------------------------------------------------------------------------| | handleTransaction | { props: CancelStreamProps } | Promise<void> | prepare transaction, connect to wallet, send pay stream for cancel transaction |

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Cluster, Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';

interface BasePaymentProps<CancelStreamResponse> {
    onSuccess: (event: SuccessPaymentEvent<CancelStreamResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CancelStreamResponse extends OnlyContentAndTransactionPaylink {}

interface CancelStreamProps extends BasePaymentProps<CancelStreamResponse> {
    paymentId: string;
}

Properties table for the ConfigService

| Methods | Params | Return | Description | |:-------------------|:--------------------------------------------|:-----------------|:-------------------------------------------| | getAssetUrl | none | string | get helio assets url | | getImageUrl | name: string | string | get helio images url | | getCluster | none | ClusterHelioType | return selected cluster | | getHelioApiBaseUrl | none | string | get Helio api base url for current cluster | | getPhantomLink | id: string, paymentType: PaymentRequestType | string | get payment url for phantom app |

import { PaymentRequestType } from '@heliofi/common';

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

Example

import { HelioSDK, ClusterHelio } from '@heliofi/sdk';
import { Cluster } from '@solana/web3.js';

const cluster = ClusterHelio.Devnet;

//create object HelioSDK
const helioSDK = new HelioSDK({ cluster });

//get curriences
const currencies = helioSDK.currencyService.getCurrencies();

//get helio asset url
const url = helioSDK.configService.getAssetUrl();

//get mint addresses list
const mintAddresses = await helioSDK.apiService.getTokenSwapMintAddresses('mint address');

//get transaction url
const transactionUrl = helioSDK.solExplorerService.getSolanaExplorerTransactionURL('transaction');

//convert to minimal amount
const amount = helioSDK.tokenConversionService.convertToMinimalUnits('symbol', 100);

//handle transaction paylink for sol blockchain
await helioSDK.paylinkService.handleTransaction({...});

//handle transaction paystream for sol blockchain
await helioSDK.paystreamStartService.handleTransaction({...});

//handle cancel transaction paystream for sol blockchain
await helioSDK.paystreamCancelService.handleTransaction({...});

//handle transaction for evm(polygon, ethereum) blockchain
await helioSDK.polygonPaylinkService.handleTransaction({...});
await helioSDK.ethPaylinkService.handleTransaction({...});