Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@coinbase/cbpay-js

coinbase23.1kMIT2.4.0TypeScript support: included

The Coinbase Onramp JS SDK contains helper methods to simplify integrating with our fiat onramp. Wallet providers and dapps can leverage Coinbase Onramp and let their users top up their self-custody wallets.

readme

@coinbase/cbpay-js

The Coinbase Onramp JS SDK contains helper methods to simplify integrating with our fiat onramp. Wallet providers and dapps can leverage Coinbase Onramp and let their users top up their self-custody wallets.

Documentation

See the Coinbase Onramp documentation for instructions on how to onboard to Coinbase Onramp and get started.

Installation

With yarn:

yarn add @coinbase/cbpay-js

With npm:

npm install @coinbase/cbpay-js

The package is distributed as both ESModules and CommonJS. To use the CommonJS output, the regenerator-runtime package will also need to be installed:

With yarn:

yarn add regenerator-runtime

With npm:

npm install regenerator-runtime

Basic example

import { initOnRamp } from '@coinbase/cbpay-js';

const options = {
  appId: '<Your Project ID obtained from Coinbase Developer Platform>',
  widgetParameters: {
    // Specify the addresses and which networks they support
    addresses: { '0x0': ['ethereum','base'], 'bc1': ['bitcoin']},
    // Filter the available assets on the above networks to just these ones
    assets: ['ETH','USDC','BTC'],
  },
  onSuccess: () => {
    console.log('success');
  },
  onExit: () => {
    console.log('exit');
  },
  onEvent: (event) => {
    console.log('event', event);
  },
  experienceLoggedIn: 'popup',
  experienceLoggedOut: 'popup',
  closeOnExit: true,
  closeOnSuccess: true,
};

// Initialize the CB Pay instance
let onrampInstance;
initOnRamp(options, (error, instance) => {
  onrampInstance = instance;
});

// Open the widget when the user clicks a button
onrampInstance.open();

React example

import { CBPayInstanceType, initOnRamp } from "@coinbase/cbpay-js";
import { useEffect, useState } from "react";

export const PayWithCoinbaseButton: React.FC = () => {
  const [onrampInstance, setOnrampInstance] = useState<CBPayInstanceType | null>();

  useEffect(() => {
    initOnRamp({
      appId: '<Your Project ID obtained from Coinbase Developer Platform>',
      widgetParameters: {
        // Specify the addresses and which networks they support
        addresses: { '0x0': ['ethereum','base'], 'bc1': ['bitcoin']},
        // Filter the available assets on the above networks to just these ones
        assets: ['ETH','USDC','BTC'],
      },
      onSuccess: () => {
        console.log('success');
      },
      onExit: () => {
        console.log('exit');
      },
      onEvent: (event) => {
        console.log('event', event);
      },
      experienceLoggedIn: 'popup',
      experienceLoggedOut: 'popup',
      closeOnExit: true,
      closeOnSuccess: true,
    }, (_, instance) => {
      setOnrampInstance(instance);
    });

    // When button unmounts destroy the instance
    return () => {
      onrampInstance?.destroy();
    };
  }, []);

  const handleClick = () => {
    onrampInstance?.open();
  };

  return <button onClick={handleClick} disabled={!onrampInstance}>Buy with Coinbase</button>;
};

React-Native example

Prerequisites

yarn add react-native-url-polyfill
import React, { useMemo } from 'react'
import { WebView } from 'react-native-webview'
import { generateOnRampURL } from '@coinbase/cbpay-js'
import 'react-native-url-polyfill/auto'

const CoinbaseWebView = ({ currentAmount }) => {
  const coinbaseURL = useMemo(() => {
    const options = {
      appId: '<Your Project ID obtained from Coinbase Developer Platform>',
      // Specify the addresses and which networks they support
      addresses: { '0x0': ['ethereum','base'], 'bc1': ['bitcoin']},
      // Filter the available assets on the above networks to just these ones
      assets: ['ETH','USDC','BTC'],
      handlingRequestedUrls: true,
      presetCryptoAmount: currentAmount,
    }

    return generateOnRampURL(options)
  }, [currentAmount, destinationAddress])

  const onMessage = useCallback((event) => {
    // Check for Success and Error Messages here
    console.log('onMessage', event.nativeEvent.data)
    try {
      const { data } = JSON.parse(event.nativeEvent.data);
      if (data.eventName === 'request_open_url') {
        viewUrlInSecondWebview(data.url);
      }
    } catch (error) {
      console.error(error);
    }
  }, [])

  return (
    <WebView source={{ uri: coinbaseURL }} onMessage={onMessage} />
  )
}

export default CoinbaseWebView

Aggregator Example

Review the Coinbase Developer docs for how to produce the parameters for use within an on ramp aggregator.

import { CBPayInstanceType, initOnRamp } from "@coinbase/cbpay-js";
import { useEffect, useState } from "react";

export const PayWithCoinbaseButton: React.FC = () => {
  const [onrampInstance, setOnrampInstance] = useState<CBPayInstanceType | null>();

  useEffect(() => {
    initOnRamp({
      appId: '<Your Project ID obtained from Coinbase Developer Platform>',
      widgetParameters: {
        // Specify the addresses and which networks they support
        addresses: { '0x0': ['ethereum','base'], 'bc1': ['bitcoin']},
        // Filter the available assets on the above networks to just these ones
        assets: ['ETH','USDC','BTC'],
        // Aggregator params are ignored unless they are all provided.
        // defaultNetwork is the exception - it's optional.
        quoteId: '<quote_id from the Buy Quote API>',
        defaultAsset: 'USDC',
        defaultNetwork: 'base',
        defaultPaymentMethod: 'CARD',
        presetFiatAmount: 20,
        fiatCurrency: 'USD',
      },
      onSuccess: () => {
        console.log('success');
      },
      onExit: () => {
        console.log('exit');
      },
      onEvent: (event) => {
        console.log('event', event);
      },
      experienceLoggedIn: 'popup',
      experienceLoggedOut: 'popup',
      closeOnExit: true,
      closeOnSuccess: true,
    }, (_, instance) => {
      setOnrampInstance(instance);
    });

    // When button unmounts destroy the instance
    return () => {
      onrampInstance?.destroy();
    };
  }, []);

  const handleClick = () => {
    onrampInstance?.open();
  };

  return <button onClick={handleClick} disabled={!onrampInstance}>Buy with Coinbase</button>;
};

Contributing

Commit signing is required for contributing to this repo. For details, see the docs on contributing and commit-signing.

changelog

Changelog

All notable changes to this project will be documented in this file.

[2.4.0] - 2024-11-08

  • Add disableEdit offramp parameter

[2.3.0] - 2024-10-21

  • Add Offramp support with generateOffRampURL and initOffRamp functions

[2.2.1] - 2024-08-01

  • Added redirectUrl widget parameter

[2.2.0] - 2024-06-11

  • Added new addresses and assets initialization parameters to simplify destinationWallets
  • Marked the destinationWallets initialization parameter as deprecated
  • Added warning message about upcoming deprecation of the embedded experience
  • Simplified the CoinbasePixel class to improve widget initialization latency
  • Fix example code in README

[2.1.0] - 2024-03-14

  • Add theme parameter

[2.0.0] - 2024-01-25

  • [BREAKING CHANGE] Rename onrampToken parameter to sessionToken

[1.10.0] - 2024-01-11

  • Add onrampToken parameter

[1.9.0] - 2023-11-07

  • Add partnerUserId parameter

[1.8.0] - 2023-10-12

  • Add support for Aggregator API parameters
  • Remove old SupportedBlockchains type
    • Hard coding this list into the SDK wasn't ideal
    • We support the expected set of assets + networks
    • We're adding an endpoint which lists the currently supported assets + networks.

[1.7.0] - 2023-05-05

  • Add defaultExperience parameter
  • Add handlingRequestedUrls parameter and associated request_open_url event
  • Add support for several blockchains

[1.6.0] - 2022-09-13

  • Move internal exports to main export file.

[1.5.0] - 2022-09-13

  • Update package.json exports format.
  • Improvements to pixel error handling.

[1.4.0] - 2022-09-06

  • Update exports for core logic.

[1.3.0] - 2022-08-25

  • Fix invalid CommonJS output.
  • Fix passing generateOnRampURL experience options.
  • Update npm package files.
  • Deprecate onReady parameter.
  • Implement synchronous open function.

Migration support for initOnRamp

See the updated examples in the README.md. The onReady function has been updated to be a callback provided as the second argument in initOnRamp. This is to avoid race conditions which results in the widget failing to open in some cases.

[1.2.0] - 2022-08-19

  • Improve pixel internal state and message management.
  • Implement fallback open functionality for initOnRamp.
  • Add debug option for initOnRamp.

[1.1.0] - 2022-08-17

  • Add parameters to add options for L2 destination wallet configs.
  • Update generateOnRampURL formatting.
  • Remove the typing for blockchains parameter.
  • Add flow as supported network.

[1.0.2] - 2022-06-30

  • Add preset amount parameters support.
  • Export init option types.
  • Update generateOnRampURL options.

[1.0.1] - 2022-05-19

  • Add additional network support.
  • Upgrade tsup.
  • Update readme.md with examples and documentation.

[1.0.0] - 2022-04-21

  • First release with initOnRamp and generateOnRampURL functions.