open-index/open-npm huggingface dataset:
npm package: @pingpay/onramp-sdk
Description: The Onramp SDK provides the core functionality for integrating Pingpay Onramp into any web application. It exposes the `PingpayOnramp` class, which manages the entire onramp flow through a popup window.
Latest version: 0.2.0

# @pingpay/onramp-sdk

The Onramp SDK provides the core functionality for integrating Pingpay Onramp into any web application. It exposes the `PingpayOnramp` class, which manages the entire onramp flow through a popup window.

## Core Concepts

- **`PingpayOnramp` Class**: The main entry point for the SDK. It handles the creation and management of the onramp popup.
- **`initiateOnramp` Method**: Starts the onramp process, opening a popup window and returning a promise that resolves with the onramp result.
- **Lifecycle Events**: Optional callbacks (`onPopupReady`, `onPopupClose`) allow developers to hook into the onramp lifecycle.
- **Communication**: The SDK uses `postMessage` to establish a secure communication channel with the popup window for exchanging messages and data.

## Installation

```bash
npm install @pingpay/onramp-sdk
```

## Quick Start

```typescript
import { PingpayOnramp } from "@pingpay/onramp-sdk";

const onramp = new PingpayOnramp({
  onPopupReady: () => console.log("Popup is ready"),
  onPopupClose: () => console.log("Popup was closed"),
});

try {
  const result = await onramp.initiateOnramp({ chain: "NEAR", asset: "wNEAR" });
  console.log("Onramp successful:", result);
} catch (error) {
  console.error("Onramp failed:", error);
}
```

## Configuration

The `PingpayOnrampConfig` object accepts the following options:

| Option | Type | Description |
|--------|------|-------------|
| `appFees` | `OneClickFee[]` | Optional fees to be applied to the onramp transaction. Each fee specifies a `recipient` address and a `fee` amount in basis points. |
| `destinationAddress` | `string` | Optional pre-filled destination wallet address. When set, the address field in the popup is read-only and non-editable by the end user. |
| `popupUrl` | `string` | Override the popup URL. Useful for local development and testing. |
| `onPopupReady` | `() => void` | Callback invoked when the popup window signals it's ready. |
| `onPopupClose` | `() => void` | Callback invoked when the popup window is closed. |

## App Fees

You can charge fees on each onramp transaction by passing `appFees`:

```typescript
const onramp = new PingpayOnramp({
  appFees: [
    { recipient: "fees.yourapp.near", fee: 50 }, // 50 basis points = 0.5%
  ],
});
```

## Destination Address

Pre-fill and lock the recipient wallet address so end users cannot change it. This is useful for apps that manage wallets on behalf of users:

```typescript
const onramp = new PingpayOnramp({
  destinationAddress: "alice.near",
});

await onramp.initiateOnramp({ chain: "NEAR", asset: "wNEAR" });
// The popup will show "alice.near" as a read-only field
```

## Cleanup

Call `close()` to shut down the popup and release resources:

```typescript
onramp.close();
```

After calling `close()`, the instance cannot be reused — create a new `PingpayOnramp` instance instead.