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

# Trading revenue reporting manual

> Data structures, reconciliation practice, and report formats for tracking trading revenue.

This manual is designed to help integrator finance teams accurately track, calculate, and report revenue generated through Bitnob’s Trading API. It includes guidance on data structures, revenue models, reconciliation practices, and reporting formats.

## Revenue sources

Integrators can generate revenue from trading by:

* Applying a spread between Bitnob’s quoted rate and the user-facing rate
* Charging a flat or percentage-based execution fee on trades
* Offering fixed-rate trades while executing on variable backend pricing

This manual focuses on capturing revenue from both spread and fee-based models.

## Key terms

| Term | Meaning |
| - | - |
| rate | Exchange rate provided by Bitnob (e.g., sats per \$1) |
| inputAmount | Amount the user traded, in the input asset's smallest unit |
| outputAmount | Amount the user received, in the output asset's smallest unit |
| bitnobOutput | Actual amount Bitnob would have returned at quoted rate |
| spreadEarned | Difference between bitnobOutput and what the user received |
| feeCharged | Platform-defined fee added to trade, if applicable |

## Revenue calculation methods

A. Spread-Based Revenue

Formula: spreadEarned = bitnobOutput - userOutput

Unit: Output asset, smallest unit

Use when:

* You fetch a quote from Bitnob
* Show a slightly different (less favorable) rate to the user
* Execute at the original Bitnob quote
* B. Fee-Based Revenue
* Formula: feeCharged = percentageFee \* inputAmount
* Unit: Input asset, smallest unit

Use when:

* You display and deduct a transparent fee (e.g., “1% execution fee”)
* The full quote rate is passed through to the user

C. Combined Model Record both spread and fee independently.

## Data you must store per trade

[Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md) returns the order fields below. Calculate the others in your own system.

| Field | Source | Purpose |
| - | - | - |
| reference | Order | Unique ID for tracking |
| id | Order | Bitnob’s ID for the trade |
| base\_currency, quote\_currency | Order | The assets in the trade |
| side | Order | `BUY` or `SELL` |
| quantity, filled\_quantity | Order | Amount requested and amount filled |
| price | Order | Bitnob price used |
| created\_at | Order | ISO timestamp of trade |
| userOutput | Your system | What the user received |
| bitnobOutput | Your system | What the user would have received at the Bitnob price |
| feeCharged | Your system | Explicit fee charged to the user (if any) |
| spreadEarned | Your system | Calculated backend profit |

## Recommended ledger format

Track trades in a financial ledger or database table:

| Reference | Inputamount | Outputamount | Rate (sats per \$1) | Bitnoboutput | Feecharged | Spreadearned | Timestamp |
| - | - | - | - | - | - | - | - |
| trade\_123 | 100000000 | 222500 | 2250 | 225000 | 0 | 2500 | 2025-05-16 |

Record every value as an integer in the smallest unit, not a float: sats for BTC, 6-decimal base units for USDT and USDC, and kobo for NGN. The trading API sends amounts as major-unit decimal strings, so convert them when you record a trade. See [Currencies and amounts](https://www.bitnob.dev/docs/getting-started/core-concepts-and-architecture/currencies-and-amounts.md#units-by-product).

## Sample monthly report template

| Date | Trades | Volume (usdt) | Volume (btc) | Volume (ngn) | Revenue (fee) | Revenue (spread) | Total Revenue |
| - | - | - | - | - | - | - | - |
| May 2025 | 1,204 | \$230,400 | 1.32 BTC | ₦12,500,000 | \$920.00 | \$1,440.00 | \$2,360.00 |

## Reconciliation practices

Reconcile revenue daily or weekly using trade logs from [Get Orders](https://www.bitnob.dev/api-reference/trading/list-orders.md), which lists crypto-pair orders only. Fetch NGN orders by ID.

Compare wallet balances before and after trade execution

Match outputAmount + spreadEarned + feeCharged against Bitnob quote data

Review webhook logs to confirm trade completion before counting revenue Ensure reference IDs are unique and mapped to internal user accounts

## Tax and regulatory notes

Treat earned spread and fees as revenue per local accounting rules

Maintain transaction-level records for all earnings

If required by jurisdiction, report asset conversions as capital gains/losses

## When to contact Bitnob finance/Ops

Mismatch between Bitnob wallet balances and internal ledger

Unexpected rate fluctuations or misquoted trades

Delayed webhook resulting in uncertain trade status


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