spread_bps vs vs_mid_bps: reading FX quotes in basis points

One basis point (bp) is one hundredth of one percent: 100 bps = 1%. FX is quoted in basis points because the differences that matter are small in percentage terms and large in money terms. On a transfer of 10,000 units, a 50 bps difference is 50 units.

spread_bps is how far a provider's rate sits below the best rate of the same rate_type on that corridor at that moment. The best quote of each kind carries 0.0; everyone else of that kind carries a positive number. It is computed within a rate type on purpose: a retail quote is measured against the best retail quote, an interbank print against the best interbank print, and an official reference is never in the comparison.

Suppose the best retail quote on a corridor is 1,900 and another provider quotes 1,881. Its spread is (1,900 − 1,881) ÷ 1,900 × 10,000 ≈ 100 bps. The number says nothing about whether 1,900 itself is a good price — only that this provider is about 1% behind the leader.

spread_bps = (best_rate_of_same_type − rate) / best_rate_of_same_type × 10,000
0.0 = best of its kind; a corridor with two rate types carries two zeros

vs_mid_bps is how far a rate sits from an independent mid-market reference that Modan sources separately from every provider and refreshes hourly. It is signed: negative means the quote is below the mid (the customer receives less than the reference implies), positive means above. Because the reference is not a provider, this number is the one that answers "is this market expensive right now?".

The mid is crossed through USD from the reference feed, so any fiat pair the feed quotes on both legs has one; a crossed mid is timestamped with its staler leg, never the fresher one. Stablecoins are the exception: no fiat reference feed quotes USDT or USDC, so on those corridors vs_mid_bps is omitted rather than estimated. The mid_source field in every response names the feed.

• Choosing a provider for a transfer: sort by spread_bps within executable quotes, then check the fee — or let the convert endpoint compute the net amount per provider.
• Benchmarking a desk, a bank or a whole corridor: use vs_mid_bps. It is the only measure anchored outside the providers themselves.
• Reading market structure: the gap between the best and the worst executable quote (the *Dispersion* tile on every corridor page) shows how fragmented pricing is on that corridor right now.

Both fields are on every provider entry returned by /rates, /convert, the fetch-* endpoints and the MCP tools, and both columns are on every corridor page. The same definitions apply everywhere; the API documentation has the field-by-field reference.