Skip to content

Configuring your API

After creating an API, you can make updates to it (e.g., its name, API credentials, documentation, earning details, etc):

  1. Enter the API portal.
  2. Link the wallet that owns your API.
  3. Click "My APIs".
  4. Click the API you want to update.
  5. Click "Edit" and follow the dialogs (this stage requires re-authorisation).

Setting your earnings rate

Dhali currently supports setting your earnings on a per request or per second basis. HTTPS APIs support both per request and per second charging, meaning that a single complete HTTPS request is charged as one unit. In contrast, WebSocket APIs only allow per request charging. Additionally, WebSocket APIs charge on both the upstream (client-to-server) and the downstream (server-to-client) flows, whereas HTTPS APIs charge for the complete request as a single unit. Because of this bidirectional charging, you may consider setting the per request rate for WebSocket APIs at approximately half the rate of an equivalent HTTPS API.

Surcharging

Dhali allows HTTPS and Websocket API providers to apply dynamic pricing in addition to the base per-second and per-request earning types. A basic example can be found here. To enable surcharging, edit your API and select a non-zero maximum surcharge value. The general flow of surcharging is:

  • A user accesses your surcharge-enabled API through Dhali.
  • Dhali forwards the request, adding the header X-Payment-Claim-Surcharge-Currency, which is a base 64 encoded string taking the decoded form:
{
   "schema": (string) A version,
   "networkType": (string) The payment network type, e.g., XRPL,
   "networkID": (int, required) For XRPL-like networks, we use these IDs: https://docs.xahau.network/technical/protocol-reference/transactions/transaction-common-fields#networkid-field,
   "code" : (string) The currency code the API earns, e.g., XRP,
   "scale": (int) The currency's scale, e.g., 6,
   "maxAmount": (int) The maximum amount this API allows to be surcharged,
   "issuer": (string, optional) The identifier of a token issuer,
}
  • The linked API optionally adds an extra charge by responding to Dhali with the header X-Payment-Claim-Surcharge (for websockets, this is returned in the json body), which must be a base 64 encoded string taking the decoded form: 
    {
   "schema": (string, required) A version,
   "amount": (unsigned int) The amount to surcharged, measured in the code/scale pair from 2.
}

Encoding and decoding surcharge headers

Below are JavaScript examples of how the X-Payment-Claim-Surcharge-Currency and X-Payment-Claim-Surcharge headers should be encoded when placed into the header: 

const data = { key: "value", number: 123 };
const jsonString = JSON.stringify(data);
const base64EncodedString = Buffer.from(jsonString).toString('base64');
And can be decoded as follows: 
const decodedBytes = Buffer.from(base64EncodedString, 'base64');
const decodedJsonString = decodedBytes.toString('utf-8');
const originalData = JSON.parse(decodedJsonString);
console.log(originalData);