[Admin] Monetize API with Network Actions

Capture Network Action is a feature supported by the "network action" system which is a flexible and scalable system that handles all of the technical aspects of payment processing, making it easy for developers to easily monetize their API or plugin for users with Capture Wallet.

The Network App system is designed to be a pay-as-you-go solution, making it easy for users to control their budget and only pay for the services they use. By topping up their Capture Wallet with sufficient funds, users can easily make use of the paid plugins and APIs supported by the "network app" system. It is perfect for businesses to control usage and avoid overspending.

Step 1: Create a network app

• In order to create a network app, you will need to have the Capture Token with admin permission.

• Before making the request, you will also need to request an API key from the storage backend admin and make sure it is registered on the API Key spreadsheet. This is needed in Step 2 to create orders for users.

• Use the following curl command to make the request:

curl -X POST https://api.numbersprotocol.io/api/v3/store/network-apps/ \
     -H 'Authorization: token ADMIN_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ 
         "name": "TestNetworkApp", 
         "price_mode": "fixed", 
         "webhook_url": "https://dia-backend.numbersprotocol.io/api/v3/store/network-apps/", 
         "price": 0.5 }'

• Make sure to replaceADMIN_TOKEN with the actual token in your code. The price unit is NUM, replace the number with the price you desire.

• If you want the network app system to call webhook after the payment is successful, update the webhook_url.

Once it is created, use the following curl command to get the NETWORK_APP_ID

curl -X GET https://api.numbersprotocol.io/api/v3/store/network-apps/?name=TestNetworkApp \
     -H 'Authorization: token ADMIN_TOKEN'

The response.data.results[0].id is the NETWORK_APP_ID you need for the next step.

Step 2: Create order for users

Add the network-app-orders API endpoint in your code to create orders for users. The following is an example in curl:

curl -X POST https://api.numbersprotocol.io/api/v3/store/network-app-orders/ \
     -H "Authorization: token USER_TOKEN" \
     -H 'x-api-key: YOUR_API_KEY' \ 
     -d '{
             "network_app": NETWORK_APP_ID,
             "action_args": {"nid": "bafkreicd6egp364rzu7est6nts6gus4s53r75jles7wisa65suwskclz6q"}}
         }'

• Please note, USER_TOKEN should be used for the "Authorization" header instead of ADMIN_TOKEN, as the order is being created under the user's account.

• Make sure to replace YOUR_API_KEY with the actual key.

• Replace action_args to the arguments needed by your webhook.

• If there is no need to call webhook after payment is successful, keep the webhook_url in the example and there is no need to input action_args.

• The response.data.id is the ORDER_ID you need for the next step.

Step 3: Confirm the order

Once the order is created, the confirmation needs to be done within 15 minutes. It is recommended to confirm the order only after it has been created to avoid any potential errors or issues. If the user confirms their intent to proceed with the order before it is created, the API can be called to confirm the order immediately after it is created.

curl -X POST https://api.numbersprotocol.io/api/v3/store/network-app-orders/${ORDER_ID}/confirm/ \
     -H "Authorization: token USER_TOKEN" \
     -H 'x-api-key: YOUR_API_KEY' \ 

Once the order is confirmed, the user's wallet will be charged the price of the network app as specified in Step 1. To avoid any confusion or misunderstandings, it is best to clearly communicate the cost of the network app to the user before proceeding with the confirmation of the order.

Check user wallet balance

To ensure that users have sufficient funds to proceed with a request, you can check the user's wallet balance. Follow the instruction here, use auth/users endpoint and authenticate with USER_TOKEN to retrieve the NUM balance of users.

Here is a sample code in node.js to check the wallet balance:

const gasEstimation = 0.03;
const totalBalance = parseFloat(user_wallet.asset_wallet_num) + parseFloat(user_wallet.points));
if (totalBalance < parseFloat(networkAppPrice) + gasEstimation) {
    console.log("Insufficient fund to proceed the transaction")
}