Request Client

You can use the Request Client library to connect to an existing node, for example one you have deployed yourself. You can view an interactive example of using the request client below.

The request client ships both as a commonjs and a UMD module. This means you can use it in node application and in web pages.

Below is an example of using the request-client.js as a commonjs module.

Using the request-client.js library

@requestnetwork/request-client.js is a typescript library part of the Request protocol. This package allows you to interact with the Request blockchain through Request nodes. This client side library uses Request nodes as servers, connected in HTTP. See the Request node documentation for more details on their API. It ships both as a commonjs and a UMD module. This means you can use it in node application and in web pages.

Use @requestnetwork/request-client.js to connect to a node and create requests.

npm install @requestnetwork/request-client.js

More information is available on github.

You can also follow this example.

Configure the Node to be used

Connect the library to a node or mock a node for development environments like explained here.

const requestNetwork = new RequestNetwork({
nodeConnectionConfig: { baseURL: '' },

It can be further configured with option from Axios.

Alternatively, you can use the request-client in development without a node by using the useMockStorage option. When the option useMockStorage is true, the library will use a mock storage in memory instead of a Request node. It is meant to simplify local development and should never be used in production. Nothing will be persisted on the Ethereum blockchain and IPFS, it will all stay in memory until your program stops.

const requestNetwork = new RequestNetwork({ useMockStorage: true });

That's it! You can now use the Request client.

The request-client.js in practice

Let's create a simple application using the request-client.js. We'll create a simple invoice flow between two parties which will include creating, accepting, fetching and updating the expected amount of the invoice.

Firstly, we need to define some parameters for the invoice such as the currency, expected amounts, the payee

const requestParameters = {
currency: RequestLogicTypes.CURRENCY.BTC,
expectedAmount: '100000000000',
payee: {
type: IdentityTypes.TYPE.ETHEREUM_ADDRESS,
value: '0x627306090abab3a6e1400e9345bc60c78a8bef57',
payer: {
type: IdentityTypes.TYPE.ETHEREUM_ADDRESS,
value: '0x740fc87Bd3f41d07d23A01DEc90623eBC5fed9D6',

We will also need to define a payment network which will define which payment address will receive the BTC payment

const paymentNetwork = {
parameters: {
paymentAddress: 'mgPKDuVmuS9oeE2D9VPiCQriyU14wxWS1v',

We now have everything we need to create an invoice, we can create an invoice like so:

const invoice = await requestNetwork.createRequest({
signer: requestParameters.payee,

You can now view information on this request

Get invoice information from its request ID

const invoiceFromRequestID = await requestNetwork.fromRequestId(invoice);
const requestData = invoiceFromRequestID.getData();
/* {
} */

We can then use this object to check various fields of the request like expectedAmount, balance, payer, payee, and metadata attached to the request.

Accepting / cancelling an invoice information

After the invoice has been created, the customer can accept the invoice. First you must create a signature as per - after this you can accept, decline or change the expected amount of the invoice

await request.accept(signatureInfo);
await request.cancel(signatureInfo);
//Increase the expected amount
await request.decreaseExpectedAmountRequest(amount, signatureInfo);
//Decrease the expected amount
await request.increaseExpectedAmountRequest(amount, signatureInfo);

Don't forget, we can then call fromRequestId to get the updated invoice information.

Payment and refund detection

If a payment network has been given to the request, the payment detection can be done.

From the information provided in payment network, the library will feed the property balance of the request with:

  • balance: the sum of the amount of all payments minus the sum of amount of all refunds

  • events: all the payments and refunds events with the amount, timestamp etc...

The payment networks available are:

  • Types.PAYMENT_NETWORK_ID.DECLARATIVE ('pn-any-declarative'): Can be use with any currency. The payments and refunds are documented by the payer and the payee of the request. It does not ensure payment detection, only a consensus is made between the payer and the payee. (see declarative requests)

  • Types.PAYMENT_NETWORK_ID.BITCOIN_ADDRESS_BASED ('pn-bitcoin-address-based'): handle Bitcoin payments associated to a BTC address to the request, every transaction hitting this address will be consider as a payment. Eventually, the payer can provide a BTC address for the refunds. Note that the addresses must be used only for one and only one request otherwise one transaction will be considered as a payment for more than one request. (see the specification)

  • Types.PAYMENT_NETWORK_ID.TESTNET_BITCOIN_ADDRESS_BASED ('pn-testnet-bitcoin-address-based'): Same as previous but for the bitcoin testnet (for test purpose)