> ## 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.

# How Bitnob Enterprise gas stations work

> A gas station is a pre-funded native balance per chain that pays fees for your Enterprise wallets, refills itself, and alerts you before it runs dry.

When you hold customer funds in Bitnob Enterprise wallets, every outbound transfer needs native gas at the sending address. With one wallet per customer, keeping ETH or TRX at thousands of addresses quickly becomes unmanageable. A gas station solves this: one balance of the native asset per chain, which pays the fee for any sponsored transfer from your wallets.

## The model

A gas station belongs to your organization and works on one chain. It has its own on-chain `address`, holding the chain's native asset (`asset` is `ETH`, `TRX`, and so on).

When you send from one of your wallets with sponsorship on, the gas station pays the network fee. The sending wallet only needs the token it is sending.

```mermaid theme={null}
flowchart LR
    T[Treasury wallet] -- auto-refill --> G[Gas station<br/>native asset]
    G -- pays the fee --> X[Sponsored transfer]
    W[Customer wallet<br/>USDT only] -- USDT --> X
    X --> R[Recipient]
```

## Sponsoring a transfer

Set `sponsor: true` on [Create transaction](https://www.bitnob.dev/api-reference/platform/transactions/create-transaction.md):

```json theme={null}
{
  "wallet_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "to_address": "TD5gsCwxykWsLN9aPrq2TAfNjByuZKYp4E",
  "asset": "USDT_TRX",
  "amount": "250",
  "sponsor": true
}
```

The transaction response shows the sponsorship:

| Field | Meaning |
| - | - |
| `sponsored` | `true` when the network fee was sponsored. |
| `gas_station_id` | The gas station that paid. |
| `status` | Passes through `awaiting_sponsorship` while the gas station funds the fee, before `broadcasting`. |

To see what sponsorship will cost before you send, pass the same `sponsor: true` to [Estimate transaction fee](https://www.bitnob.dev/api-reference/platform/transactions/estimate-transaction-fee.md).

Sponsored transactions still pass through your [policies](https://www.bitnob.dev/docs/platform/policies/overview.md). Sponsorship changes who pays the fee, not whether the transfer is allowed.

## Thresholds and auto-refill

Each gas station has a `threshold` in the native asset's display unit, for example `"0.05"` ETH. It drives two things:

* **Health.** `health_status` is `healthy` while the balance is at or above the threshold, and `low` below it.
* **Auto-refill.** With `auto_refill_enabled`, when the balance drops below `threshold`, the gas station pulls `refill_amount` from `refill_from_wallet_id`, a wallet you choose, usually a treasury wallet on the same chain.

You can also top up at any time with [Refill gas station](https://www.bitnob.dev/api-reference/platform/gasstations/refill-gas-station.md). A refill is an ordinary transaction from the source wallet, so it is subject to your policies and appears in your transaction history.

> [!WARNING]
>
> Auto-refill moves funds out of the source wallet, so that wallet needs enough native balance too. If both run dry, sponsored transfers on that chain stop. Watch the source wallet as well as the gas station.

## Alerts

Gas stations emit three webhook events:

| Event | Sent when |
| - | - |
| `gas_station.low_balance` | The balance falls below the threshold. |
| `gas_station.critical_balance` | The balance is close to empty, and sponsored transfers on that chain are at risk. |
| `gas_station.auto_refilled` | An auto-refill completed. |

Route `critical_balance` to whoever can fund the source wallet. A run of `auto_refilled` events at short intervals means `refill_amount` is too small for your volume.

## Units

Gas station fields come in two forms. `threshold` and `refill_amount` are display-unit decimals, such as `"0.25"` ETH, with `_raw` versions in base units. `balance` is **only** in base units, such as wei or sun. Divide it by `10^asset_decimals` before you compare it with `threshold`.

## Sponsoring externally signed Tron transactions

A gas station can also pay for a Tron transaction your system didn't sign through Bitnob. [Sponsor and broadcast](https://www.bitnob.dev/api-reference/platform/gasstations/sponsor-and-broadcast-external-tron-transaction.md) takes the signed raw transaction, funds the fee from the gas station, and broadcasts it. The response includes the `sponsor_tx_id` of the fee-funding transaction and the amount sponsored in TRX.

## Gas stations or sponsored transfers

| | Gas station | Sponsored transfer |
| - | - | - |
| Sends from | Your Enterprise wallets | Your users' own addresses |
| You pre-fund | Native asset, per chain | Nothing |
| Fee is paid by | You, in the native asset | The sender, in the token |
| Governed by | Your policies | Your application logic |

If you run both custodial and self-custody flows, you can use both. See [How sponsored transfers work](https://www.bitnob.dev/docs/platform/gas-sponsorship/how-sponsored-transfers-work.md).


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