Herald Exchange Onramp SDK Widget

Herald Exchange Onramp SDK is a simple component for React applications.

Installation

You can install Herald Exchange Onramp SDK via npm:

npm install heraldex-onramp-sdk
# or
yarn add heraldex-onramp-sdk

Usage

To use widget in your React application, follow these steps:

import { BuyCryptoWidget } from "heraldex-onramp-sdk";

Initialize the widget:

To Generate API Key Please Visit : Herald Exchange.
Supported Token Types : ["USDT", "USDC", "ETH", "BNB", "MATIC", "SOL", "TRX"] Supported Fiat Types : ["USD", "EUR"]

<BuyCryptoWidget
  mode={"development" | "production"}
  apiKey={YOUR_API_KEY}
  clientReferenceID={YOUR_SALT_KEY}
  buyParameters={{
    from_amount: "25",
    token_type: "USDC",
    fiat: "USD",
  }}
  redirect={false | true}
  redirectUrl={REDIRECT_URL}
  callback={(data) => alert(JSON.stringify(data))}
/>

mode (required)

• Type: development | production

• Description:

• development → Runs the widget on testnet

• production → Runs the widget on mainnet

Note:

• In development mode, the widget operates on testnet and runs in a sandbox environment.
• Transactions are simulated based on the fromAmount value:
  • 100 → Success
  • 200 → Failure
  • Any other value → Initiated
• ⚠️ Ensure your application is deployed in a production environment when going live to enable accurate transaction tracking and wallet interactions.

🔧 Props

apiKey (required)

• Type: string

• Description: A unique API key generated via the Herald Exchange App.

• This key is used to authenticate and authorize the widget.

• Example: 4bb06e2fdbfb8e392a0ab49e4d9819.ae072dcef82d79af7893625a5ff1416f

clientReferenceID (required)

• Type: string

• Description: A unique identifier (UUID) generated via the Herald Exchange App, used to associate a transaction with a specific user or session.

• Helps track user activity and transaction flow.

• Example: 34edd6d6eb12422fbd0e63c5733527

buyParameters (required)

• Type:

{
  from_amount: string;
  token_type: string;
}

• Description: Defines the default configuration for the buy flow.

  • from_amount: A string representing the default amount to be displayed in the input field (e.g., "25").

  • token_type: The token that should be selected by default for purchase (e.g., "USDC").

⚠️ If the passed token_type is not active, the widget will automatically fall back to the first activated token.

callback (required)

• Type:

(data: {
  status: string;
  message?: string;
  transaction_id?: string;
  [key: string]: any;
}) => void

• Description: A callback function that is triggered whenever the widget returns a response or status update.

  status: Represents the current state of the action (e.g., "success", "failed", "pending"). message: Optional message returned from the widget response. transaction_id: Optional unique transaction identifier. Additional response fields may be included depending on the event type.

redirect (optinal)

• Type: boolean

• Description: Determines whether redirection should be enabled after the action is completed.

• Example: false | true

redirectUrl (optional)

• Type: string

• Description: The URL to which the user will be redirected after completing the transaction.

• A callback will be made to this URL along with the transaction result or status as query parameters or payload (depending on the integration).

• Example: https://yourapp.com/transaction-complete

License

This project is licensed under the MIT License - see the LICENSE file for details.