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

# Pricing and FX

> Pricing Profiles, FX Quotes, and Quote-Backed Commercial Snapshots for Orders and Transfers

EmaalCoin ties fiat legs and fees to **stored pricing** so operations stay auditable. Two building blocks work together:

## Pricing Profiles (`/api/v1/auth/pricing/profiles`)

A **pricing Profile** describes *how* you charge (fees, spread behavior, settlement side) for a **flow**:

| `flow_type` | Use case                                                 |
| ----------- | -------------------------------------------------------- |
| `onramp`    | Fiat → crypto (e.g. Customer buys USDT)                  |
| `offramp`   | Crypto → fiat (e.g. Customer sells USDT)                 |
| `p2p`       | Internal P2P USDT transfers with optional fiat reference |
| `b2b`       | Vendor-to-vendor B2B transfers                           |
| `b2b2c`     | Extended B2B2C flows (where configured)                  |

You also set **`asset`** (typically `USDT`), optional **`network`** (`tron` or `ethereum`), optional **`fiat_currency`** when the profile is scoped to a corridor, and optional **`user_role`** for role-segmented pricing. **`fee_type`** is one of `none`, `fixed`, `percentage`, or `hybrid`, with BPS and min/max as needed.

> **Note:** Creating and updating pricing profiles is **admin-only** (`POST`, `GET`, `PUT`, active flag endpoints).

## FX Rate Quotes (`/api/v1/auth/pricing/fx-quotes`)

An **FX Quote** stores **`reference_rate`** and **`applied_rate`** (or derives applied rate from **`spread_bps`**) for a given flow, asset, and **`fiat_currency`**. Use **`expires_at`** so stale quotes fail validation when building snapshots.

List and fetch by ID for audit. Use **`GET .../fx-quotes/active`** when you need the current active quote for a flow/asset/fiat (+ optional network).

## Live Quote Tool (`POST /api/v1/auth/pricing/quote`)

Combines the **active pricing profile** and **active FX** for a hypothetical amount (`amount_in` + `amount_in_type` of `fiat` or `crypto`) - useful for admin dashboards and sanity checks before placing orders.

## App Resolve (`POST /api/v1/auth/pricing/resolve`)

For app clients, use **Resolve** to get the correct **`pricing_profile_id`** and **`fx_rate_quote_id`** for the current flow context (flow/network/asset/fiat/amount), plus a computed commercial preview (fees and gross/net amounts) before creating the order.

**B2B OTC** (bank deposit or withdrawal lanes with **`otc_type`** on profiles and FX quotes) uses **`POST /api/v1/auth/pricing/resolve-otc`** instead, so OTC pricing does not collide with generic **`b2b`** resolve.

**`fiat_currency`** values in pricing resolve (including **resolve-otc**) must reference an **active** code from the shared **`fiat_currencies`** catalog. Use **`GET /api/v1/auth/fiat-currencies`** — the same endpoint other products use for fiat pickers.

**Example request**

```json theme={null}
{
  "flow_type": "onramp",
  "network": "tron",
  "asset": "USDT",
  "fiat_currency": "KES",
  "amount_in": "13000.00",
  "amount_in_type": "fiat",
  "vendor_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "offer_id": "99999999-8888-7777-6666-555555555555",
  "order_type": "ON_RAMP_BUY"
}
```

**Example response**

```json theme={null}
{
  "pricing_profile_id": "22222222-3333-4444-5555-666666666666",
  "fx_rate_quote_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "flow_type": "onramp",
  "network": "tron",
  "asset": "USDT",
  "fiat_currency": "KES",
  "amount_in": "13000.00",
  "amount_in_type": "fiat",
  "reference_fx_rate": "129.50000000",
  "applied_fx_rate": "130.10000000",
  "spread_bps": 46,
  "fees": {
    "fixed_fee": "20.00000000",
    "fixed_fee_currency": "KES",
    "percentage_fee_bps": 150,
    "percentage_fee_amount": "195.00000000",
    "total_fee_amount": "215.00000000",
    "fee_currency": "KES"
  },
  "amounts": {
    "gross_fiat_amount": "13000.00000000",
    "net_fiat_amount": "12785.00000000",
    "gross_crypto_amount": "99.92313605",
    "net_crypto_amount": "98.27056111"
  },
  "quoted_at": "2026-04-21T13:38:20Z",
  "expires_at": "2026-04-21T13:53:20Z"
}
```

## Linking to Orders and Transfers

When creating **`POST /api/v1/auth/orders`** or transfer endpoints, you pass:

* `pricing_profile_id`
* `fx_rate_quote_id`

together with amounts. The API builds a **pricing snapshot** (reference/applied rate, fees, net/gross lines) when both IDs are valid and consistent with order/transfer type, asset, fiat, and network rules.

Partial pricing fields result in **`400`** - either supply all commercial fields required by the endpoint or omit pricing entirely where allowed.

See also [Orders and payments](/guides/orders-and-payments) and [Transfers (P2P and B2B)](/guides/transfers-p2p-b2b).