@spec best_for_side(best_price_result(), :buy | :sell) :: %{
  price: float(),
  exchange: atom() | String.t()
}

Extract the best venue for a given side from a best_price result.

Parameters

• result - Result map from best_price/2 (value)
• side - :buy (best ask) or :sell (best bid) (value)

Returns

Map with :price and :exchange for the requested side (map)

Example

%{exchange: "binance", price: 83512.0}

# descripex:contract
%{
  params: %{
    result: %{description: "Result map from best_price/2", kind: :value},
    side: %{description: ":buy (best ask) or :sell (best bid)", kind: :value}
  },
  returns: %{
    type: :map,
    description: "Map with :price and :exchange for the requested side"
  },
  returns_example: %{exchange: "binance", price: 83512.0}
}

@spec best_price(
  [map()],
  keyword()
) :: best_price_result() | nil

Find best bid/ask across venues from pre-fetched ticker data.

Parameters

• venues - List of maps with :exchange, :bid, and :ask fields. Optional :group is a caller-declared comparability key (any term): venues sharing a :group are declared comparable for arbitrage. A venue omitting :group is comparable only with itself — never inferred from the exchange name or symbol. (exchange_data)
• opts - Options: min_venues (minimum valid venues, default 1) (default: [], value)

Returns

Map with :best_bid, :best_ask, :spread, :spread_bps, :mid, :arb_opportunity, :arb_status (:none | :comparable | :incomparable), :venue_count, :venues — or nil if insufficient valid venues. arb_opportunity is true only when the crossing venues are declared comparable; a cross between incomparable venues sets arb_status :incomparable with arb_opportunity false. (map)

Example

%{
  mid: 83511.0,
  venues: [%{exchange: "bybit", ask: 83512.0, bid: 83510.0}],
  best_bid: %{exchange: "bybit", price: 83510.0},
  best_ask: %{exchange: "binance", price: 83512.0},
  spread: 2.0,
  venue_count: 2,
  arb_status: :none,
  spread_bps: 0.24,
  arb_opportunity: false
}

Composes With

• best_for_side

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: min_venues (minimum valid venues, default 1)",
      kind: :value
    },
    venues: %{
      description: "List of maps with :exchange, :bid, and :ask fields. Optional :group is a caller-declared comparability key (any term): venues sharing a :group are declared comparable for arbitrage. A venue omitting :group is comparable only with itself — never inferred from the exchange name or symbol.",
      source: "multiple fetch_ticker calls or from_multi/1",
      kind: :exchange_data
    }
  },
  returns: %{
    type: :map,
    description: "Map with :best_bid, :best_ask, :spread, :spread_bps, :mid, :arb_opportunity, :arb_status (:none | :comparable | :incomparable), :venue_count, :venues — or nil if insufficient valid venues. arb_opportunity is true only when the crossing venues are declared comparable; a cross between incomparable venues sets arb_status :incomparable with arb_opportunity false."
  },
  returns_example: %{
    mid: 83511.0,
    venues: [%{exchange: "bybit", ask: 83512.0, bid: 83510.0}],
    best_bid: %{exchange: "bybit", price: 83510.0},
    best_ask: %{exchange: "binance", price: 83512.0},
    spread: 2.0,
    venue_count: 2,
    arb_status: :none,
    spread_bps: 0.24,
    arb_opportunity: false
  },
  composes_with: [:best_for_side]
}

@spec from_multi(%{required(map() | module()) => map()}) :: [map()]

Convert Bourse.Multi success map to venue list for best_price/2.

Parameters

• successes - Map of %{%Bourse.Exchange{} => %Bourse.Ticker{}} from Bourse.Multi.successes/1. A ticker value carrying a caller-supplied :group key has it carried through to the venue so best_price/2 can judge cross-venue comparability. (exchange_data)

Returns

List of maps with :exchange (string), :bid, :ask, and optional :group fields (list)

Example

[1.0, 0.9]

Composes With

• best_price

# descripex:contract
%{
  params: %{
    successes: %{
      description: "Map of %{%Bourse.Exchange{} => %Bourse.Ticker{}} from Bourse.Multi.successes/1. A ticker value carrying a caller-supplied :group key has it carried through to the venue so best_price/2 can judge cross-venue comparability.",
      source: "Bourse.Multi.successes(Bourse.Multi.fetch_tickers(...))",
      kind: :exchange_data
    }
  },
  returns: %{
    type: :list,
    description: "List of maps with :exchange (string), :bid, :ask, and optional :group fields"
  },
  returns_example: [1.0, 0.9],
  composes_with: [:best_price]
}

@spec split_order(:buy | :sell | String.t(), map(), [map()], keyword()) ::
  {:ok, split_plan()} | {:error, split_error()}

Build a deterministic, non-executing split plan across venue liquidity snapshots.

Walks available liquidity in fee-adjusted price-priority order (lowest net unit cost for buys, highest net unit proceeds for sells). Ties break by exchange name ascending, then input index. Each child respects liquidity, optional price limit, lot size (floor), minimum amount/notional, fee rate, and venue quantity/notional caps.

Returns a plan only — never places, times, cancels, or tracks live orders.