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

# Fills and Fee Rates

> Check your exchange maker and taker fee rates, and reconcile your orders with the fills they produced.

This guide will walk you through two things every exchange trader needs: your **fee rates** (what you pay to trade) and your **fills** (what your orders actually executed). A fill records one execution against one of your orders, including the fee actually charged and whether you were the maker or taker.

> [!TIP]
>
> **What You'll Achieve:**
>
> 1. Retrieve your effective maker and taker fee rates.
>
> 2. List your fills and understand each field.
>
> 3. Know how maker versus taker fees apply.

## Prerequisites

Before you begin, ensure you have:

* A **Busha Business Account** and **Secret API Key** (from the [Quick Start Tutorial](https://docs.busha.io/guides/getting-started/quick-start.md)).

* An API key that carries the `exchange:read` (or `api:read`) scope.

* A basic understanding of orders (from [Placing and Managing Orders](https://docs.busha.io/guides/exchange/orders.md)).

## How to Check Fills and Fees

**1. Check Your Fee Rates**

Your effective rates are decimal fractions: `0.002` means 0.2%, and a negative maker rate is a rebate. Fees settle in the market's quote currency.

To list your fee rates:

```bash theme={null}
$ curl -i -X GET \
  https://YOUR_BASE_URL/v1/exchange/fees \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Exchange fees retrieved",
  "data": [
    {
      "market": "USDT-NGN",
      "maker_fee_rate": "0",
      "taker_fee_rate": "0.002",
      "fee_currency": "NGN"
    }
  ]
}
```

Filter a single market with `?market=USDT-NGN`. Omit `market` for every listed market that accepts new orders, in symbol order.

> [!NOTE]
>
> These are your saved rates (or the entry tier). Terms can change before you
> place an order — the rate snapshot accepted on the order governs its
> executions, and `GET /v1/exchange/fills` reports what was actually
> charged.

**2. List Your Fills**

A **fill** is one execution against one of your orders. An order that traded in five prints has five fills, each with the fee actually charged and whether you were the `maker` or `taker` on that print.

To list your fills:

```bash theme={null}
$ curl -i -X GET \
  "https://YOUR_BASE_URL/v1/exchange/fills?limit=2" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Fills retrieved",
  "data": [
    {
      "fill_id": "9930447",
      "order_id": "exo_3Nd8vYpLwGtE",
      "client_order_id": "mm-usdtngn-ask-0090",
      "market": "USDT-NGN",
      "side": "sell",
      "price": "1372.30",
      "quantity": "1500.00",
      "quote_quantity": "2058450.00",
      "fee": "0.00",
      "fee_currency": "NGN",
      "liquidity": "maker",
      "time": "2026-09-06T11:59:58.412Z"
    }
  ]
}
```

The key fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`fill_id`</td>
      <td>The venue's identifier for this execution.</td>
    </tr>

    <tr>
      <td>`order_id` / `client_order_id`</td>
      <td>The order this execution belongs to, by platform ID and by your own reference.</td>
    </tr>

    <tr>
      <td>`price` / `quantity` / `quote_quantity`</td>
      <td>The executed price and sizes.</td>
    </tr>

    <tr>
      <td>`fee` / `fee_currency`</td>
      <td>The fee actually charged for this fill, in the market's quote currency.</td>
    </tr>

    <tr>
      <td>`liquidity`</td>
      <td>`maker` (your order was resting) or `taker` (your order crossed the spread). Fee rates differ by side.</td>
    </tr>
  </tbody>
</table>

Filter by `market` or `order_id`, and bound the window with `from` and `to` (execution time). `limit` defaults to `50` and is capped at `200`.

**3. Understand Maker vs. Taker**

Whether a fill is `maker` or `taker` determines its fee rate:

* **Maker** — your order rested in the book and added liquidity. You typically pay the lower rate (and may earn a rebate if the maker rate is negative).

* **Taker** — your order crossed the spread to match a resting order, removing liquidity. You pay the taker rate.

In the fee example above, the maker rate is `0` (no fee) while the taker rate is `0.002` (0.2%). A fill with `liquidity: maker` therefore charged `fee: "0.00"`.

For real-time private updates on your orders and balances, mint a stream token with `POST /v1/exchange/stream_tokens` and subscribe over the exchange stream.

## Troubleshooting Common Issues

* **`404 Not Found` on fees:** The `market` symbol is unknown. Symbols are `BASE-QUOTE` and uppercase.

* **`503 Service Unavailable` on fees:** A requested market has unusable fee terms. The endpoint never substitutes zero rates — retry or contact support.

* **Empty fills:** Your orders may not have executed, or your filter window excludes them. Check order `status` with `GET /v1/exchange/orders`.

* **`401 Unauthorized`:** Your key lacks the `exchange:read` (or `api:read`) scope.

## What's Next?

Now that you understand fills and fees, you have the full exchange flow:

* [Placing and Managing Orders](https://docs.busha.io/guides/exchange/orders.md)

* [Reading Market Data](https://docs.busha.io/guides/exchange/market-data.md)

* [Understanding the Exchange](https://docs.busha.io/guides/exchange/introduction.md)


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