> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Charge your own fee on sponsored transfers

> Add a flat partner fee to each sponsored transfer, paid in the same token to an address you control, settled with the transfer.

A partner fee is your own charge on a sponsored transfer, on top of Bitnob's sponsorship fee. It is paid in the token being sent, to an address you choose, and settled as part of the transfer. You don't need a separate collection step, and you never hold the user's funds.

Partner fees work on every supported chain: Solana, the EVM chains, and Tron.

## Add it to the quote

Pass `partner_fee` with an `address` and an `amount`. Both are required together.

```bash theme={null}
curl https://api.platform.bitnob.com/v1/sponsored-transfers \
  -H "X-API-Key: $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-0004" \
  -d '{
    "chain": "solana",
    "asset": "USDC",
    "from": "Sender1111111111111111111111111111111111111",
    "to": "Recipient1111111111111111111111111111111111",
    "amount": "10.50",
    "partner_fee": {
      "address": "PartnerFee111111111111111111111111111111111",
      "amount": "0.20"
    }
  }'
```

```json theme={null}
{
  "object": "sponsored_transfer",
  "status": "quoted",
  "recipient_amount": "10.5",
  "fee": { "amount": "0.004", "asset": "USDC", "usd": "0.004" },
  "partner_fee": {
    "address": "PartnerFee111111111111111111111111111111111",
    "amount": "0.20",
    "asset": "USDC",
    "usd": "0.20"
  },
  "total_debit": "10.704"
}
```

The recipient still receives 10.50 USDC. The sender is debited 10.704: the transfer, plus the 0.004 sponsorship fee to Bitnob, plus 0.20 to you. The sponsorship fee here is an example. Because the fee is part of the payload the user signs, the user approves your fee explicitly, and it can't be changed after they sign.

## Rules

* **`amount`** is a flat amount in the token's normal units, for example `"0.20"` USDC. It is not a percentage. To charge a percentage, calculate it before you request the quote.
* **The amount is capped per chain.** A quote over the cap returns `400 partner_fee_too_high`.
* **`address` can't be the sender or the recipient.**
* **On Solana**, `address` must already have a token account for the asset. Create the associated token account once, before your first quote. Otherwise the quote returns `400`.

## Net and gross mode

In net mode, the default, your fee is added on top: `total_debit` = `amount` + `fee` + `partner_fee`.

In gross mode, with `treat_as_gross_amount: true`, your fee comes out of `amount` along with Bitnob's: `recipient_amount` = `amount` − `fee` − `partner_fee`. If `amount` doesn't exceed both fees together, the quote returns `400 invalid_request`. See [Sweep a full balance](https://www.bitnob.dev/docs/platform/gas-sponsorship/sweep-a-full-balance.md).

## Show it to the user

List your fee separately from the network fee in your confirmation screen. Both appear on chain, so a single combined "fee" line can look like a hidden charge to a user who checks.

| Line | Field |
| - | - |
| Recipient gets | `recipient_amount` |
| Network fee | `fee.amount` |
| Service fee | `partner_fee.amount` |
| You pay | `total_debit` |

## Reconcile your fees

Your fee arrives at `partner_fee.address` when the transfer completes. To reconcile, match incoming credits to that address against sponsored transfers in `completed` status, using the stored `tx_hash` and `partner_fee.amount`. [List sponsored transfers](https://www.bitnob.dev/api-reference/platform/sponsored-transfers/list-sponsored-transfers.md) returns only the most recent page, so store each transfer's `id`, `tx_hash`, and `partner_fee` in your own records as it completes, rather than relying on listing later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.