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.
@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.
Method | Entity | Description | ||||||||||||||||
createCharge | Charge | Creates a new Charge / Payment Request in the Bitcoin Lightning Network, payable by any Bitcoin Lightning wallet. Parameters:
Resources:
| ||||||||||||||||
getCharge | Charge | Retrieves all information relating to a specific Charge / Payment Request. Parameters:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
getStaticCharge | Static Charge | Retrieves all information relating to a specific Static Charge. Parameters:
Resources:
| ||||||||||||||||
updateStaticCharge | Static Charge | Perform updates to any of the allowed properties of a Static Charge. Parameters:
Resources:
| ||||||||||||||||
createWithdrawalRequest | Withdrawal Request | A Withdrawal Request is a QR code that allows someone to scan and receive Bitcoin (e.g. Withdrawals). Parameters:
Resources:
| ||||||||||||||||
getWithdrawalRequest | Withdrawal Request | Retrieves details about a specific Withdrawal Request. Parameters:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
getWallet | Wallet | Retrieves the total balance of a given Project Wallet. Resources:
| ||||||||||||||||
internalTransfer | Wallet | Initiates a transfer of funds between two Project Wallets you own. Parameters:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
sendPayment | Payment | Pays a Charge / Payment Request in the Bitcoin Lightning Network. Parameters:
Resources:
| ||||||||||||||||
getPayment | Payment | Retrieves all the information related to a specific Payment. Parameters:
Resources:
| ||||||||||||||||
sendGamertagPayment | ZBD Gamertag | This API endpoint is used to send Bitcoin payments directly to a user's ZBD Gamertag. Parameters:
Resources:
| ||||||||||||||||
getGamertagTransaction | ZBD Gamertag | Get a given ZBD Gamertag when provided with a ZBD User's ID. Parameters:
Resources:
| ||||||||||||||||
getUserIdByGamertag | ZBD Gamertag | Get a given ZBD User's ID when provided with a ZBD Gamertag. Parameters:
Resources:
| ||||||||||||||||
getGamertagByUserId | ZBD Gamertag | Invoked when the app first loads. If a plugin reloads, it's invoked again with the existing app. Parameters:
Resources:
| ||||||||||||||||
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:
Resources:
| ||||||||||||||||
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:
| ||||||||||||||||
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:
|
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.