WaaS Fee Configuration

Configure automatic fee collection for customer transfers. When enabled, a percentage fee is automatically deducted on every WaaS transfer and sent directly on-chain to your configured crypto address — no platform intermediary.

Endpoints

Method	Path	Description
GET	/api/v1/settings/waas/fees	Get current fee configuration
POST	/api/v1/settings/waas/fees	Set fee percentage + addresses
PUT	/api/v1/settings/waas/fees/addresses	Update addresses only

Authentication

Requires Bearer JWT (dashboard session) with wallet:manage permission.

Authorization: Bearer <jwt_token>

---

GET /api/v1/settings/waas/fees

Returns the current fee percentage, enabled state, and all per-network receiving addresses.

Response

{
  "business_id": 7,
  "fee_percent": "0.010000",
  "is_enabled": true,
  "fee_addresses": {
    "ETH": "0xYourEthAddress",
    "BSC": "0xYourEthAddress",
    "POL": "0xYourEthAddress",
    "TRX": "TYourTronAddress",
    "SOL": "YourSolanaAddress",
    "BTC": "bc1yourbitcoinaddress",
    "LTC": "ltc1yourlitecoinaddress",
    "BCH": "bitcoincash:youraddress",
    "XRP": "rYourXRPAddress"
  }
}

If no configuration has been created yet, returns defaults: fee_percent: "0", is_enabled: false, fee_addresses: {}.

---

POST /api/v1/settings/waas/fees

Creates or updates the fee configuration in one call. Updates the fee percentage, enabled flag, and optionally per-network receiving addresses.

Request Body

Field	Type	Required	Description
fee_percent	string	Yes	Fee as a decimal string — "0.01" = 1%. Range: "0" to "0.5" (max 50%)
is_enabled	boolean	No	Enable/disable fee collection. Default: false
fee_addresses	object	No	Map of network code → your crypto address. Omit a network to leave it unchanged. Pass "" to remove.

Example Request

POST /api/v1/settings/waas/fees
Authorization: Bearer <token>
Content-Type: application/json

{
  "fee_percent": "0.01",
  "is_enabled": true,
  "fee_addresses": {
    "ETH": "0xYourEthAddress",
    "BSC": "0xYourEthAddress",
    "POL": "0xYourEthAddress",
    "TRX": "TYourTronAddress",
    "SOL": "YourSolanaAddress",
    "BTC": "bc1yourbitcoinaddress",
    "LTC": "ltc1yourlitecoinaddress",
    "BCH": "bitcoincash:youraddress",
    "XRP": "rYourXRPAddress"
  }
}

Response (200 OK)

{
  "business_id": 7,
  "fee_percent": "0.010000",
  "is_enabled": true,
  "fee_addresses": {
    "ETH": "0xYourEthAddress",
    "BSC": "0xYourEthAddress",
    "POL": "0xYourEthAddress",
    "TRX": "TYourTronAddress",
    "SOL": "YourSolanaAddress",
    "BTC": "bc1yourbitcoinaddress",
    "LTC": "ltc1yourlitecoinaddress",
    "BCH": "bitcoincash:youraddress",
    "XRP": "rYourXRPAddress"
  },
  "message": "Fee configuration updated"
}

Error Responses

400 — Invalid fee_percent

{ "error": "fee_percent must be between 0 and 0.5 (50%)" }

---

PUT /api/v1/settings/waas/fees/addresses

Updates only the per-network fee addresses. The fee percentage and enabled flag are unchanged.

Use this when you want to:

• Add a new network address without changing the percentage
• Update a specific address (e.g. after rotating your wallet)
• Remove fee collection for a specific network (pass "")

Request Body

Field	Type	Required	Description
addresses	object	Yes	Map of network → address. Only the listed networks are updated.

Example Request

PUT /api/v1/settings/waas/fees/addresses
Authorization: Bearer <token>
Content-Type: application/json

{
  "addresses": {
    "ETH": "0xNewEthAddress",
    "TRX": "TNewTronAddress",
    "BTC": ""
  }
}

Passing "BTC": "" removes the Bitcoin fee address. No Bitcoin fees will be collected until a new address is set.

Response (200 OK)

Returns the complete updated address map (not just the keys you sent):

{
  "fee_addresses": {
    "ETH": "0xNewEthAddress",
    "BSC": "0xYourEthAddress",
    "POL": "0xYourEthAddress",
    "TRX": "TNewTronAddress",
    "SOL": "YourSolanaAddress",
    "LTC": "ltc1yourlitecoinaddress",
    "BCH": "bitcoincash:youraddress",
    "XRP": "rYourXRPAddress"
  },
  "message": "Fee collection addresses updated"
}

---

How fee collection works

Fee deduction

When is_enabled: true and a customer executes a transfer on a network that has a configured address:

1. The gross amount (what you pass as amount in the transfer request) is received
2. The fee is calculated: fee = floor(gross × fee_percent)
3. The net amount (gross - fee) is sent to the recipient
4. The fee is sent on-chain directly to your configured address for that network
5. The transfer API response includes fee_amount and fee_tx_hash

Per-chain mechanics

Chain	How fee is routed
BTC, LTC, BCH	Single transaction with 3 outputs: recipient + your address + change
SOL (native)	Single transaction with 2 transfer instructions
ETH, BSC, POL, TRX, XRP, SOL USDC	Two sequential transactions — main transfer first, then fee

Networks without a configured address

If a customer transfer happens on a network that has no fee address configured, the fee is skipped entirely for that transfer — no error, the full amount goes to the recipient. This lets you selectively enable fee collection per network.

Transfer response with fee

{
  "tx_hash": "0x1a2b3c...",
  "from_address": "0xCustomerWallet",
  "to_address": "0xRecipient",
  "amount": "9900000",
  "currency": "USDT",
  "network": "ETH",
  "gas_fee": "2100000000000000",
  "status": "pending",
  "timestamp": "2026-06-26T12:00:00Z",
  "fee_amount": "100000",
  "fee_tx_hash": "0xfee..."
}

For BTC/LTC/BCH, fee_tx_hash is an empty string because the fee is a third output in the main transaction.

fee_percent reference

fee_percent	Meaning
"0"	No fee (pass-through)
"0.001"	0.1%
"0.005"	0.5%
"0.01"	1%
"0.02"	2%
"0.05"	5%
"0.1"	10%
"0.5"	50% (maximum)

Related Endpoints

• Transfer — Execute a WaaS transfer (fee applied automatically)
• Earnings Dashboard — View collected fees