Agent Network Float API

Reconcile caller-supplied opening and closing cash with every cash-in, cash-out, commission, fee, reversal, and adjustment. The expected closing is the opening balance plus those signed amounts. unexplained_amount is the counted closing minus that expected closing. A supplied expected balance is compared with the same expected closing. A reversal uses the opposite sign of an earlier transaction and its own amount. Amounts are safe integers in one minor unit. No ledger is fetched or stored.

Project caller-supplied outlet cash over the requested days. Historical cash in and cash out are averaged by weekday, and a missing day is not treated as zero. Expected demand replaces historical cash out on the dates or weekdays it names. A closed weekday follows the supplied schedule. The minimum replenishment is the amount that must be added at the start so the balance stays at the outlet minimum. Assumptions name every open day that has neither demand nor history. No ledger is fetched or stored.

Score caller-supplied payment terminals from transaction counts, values, fee rules, revenue shares, and operating costs. Fees may be fixed, a rate in basis points, or tiers by cumulative count. revenue_share_bps is the share of the fee the terminal keeps; omitted means 10000. Each terminal keeps its own currency code. No amount is converted. profit_margin_bps is net profit over revenue in basis points. break_even_count is the transaction count that covers the period costs at the average revenue per transaction from the supplied mix. Ranking is by net profit inside each currency. No ledger is fetched or stored.

Compare caller-supplied transactions with dated agent agreements and commission payments. Expected commission follows the agreement in force on the transaction date: fixed, percent, tiered by cumulative count under that agreement, or capped. transaction_types limit a rule to named types; type-specific agreements beat general ones, then the latest effective_from wins. Payments that name a transaction apply there first. Remaining payments apply FIFO to unpaid expected amounts for that agent. unpaid is expected minus paid. overpaid is paid above expected, including leftover unallocated payments. exposure is unpaid plus overpaid inside each currency. No ledger is fetched or stored.

Propose the cheapest cash transfers that lift every agent to its minimum float after expected demand. projected_before is cash_balance minus expected_demand. Surplus is cash above the minimum; shortage is the shortfall below the minimum. Allowed corridors come only from transfer_costs. transfer_limits cap a corridor. maximum_float caps how much a receiver can take. budget caps total transfer cost. Currencies are never mixed. Allocation is successive shortest-path min-cost flow on the surplus-to-shortage network. The response is a proposal only; no transfer is initiated. feasibility explains when shortages remain.

Calculate the cost of holding cash and electronic float for the supplied period. Funding from funding_rate_bps or funding_costs, replenishment costs, collection costs, and transfer fees are actual expenses. Idle capital from idle_periods and cost_of_capital_bps is an opportunity cost. Rates annualize with annualization_days (default 365): floor(balance * rate_bps * days / (10000 * annualization_days)). Currencies are never mixed. lines and formulas show every intermediate. No ledger is fetched or stored.

Compare caller-supplied outlet productivity inside peer groups of category:currency. Metrics are transactions per active day, revenue per operating hour from commission, average transaction value, commission per transaction, operating cost per transaction, and cash utilization_bps when capacity is supplied. When active_days or operating_hours are present, ranking uses the normalized per-day and per-hour figures instead of raw totals. productivity_score is the sum of competition ranks across available metrics; lower is better. explanations and formulas document every metric. No industry benchmark or external market data is used.

Plan note and coin acquisitions so agents can fulfil caller-supplied cash-in and cash-out amounts. denominations define the only currency systems used; none are assumed. Cash-out and change use largest-first greedy composition against on-hand quantities, preferring notes above minimum_reserves before dipping into reserves. Cash-in adds a greedy composition of tender (defaulting to amount) then dispenses change of tender minus amount. Recommended acquisitions cover shortage compositions and reserve top-ups, capped by replenishment.max_quantity. minimum_cash_required is starting inventory value plus recommended acquisitions. No replenishment is initiated.

Distribute caller-supplied demand across outlets that share the demand location, support the service type, and have operating hours in the interval. Interval capacity is capacity_per_hour times hours, and when staffing is supplied it is also limited by staff_count times staff_capacity_per_hour times hours. Demand is allocated in demand id order to the eligible outlet with the most remaining capacity, then by outlet id. utilization_bps is floor(allocated * 10000 / capacity). capacity_required is the extra allocated volume still needed to reach each supplied fulfil_bps target. No map, geocoder, or demand database is used.

Measure how concentrated caller-supplied agent, outlet, and operator activity is. For transaction_volume, transaction_value, and revenue, compute share_bps, top-n concentration ratios, HHI = floor(sum(share_bps^2) / 10000), and dependency rankings overall, per entity kind, and for each supplied segment dimension/label. Outage scenarios remove unavailable_ids, report affected volume/value/revenue, and compare affected volume with remaining entities' replacement_capacity. No industry HHI threshold is invented or applied.

Classify caller-supplied outlets as active, declining, temporarily inactive, permanently inactive, seasonal, suspended, closed, never active, or not yet active. Open days follow the supplied weekday schedule (or every day when omitted) excluding dates covered by closure, suspension, or seasonal status records. Inactivity uses open days after the last transaction through as_of_date against inactive_days_threshold and permanent_days_threshold. Decline compares recent_days volume with the preceding baseline window. Every outlet row includes evidence strings. No external dormancy threshold is invented.

Build capacitated cash replenishment routes for caller-supplied outlets, depots, and vehicles. Distances prefer directed distances[] entries and otherwise use rounded haversine meters from coordinates, labeled supplied versus straight_line. Routes use nearest-neighbor construction, intra-route 2-opt, and a cheapest-feasible insertion pass. Optional time windows use minutes_per_distance_unit for travel. No mapping, routing, or external optimization API is called.

Reconcile caller-supplied agent transactions against provider settlement statement rows. Confirmed matches require a unique settlement.transaction_id, a unique settlement.reference equal to transaction.settlement_reference, or a unique currency+amount pair. Ambiguous candidates are listed separately and are never treated as confirmed. Amount and fee deltas, missing settlements, unmatched credits, and duplicate reference groups are returned with evidence. No FX conversion is applied.

Audit consecutive agent shifts for cash and electronic-float handovers. Expected balances use opening amounts plus supplied transaction totals and adjustments. Actual balances prefer cash_count and electronic_float_balance when present. Missing handover records between consecutive same-agent shifts, inconsistent handed amounts, and unexplained deltas are reported. No external till balance is invented.

Investigate customer disputes where a charge is claimed against a failed, reversed, or pending agent transaction. Reconstruct a timeline only from supplied lifecycle events, receipts, reversals, and the dispute claim. Report conflicting evidence, missing lifecycle steps, possible duplicate receipts, and reversal inconsistencies. Successful payment is never inferred without a supplied settled fact.

Quantify agent terminal outages using supplied availability intervals, historical day totals, and optional per-hour averages. measured_* values come only from history rows on the outage start date. estimated_lost_* values come only from supplied averages. Restoration priority ranks terminals by estimated lost commission, then value, then transactions, then downtime. No market demand model is invented.

Package caller-supplied agent and operator records into a chronological evidence timeline for financial disputes. Balance transitions are checked against intervening signed amounts. Conflicting references, unexplained balance changes, and missing records for declared dispute categories are labeled separately from verified supplied facts. No liability outcome is assigned and no compensating transactions are invented.