ZBD Logo

Node.js SDK for ZBD API

// Import @zbd/node library import { zbd } from '@zbd/node'; // Create ZBD instance const ZBD = new zbd(API_KEY); // Send Bitcoin payment const response = await ZBD.sendLightningAddressPayment({ amount: 50000, lnAddress: 'andre@zbd.gg', comment: 'Lightning fast!', }); // Done!

Getting Started

The Node.js library for ZBD API is available under @zbd/node. When building tools with ZBD support we encourage you to include zbd in the keywords field in package.json.

All you have to do to get started is install @zbd/node as a dependency to your Node.js-based project. You can do so using npm:

npm install @zbd/node --save

Or if you are using yarn:

yarn add @zbd/node

Now let's authenticate a specific Wallet with that ZBD Project's API Key.

Authentication

In order to authenticate your Project Wallet with the ZBD API, you will need to provide your ZBD Project's API Key to the @zbd/node SDK. You can find your Project API Key in the ZBD Developer Dashboard.

First you must import the zbd SDK client into your codebase, and then instantiate it with your Project API Key (replace YOUR_API_KEY_HERE below with your actual ZBD Project's API Key).

import { zbd } from '@zbd/node'

const ZBD = new zbd(YOUR_API_KEY_HERE)

const payment = await ZBD.sendPayment( ... )

You're all set. Now let's move some money at the speed of the internet! Check the Dev Playground or the SDK API Reference below for more information on how to use the @zbd/node SDK.

Dev Playground

The best way to get started using the @zbd/node SDK for the ZBD API is to check out our Dev Playground -- a web-based tool that allows you to test and interact with the @zbd/node library without writing any code.

The Dev Playground has built-in modules and source code showing the usage of the @zbd/node SDK to perform Payins and Payouts in Bitcoin. From creating Charges, to editing Static QR codes, to sending Lightning Address payments -- there's a module for everything.

To make the most of the Dev Playground, clone the source code repository to your local machine and follow the instructions in the README to get started.

git clone https://github.com/zebedeeio/nextjs-zebedee-starter.git

Once you've connected your ZBD API Key as a local environment variable and started the Next.js server, you can open your local Dev Playground at localhost:3000/playground.

You may also check out a LIVE running version of the Dev Playground here.

Dev Playground

@zbd/node

The goal of the project is to create a beautiful and extensible experience for developers using ZBD APIs in a Node.js environment. Our focus will be primarily around providing parity with ZBD REST API, as well as providing further stability for developers.

In the future, we anticipate adding Node.js-only APIs to this SDK. We also anticipate the community will come up with innovative additions to enhance what could be the simplest and most powerful Bitcoin payments API.

API Reference

Below is a comprehensive list of the methods and functions available in the @zbd/node SDK. These methods are ONLY available to the zbd client instance after it's been properly authenticated with a Project's API Key.

MethodEntityDescription
createCharge
Charge

Creates a new Charge / Payment Request in the Bitcoin Lightning Network, payable by any Bitcoin Lightning wallet.

Parameters:

amount

required

The amount for the Charge -> in millisatoshis.
description

required

Note or comment for this Charge (visible to payer).
expiresInTime until Charge expiration -> in seconds.
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST Charge updates to.


Resources:

View response payload examples
View source code example examples
getCharge
Charge

Retrieves all information relating to a specific Charge / Payment Request.

Parameters:

chargeId

required

The ID of the Charge.


Resources:

View response payload examples
View source code example examples
decodeCharge
Charge

Decodes a specific Charge / Payment Request / Invoice from Bitcoin's Lightning Network. This API returns all of the individual properties for the Charge, including the amount, description, expiration, and more.

Parameters:

invoice

required

The code for the Charge / Payment Request / Lightning Network invoice (e.g. lnbc10m.....61hj).


Resources:

View response payload examples
View source code example examples
createStaticCharge
Static Charge

Static Charges are static Payment Requests in the Bitcoin Lightning Network. Whereas Charges create fixed-amount and single-use Payment Requests that expire, Static Charges provide you a lot more flexibility & capabilities, including variable amounts, multi-use, success messages, and slots.

Parameters:

minAmount

required

Minimum allowed amount for the Static Charge -> in millisatoshis.
maxAmount

required

Maximum allowed amount for the Static Charge -> in millisatoshis.
description

required

Note or comment for this Static Charge (visible to payer).
successMessageMessage displayed to the payer AFTER payment settles.
allowedSlotsNumber of payments this Static Charge can accept
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST updates to.


Resources:

View response payload examples
View source code example examples
getStaticCharge
Static Charge

Retrieves all information relating to a specific Static Charge.

Parameters:

staticChargeId

required

The ID of the Static Charge.


Resources:

View response payload examples
View source code example examples
updateStaticCharge
Static Charge

Perform updates to any of the allowed properties of a Static Charge.

Parameters:

minAmountMinimum allowed amount for the Static Charge -> in millisatoshis.
maxAmountMaximum allowed amount for the Static Charge -> in millisatoshis.
descriptionNote or comment for this Static Charge (visible to payer).
successMessageMessage displayed to the payer AFTER payment settles.
allowedSlotsNumber of payments this Static Charge can accept
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST updates to.


Resources:

View response payload examples
View source code example examples
createWithdrawalRequest
Withdrawal Request

A Withdrawal Request is a QR code that allows someone to scan and receive Bitcoin (e.g. Withdrawals).

Parameters:

amount

required

The amount for the Withdrawal Request -> in millisatoshis.
expiresInTime until Withdrawal Request expiration -> in seconds.
descriptionNote or comment for this Withdrawal Request (visible to payer).
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST Withdrawal Request updates to.


Resources:

View response payload examples
View source code example examples
getWithdrawalRequest
Withdrawal Request

Retrieves details about a specific Withdrawal Request.

Parameters:

withdrawalRequestId

required

The ID of the Withdrawal Request.


Resources:

View response payload examples
View source code example examples
sendLightningAddressPayment
Lightning Address

Send Bitcoin payments directly to a Lightning Address. A Lightning Address is an internet identifier (akin to an email address -- andre@zbd.gg) that anyone can send Bitcoin Lightning Network payments to.

Parameters:

amount

required

The amount for the Payment -> in millisatoshis.
lnAddress

required

The Lightning Address of the intended recipient.
commentNote or description of this Payment.
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST updates to.


Resources:

View response payload examples
View source code example examples
validateLightningAddress
Lightning Address

Not all internet identifiers are Lightning Addresses / compatible with the Lightning Address protocol. Use this endpoint in order to validate whether a user's entered Lightning Address is valid.

Parameters:

Lightning Address

required

The address attempted to be verified.


Resources:

View response payload examples
createChargeFromLightningAddress
Lightning Address

Generates a Bitcoin Lightning Charge / Payment Request for a given Lightning Address destination. Depending on your system's configuration or your product's UX, you may need the ability to generate Charges for specific users using a different provider than ZBD.

Parameters:

lnAddress

required

The Lightning Address of the intended recipient.
amount

required

The amount for the Charge -> in millisatoshis.
descriptionNote or comment of this Charge.


Resources:

View response payload examples
View source code example examples
getWallet
Wallet

Retrieves the total balance of a given Project Wallet.



Resources:

View response payload examples
View source code example examples
internalTransfer
Wallet

Initiates a transfer of funds between two Project Wallets you own.

Parameters:

amount

required

The amount to be transferred -> in millisatoshis.
receiverWalletId

required

The Wallet ID of the recipient Project.


Resources:

View response payload examples
View source code example examples
sendKeysendPayment
Keysend

This endpoint exposes the ability to make payment directly to a Lightning Network node Public Key, without the need for a Payment Request / Charge.

Parameters:

amount

required

The amount for the Payment -> in millisatoshis.
pubkey

required

The Public Key for the destination Lightning node.
callbackUrlThe endpoint ZBD will POST updates to.
internalIdOpen metadata object property.
tlvRecordsTLV data records.


Resources:

View response payload examples
View source code example examples
sendPayment
Payment

Pays a Charge / Payment Request in the Bitcoin Lightning Network.

Parameters:

invoice

required

Lightning Network Payment Request / Charge.
descriptionNote or comment for this Payment.
amountAmount to be paid to this Charge/Invoice -> in millisatoshis (only valid if Amountless Invoice).
internalIdOpen metadata string property.
callbackUrlThe endpoint ZBD will POST updates to.


Resources:

View response payload examples
View source code example examples
getPayment
Payment

Retrieves all the information related to a specific Payment.

Parameters:

paymentId

required

The ID of the Payment.


Resources:

View response payload examples
View source code example examples
sendGamertagPayment
ZBD Gamertag

This API endpoint is used to send Bitcoin payments directly to a user's ZBD Gamertag.

Parameters:

amount

required

The amount for the Payment -> in millisatoshis.
gamertag

required

Destination ZBD Gamertag.
descriptionNote or comment for this Payment (visible to recipient).


Resources:

View response payload examples
View source code example examples
getGamertagTransaction
ZBD Gamertag

Get a given ZBD Gamertag when provided with a ZBD User's ID.

Parameters:

transactionId

required

The ZBD Gamertag Payment Transaction ID.


Resources:

View response payload examples
View source code example examples
getUserIdByGamertag
ZBD Gamertag

Get a given ZBD User's ID when provided with a ZBD Gamertag.

Parameters:

gamertag

required

The ZBD Gamertag of the ZBD user.


Resources:

View response payload examples
View source code example examples
getGamertagByUserId
ZBD Gamertag

Invoked when the app first loads. If a plugin reloads, it's invoked again with the existing app.

Parameters:

userId

required

The specified ZBD User ID.


Resources:

View response payload examples
View source code example examples
isSupportedRegion
Utility

If you wish to know whether the incoming user request is coming from a region/country where ZBD is supported or not, you can use this simple API endpoint and pass the target IP address as a parameter.

Parameters:

IP Address

required

The IP Address being checked.


Resources:

View response payload examples
View source code example examples
getZBDProdIps
Utility

The ZBD API relies on callback URLs for keeping you informed about updates that occur to any Charges, Payments, or Withdrawals you've created. In order to ensure that any incoming callback message is indeed from a trusted ZBD API infrastructure server, we provide this API endpoint for you to know which IP addresses real requests come from.



Resources:

View response payload examples
View source code example examples
getBtcUsdExchangeRate
Utility

Get the latest price for Bitcoin in US Dollars. The exchange rate feed is refreshed every 5 seconds and is based upon a combination of industry-leading partner exchange providers's price feeds.



Resources:

View response payload examples
View source code example examples

Community Support

Feature Request? Bugfix? Recommendations? We're all ears! Head on over to the @zbd/node Issues page and submit one. We also welcome Pull Requests and other contributions to the library.