# Fee Calculations

Understand HivePay fees and how to calculate them in your application.

# Fee Structure

HivePay charges a percentage-based fee on each payment. The fee is deducted from the payment amount before sending to your Hive account.

Component	Description
Gross Amount	Total amount paid by customer
Fee	HivePay processing fee
Net Amount	Amount you receive (Gross - Fee)

# Get Current Fee Rate

Retrieve the current fee percentage from the API:

const feePercent = await hivepay.payments.getFeeRate();
console.log(`Current fee: ${feePercent}%`); // e.g., "1.5%"

curl https://hivepay.me/api/public/payments/fee-rate \
  -H "Authorization: Bearer sk_live_xxx"

# Fee Calculation Utilities

The TypeScript SDK provides utility functions for fee calculations:

# Calculate Split from Satoshis

import { getSplitAmount } from '@hivepay/client';

// Amount in satoshis (smallest unit)
const grossAmount = 10500n; // 10.500 HIVE/HBD
const feePercent = 1.5;

const { fee, net } = getSplitAmount(grossAmount, feePercent);

console.log('Fee:', fee);   // 158n (0.158 HIVE/HBD)
console.log('Net:', net);   // 10342n (10.342 HIVE/HBD)

# Calculate Split from Formatted Amount

import { getSplitAmountFromFormatted } from '@hivepay/client';

// Amount as decimal string
const grossAmount = '10.500';
const feePercent = 1.5;

const { fee, net } = getSplitAmountFromFormatted(grossAmount, feePercent);

console.log('Fee:', fee);   // 158n
console.log('Net:', net);   // 10342n

# Format Satoshis

Convert satoshi values to readable strings:

import { formatSatoshis } from '@hivepay/client';

const satoshis = 10500n;

console.log(formatSatoshis(satoshis));      // "10.500"
console.log(formatSatoshis(satoshis, 2));   // "10.50"
console.log(formatSatoshis(158n));          // "0.158"

# Example: Display Price Breakdown

import { getSplitAmount, formatSatoshis } from '@hivepay/client';

function displayPriceBreakdown(amount: bigint, feePercent: number, currency: string) {
  const { fee, net } = getSplitAmount(amount, feePercent);

  console.log(`Customer pays: ${formatSatoshis(amount)} ${currency}`);
  console.log(`HivePay fee (${feePercent}%): ${formatSatoshis(fee)} ${currency}`);
  console.log(`You receive: ${formatSatoshis(net)} ${currency}`);
}

displayPriceBreakdown(10500n, 1.5, 'HBD');
// Customer pays: 10.500 HBD
// HivePay fee (1.5%): 0.158 HBD
// You receive: 10.342 HBD

# Fee Calculation Formula

fee = floor(amount * feePercent / 100)
net = amount - fee

The SDK uses BigInt for precise calculations without floating-point errors.

# Payment Response

When you create or retrieve a payment, fee information is included:

{
  "id": "cmj7b2rg10004d2rimvum8kaz",
  "amount": {
    "value": "10500",
    "formatted": "10.500 HBD",
    "currency": "HBD"
  },
  "fee": "158",
  "net": "10342"
}

Field	Description
`amount.value`	Gross amount (customer pays)
`fee`	Fee deducted
`net`	Amount you receive

# Pricing Your Products

If you want customers to pay a specific amount and you want to receive a fixed net amount, calculate the gross amount:

function calculateGrossAmount(desiredNet: bigint, feePercent: number): bigint {
  // gross = net / (1 - feePercent/100)
  const multiplier = 100 - feePercent;
  return (desiredNet * 100n) / BigInt(Math.floor(multiplier));
}

// You want to receive exactly 10.000 HIVE
const desiredNet = 10000n;
const feePercent = 1.5;

const grossAmount = calculateGrossAmount(desiredNet, feePercent);
console.log('Charge customer:', formatSatoshis(grossAmount)); // ~10.153 HIVE