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

# Bitnob Enterprise core concepts

> Vaults, wallets, policies, and approvals: the objects to model your Bitnob Enterprise integration around.

These are the building blocks behind Bitnob Enterprise. Understanding them will help you model your integration correctly and configure policies that reflect your actual security requirements.

## Custody model

Bitnob Enterprise is non-custodial. You hold the assets, and Bitnob cannot move them. Private keys are generated inside the Bitnob Secure Enclave, a key management system built on AWS Nitro Enclaves, and never leave that hardware boundary.

The platform itself cannot move funds without an authenticated API call that your enforced policy allows. Every signing event is recorded as an immutable activity entry for compliance and audit.

* **Keys are generated in hardware isolation.** No process outside the enclave ever sees the raw private key material.
* **Policies run before signing.** The enclave only releases a signature when your enforced policy allows the authenticated request.
* **Bitnob cannot unilaterally move funds.** There is no admin backdoor. Root quorum governance applies even to Bitnob-side operations on your organization.

## Resource hierarchy

All resources are strictly nested. Understanding this hierarchy is essential for designing your wallet topology.

![Resource Hierarchy](https://mintcdn.com/bitnob/SHTitgOAvySrbvsS/images/resource-hierarchy.webp?fit=max\&auto=format\&n=SHTitgOAvySrbvsS\&q=85\&s=a9d0950fe1586180a0ce364aed761a4e)

* **Organization**: the top-level tenant. All resources are scoped to your organization, derived automatically from your API key.
* **Vault**: an HD seed container. A dedicated vault maps 1-to-1 with a single wallet per chain. A pool vault holds unlimited wallets, ideal for assigning one per customer. See [Vaults](https://www.bitnob.dev/api-reference/platform/vaults/list-vaults.md).
* **Wallet**: a logical account derived from a vault's seed, scoped to a specific chain. Holds multiple asset balances and owns all addresses derived from it. See [Wallets](https://www.bitnob.dev/api-reference/platform/wallets/list-wallets.md).
* **Address**: a blockchain address derived from the wallet's HD path. Each wallet gets one primary address when it is created. Account-based chains hold exactly one address per wallet. Bitcoin wallets can [derive more](https://www.bitnob.dev/api-reference/platform/wallets/create-address.md). [List addresses](https://www.bitnob.dev/api-reference/platform/wallets/list-addresses.md) returns them.

## Vault types

Choose the vault type that matches your use case. The choice is irreversible, upgrading a dedicated vault to a pool vault cannot be undone. Existing vaults can be inspected with [List Vaults](https://www.bitnob.dev/api-reference/platform/vaults/list-vaults.md) and [Get Vault](https://www.bitnob.dev/api-reference/platform/vaults/get-vault.md).

| Type | Wallets per chain | Best for |
| - | - | - |
| `dedicated` | 1 | Treasury accounts, operational hot wallets, cold storage |
| `pool` | Unlimited | Exchanges, neobanks, any platform assigning one wallet per customer |

## Wallet types

The type is set on [Create Wallet](https://www.bitnob.dev/api-reference/platform/wallets/create-wallet.md) and can be reviewed with [List Wallets](https://www.bitnob.dev/api-reference/platform/wallets/list-wallets.md). It can't be changed later: [Update Wallet](https://www.bitnob.dev/api-reference/platform/wallets/update-wallet.md) only changes `name` and `metadata`.

| Type | Description |
| - | - |
| `hot` | Online, actively signing transactions. Suitable for customer deposit and withdrawal wallets. |
| `cold` | Offline storage. Requires elevated approval thresholds configured in your policies before the enclave will sign. |
| `operational` | System-managed wallets used for gas stations and internal fund sweeps. Not directly customer-facing. |

## Policy engine

A policy is an ordered list of rules that runs before the Bitnob Secure Enclave signs a transaction. Your organization enforces one policy at a time. Rules are evaluated in order, and the first rule whose conditions all match decides the outcome.

| Action | Effect |
| - | - |
| `allow` | Sign and broadcast the transaction. |
| `block` | Reject the transaction outright. No signing occurs. |
| `alert` | Allow the transaction, and send `policy.alert` to the rule's notify targets. |
| `require_approval` | Hold the transaction in `pending_authorization` until enough approvers approve it. |
| `delay` | Hold the transaction in `delayed` until a time lock expires, then execute it. |

Every policy has a category that describes its purpose: `access`, `whitelist`, `limits`, `approvals`, `velocity`, `compliance`, or `quorum`. `quorum` is reserved for the policy that governs administrative changes.

To write, test, and activate a policy, see [Policies](https://www.bitnob.dev/docs/platform/policies/overview.md).

## Approvals and root quorum

When a rule fires `require_approval`, the transaction stops at `pending_authorization` until the rule's approvers act on it:

* Once the required number of approvals is reached, the transaction proceeds automatically.
* If an approver rejects it, the transaction terminates as `rejected`.

The quorum is a special policy of category `quorum` that protects administrative operations, including policy activation. [Activate policy](https://www.bitnob.dev/api-reference/platform/policies/activate-policy.md) never applies a policy directly: it opens an approval request for the quorum, and the policy becomes `enforced` only once enough quorum approvers approve. No single API key or administrator can change what your organization enforces.

> [!WARNING]
>
> Configure the quorum in the Bitnob dashboard, with at least two approvers, before you go live. Until it has two, Activate policy returns `422`, so you can't enforce any policy through the API.

See [Policy lifecycle and quorum](https://www.bitnob.dev/docs/platform/policies/policy-lifecycle-and-quorum.md).

## Gas stations

A gas station is a pre-funded, organization-owned balance of a chain's native asset that pays network fees for your wallets: see [Gas stations](https://www.bitnob.dev/api-reference/platform/gasstations/list-gas-stations.md).

* A gas station works on one chain. Create one for each chain you send sponsored transactions on.
* Send with `sponsor: true` on [Create transaction](https://www.bitnob.dev/api-reference/platform/transactions/create-transaction.md), and the gas station pays the fee. The transaction passes through `awaiting_sponsorship`, and records `sponsored` and the `gas_station_id` that paid.
* On Tron, a gas station can also fund and broadcast a transaction someone else signed, with [Sponsor and broadcast](https://www.bitnob.dev/api-reference/platform/gasstations/sponsor-and-broadcast-external-tron-transaction.md).

Set a `threshold`, turn on `auto_refill_enabled`, and set a `refill_from_wallet_id`, so the gas station tops itself up when its balance runs low. Its `health_status` is `low` below the threshold, and the `gas_station.low_balance`, `gas_station.critical_balance`, and `gas_station.auto_refilled` events report on it.

To set one up, and to sponsor transfers from your users' own addresses, see [Gas sponsorship](https://www.bitnob.dev/docs/platform/gas-sponsorship/overview.md).

## Address book

The address book is an organization-level list of named, validated recipient addresses. A consolidation rule can sweep to an address book entry with `destination_address_book_id`.

To restrict where a wallet can send, add a policy rule with a `to_address` `not_in` condition that blocks any address you haven't listed. See [Rule reference](https://www.bitnob.dev/docs/platform/policies/rule-reference.md#operators).

## Transaction lifecycle

Every outbound transaction moves through a defined set of statuses. Understanding these helps you design correct notification handlers and UI states. The calls involved are [Create Transaction](https://www.bitnob.dev/api-reference/platform/transactions/create-transaction.md), [Get Transaction](https://www.bitnob.dev/api-reference/platform/transactions/get-transaction.md), and [List Transactions](https://www.bitnob.dev/api-reference/platform/transactions/list-transactions.md).

| Status | Description |
| - | - |
| `pending_signature` | Transaction created. Awaiting Enclave signing. |
| `pending_authorization` | A policy requires approval. Paused until approvers act. |
| `delayed` | A policy time lock holds the transaction until `execute_at`, then it executes automatically. |
| `pending_screening` | Waiting on compliance screening. |
| `signed` | Signed by the Enclave. Not yet broadcast. |
| `awaiting_sponsorship` | A gas station is funding the network fee before broadcast. |
| `broadcasting` | Submitted to the blockchain network. |
| `confirming` | On-chain and accumulating block confirmations. |
| `completed` | Confirmed with sufficient confirmations. Terminal. |
| `failed` | Errored at any stage. Terminal. |
| `cancelled` | Canceled before broadcast. Terminal. |
| `rejected` | An approver rejected the transaction. Terminal. |

Create transaction returns `201` when the transaction was signed and submitted, and `202` when it is `pending_authorization` or `delayed`. In both `202` cases the transaction is persisted and its funds are locked.


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