website | docs | @pingpay_io

Partner Onboarding & Requests

Use the following forms to get started or request support:

• Pingpay Partner Interest Form
• Request New Chain / Asset Support Form
• Additional Onramp Provider Onboarding Form

Usage

Installation

npm install @pingpay/onramp-sdk

Basic Usage

import type { TargetAsset, OnrampResult, PingpayOnrampError } from "@pingpay/onramp-sdk";
import { PingpayOnramp } from "@pingpay/onramp-sdk";

const onramp = new PingpayOnramp();

const targetAsset: TargetAsset = {
  chain: "NEAR",
  asset: "wNEAR",
};

async function handleOnramp() {
  try {
    const result: OnrampResult = await onramp.initiateOnramp(targetAsset);
    console.log("Onramp successful:", result);
  } catch (error) {
    if (error instanceof PingpayOnrampError) {
      console.error("Onramp failed:", error.message);
    } else {
      console.error("Onramp failed:", error);
    }
  }
}

const button = document.getElementById("onrampButton");
if (button) {
  button.addEventListener("click", handleOnramp);
}

<button id="onrampButton">Buy Crypto</button>

Advanced Usage

The SDK provides configuration options and callbacks to customize the onramp experience.

import type { PingpayOnrampConfig, OneClickFee } from "@pingpay/onramp-sdk";
import { PingpayOnramp } from "@pingpay/onramp-sdk";

// Configure app fees (example: 1% fee)
const appFees: OneClickFee[] = [
  {
    recipient: "YOUR_FEE_RECIPIENT.near",
    fee: 100, // 100 basis points = 1%
  },
];

const config: PingpayOnrampConfig = {
  targetAsset: { chain: "NEAR", asset: "wNEAR" },
  appFees,
  onPopupReady: () => {
    console.log("SDK: Popup is ready.");
  },
  onPopupClose: () => {
    console.log("SDK: Popup was closed.");
  },
};

const onramp = new PingpayOnramp(config);

async function handleOnramp() {
  try {
    const result = await onramp.initiateOnramp();
    console.log("Onramp successful:", result);
  } catch (error) {
    if (error instanceof PingpayOnrampError) {
      console.error("Onramp failed:", error.message);
    } else {
      console.error("Onramp failed:", error);
    }
  }
}

Configuration

The PingpayOnrampConfig interface supports the following options:

• targetAsset?: TargetAsset - The target asset and chain for the onramp process. If not provided, users can select from available options in the popup.
• appFees?: OneClickFee[] - Application fees to be applied to the onramp process.
• popupUrl?: string - URL to render in popup (useful for development and testing).
• onPopupReady?: () => void - Optional callback invoked when the popup window signals it's ready.
• onPopupClose?: () => void - Optional callback invoked when the popup window is closed, either by the user or programmatically.

App Fees

Configure application fees using the OneClickFee[] array:

type OneClickFee = {
  recipient: string;  // Fee recipient address
  fee: number;        // Fee in basis points (100 = 1%)
};

Error Handling

The SDK provides a dedicated PingpayOnrampError class for error handling:

try {
  const result = await onramp.initiateOnramp(targetAsset);
  // Handle success
} catch (error) {
  if (error instanceof PingpayOnrampError) {
    console.error("Onramp failed:", error.message);
    // Access additional error details if needed
    // error.details
    // error.step
  } else {
    console.error("Unexpected error:", error);
  }
}

Closing the Onramp

You can programmatically close the onramp popup and clean up resources by calling the close() method:

onramp.close();

This is useful if your application needs to interrupt the onramp flow. The onPopupClose callback will also be triggered.

Type Definitions

TargetAsset

type TargetAsset = {
  chain: string;   // Target blockchain (e.g., "NEAR")
  asset: string;   // Asset symbol (e.g., "wNEAR", "USDC")
};

OnrampResult

type OnrampResult = {
  type: "intents";
  action: "withdraw";
  depositAddress: string;
  network: string;
  asset: string;
  amount: string;
  recipient: string;
};

PingpayOnrampError

class PingpayOnrampError extends Error {
  message: string;
  details?: unknown;
  step?: string;
}

Development

To install dependencies:

bun install

To run all dev servers:

bun run dev

This uses Turborepo to orchestrate development servers across the monorepo:

• Watches for changes to the SDK (packages/sdk)
• Starts the popup dev server (apps/popup)
• Runs the API dev server (apps/api)
• Runs example apps (examples/)

Dev Server URLs:

• http://localhost:3000 - Example app (demo)
• http://localhost:3001 - Example app (sui)
• https://pingpay.local.gd:5173 - Popup app
• http://localhost:8787 - API server

Note: The demo apps can be accessed via localhost, but the popup must run on https://pingpay.local.gd:5173 for Coinbase redirects to work. Always access the popup through the example apps, not directly.

To build all packages:

bun run build

To run all tests:

bun run test