Pricing and FX

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

{
  "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

{
  "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 and Transfers (P2P and B2B).

Getting Started

Guides

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

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

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

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

Linking to Orders and Transfers

​Pricing Profiles (/api/v1/auth/pricing/profiles)

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

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

​App Resolve (POST /api/v1/auth/pricing/resolve)

​Linking to Orders and Transfers

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

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

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

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

Linking to Orders and Transfers