# Agent Network Float API

> Reconcile caller-supplied agent cash balances against cash movements, commissions, fees, reversals, and adjustments. Project when an outlet runs out of physical cash from its history, demand, schedule, and replenishment. Score terminal profitability from fee rules, revenue shares, and operating costs. Find commission underpayments, overpayments, and missed entitlements from dated agreements. Propose minimum-cost float transfers between agents. Calculate the actual and opportunity cost of holding float. Benchmark outlet productivity inside caller-supplied peer groups. Optimize banknote and coin composition for expected cash demand. Allocate demand across outlets by processing capacity. Measure concentration risk across agents, outlets, and operators. Detect dormant or declining outlets from supplied activity history. Plan cash replenishment vehicle routes from supplied coordinates and distances. Reconcile provider settlements, audit shift handovers, assess failed-transaction disputes, quantify terminal downtime, and package agent dispute evidence.

Each POST has a fixed USDC price on Base, paid with the x402 exact scheme. The request is validated first, and payment settles only after a successful (2xx) result. Failed calls are not charged.

1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.
2. A valid unpaid call returns 402 with the exact amount and payTo.
3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.

- Product: https://www.brainiac.software/api/agent-networks
- Docs: https://www.brainiac.software/api/agent-networks/docs
- OpenAPI: https://www.brainiac.software/api/agent-networks/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/agent-networks/float-loss-attribution

$0.04 USDC. 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.

Inputs: agents, transactions

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-float-loss-attribution

Example request:

```json
{
  "agents": [
    {
      "id": "ag-1",
      "opening_balance": 10000,
      "closing_balance": 14000,
      "expected_balance": 15000
    },
    {
      "id": "ag-2",
      "opening_balance": 8000,
      "closing_balance": 9000
    }
  ],
  "transactions": [
    {
      "id": "c1",
      "agent_id": "ag-1",
      "category": "cash_in",
      "amount": 5000
    },
    {
      "id": "c2",
      "agent_id": "ag-1",
      "category": "cash_out",
      "amount": 2000
    },
    {
      "id": "c3",
      "agent_id": "ag-1",
      "category": "commission",
      "amount": 300
    },
    {
      "id": "c4",
      "agent_id": "ag-1",
      "category": "fee",
      "amount": 100
    },
    {
      "id": "c5",
      "agent_id": "ag-1",
      "category": "reversal",
      "amount": 2000,
      "reverses": "c2"
    },
    {
      "id": "c6",
      "agent_id": "ag-1",
      "category": "adjustment",
      "amount": -500
    },
    {
      "id": "c7",
      "agent_id": "ag-2",
      "category": "cash_in",
      "amount": 1000
    }
  ]
}
```

Example response:

```json
{
  "expected_closing_balances": [
    {
      "agent_id": "ag-1",
      "opening_balance": 10000,
      "expected_closing_balance": 14700
    },
    {
      "agent_id": "ag-2",
      "opening_balance": 8000,
      "expected_closing_balance": 9000
    }
  ],
  "unexplained_discrepancies": [
    {
      "agent_id": "ag-1",
      "opening_balance": 10000,
      "expected_closing_balance": 14700,
      "closing_balance": 14000,
      "unexplained_amount": -700,
      "supplied_expected_balance": 15000,
      "supplied_variance": 300
    }
  ],
  "discrepancy_breakdown": [
    {
      "agent_id": "ag-1",
      "category": "cash_in",
      "signed_amount": 5000,
      "transaction_ids": [
        "c1"
      ]
    },
    {
      "agent_id": "ag-1",
      "category": "cash_out",
      "signed_amount": -2000,
      "transaction_ids": [
        "c2"
      ]
    },
    {
      "agent_id": "ag-1",
      "category": "commission",
      "signed_amount": 300,
      "transaction_ids": [
        "c3"
      ]
    },
    {
      "agent_id": "ag-1",
      "category": "fee",
      "signed_amount": -100,
      "transaction_ids": [
        "c4"
      ]
    },
    {
      "agent_id": "ag-1",
      "category": "reversal",
      "signed_amount": 2000,
      "transaction_ids": [
        "c5"
      ]
    },
    {
      "agent_id": "ag-1",
      "category": "adjustment",
      "signed_amount": -500,
      "transaction_ids": [
        "c6"
      ]
    }
  ],
  "transactions": [
    {
      "id": "c1",
      "agent_id": "ag-1",
      "category": "cash_in",
      "amount": 5000,
      "signed_amount": 5000
    },
    {
      "id": "c2",
      "agent_id": "ag-1",
      "category": "cash_out",
      "amount": 2000,
      "signed_amount": -2000
    },
    {
      "id": "c3",
      "agent_id": "ag-1",
      "category": "commission",
      "amount": 300,
      "signed_amount": 300
    },
    {
      "id": "c4",
      "agent_id": "ag-1",
      "category": "fee",
      "amount": 100,
      "signed_amount": -100
    },
    {
      "id": "c5",
      "agent_id": "ag-1",
      "category": "reversal",
      "amount": 2000,
      "signed_amount": 2000,
      "reverses": "c2"
    },
    {
      "id": "c6",
      "agent_id": "ag-1",
      "category": "adjustment",
      "amount": -500,
      "signed_amount": -500
    }
  ]
}
```

### POST /api/v1/agent-networks/cash-shortage-analysis

$0.04 USDC. 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.

Inputs: start_date, period_days, outlets, transactions?, demand?, schedules?, replenishment?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-cash-shortage-analysis

Example request:

```json
{
  "start_date": "2026-11-09",
  "period_days": 3,
  "outlets": [
    {
      "id": "shop-1",
      "cash_balance": 300,
      "minimum_balance": 200
    },
    {
      "id": "shop-2",
      "cash_balance": 5000
    }
  ],
  "transactions": [
    {
      "id": "h1",
      "outlet_id": "shop-1",
      "date": "2026-11-02",
      "direction": "out",
      "amount": 400
    },
    {
      "id": "h2",
      "outlet_id": "shop-1",
      "date": "2026-11-03",
      "direction": "out",
      "amount": 100
    }
  ],
  "demand": [
    {
      "outlet_id": "shop-1",
      "weekday": 1,
      "cash_out": 600
    }
  ],
  "schedules": [
    {
      "outlet_id": "shop-1",
      "weekday": 1
    },
    {
      "outlet_id": "shop-1",
      "weekday": 2
    },
    {
      "outlet_id": "shop-1",
      "weekday": 3
    }
  ],
  "replenishment": [
    {
      "outlet_id": "shop-1",
      "amount": 500,
      "every_days": 2
    }
  ]
}
```

Example response:

```json
{
  "projected_balances": [
    {
      "outlet_id": "shop-1",
      "date": "2026-11-09",
      "cash_balance": 200,
      "cash_in": 0,
      "cash_out": 600,
      "replenishment": 500
    },
    {
      "outlet_id": "shop-1",
      "date": "2026-11-10",
      "cash_balance": 100,
      "cash_in": 0,
      "cash_out": 100,
      "replenishment": 0
    },
    {
      "outlet_id": "shop-1",
      "date": "2026-11-11",
      "cash_balance": 350,
      "cash_in": 0,
      "cash_out": 250,
      "replenishment": 500
    },
    {
      "outlet_id": "shop-2",
      "date": "2026-11-09",
      "cash_balance": 5000,
      "cash_in": 0,
      "cash_out": 0,
      "replenishment": 0
    },
    {
      "outlet_id": "shop-2",
      "date": "2026-11-10",
      "cash_balance": 5000,
      "cash_in": 0,
      "cash_out": 0,
      "replenishment": 0
    },
    {
      "outlet_id": "shop-2",
      "date": "2026-11-11",
      "cash_balance": 5000,
      "cash_in": 0,
      "cash_out": 0,
      "replenishment": 0
    }
  ],
  "shortage_dates": [
    {
      "outlet_id": "shop-1",
      "date": "2026-11-10",
      "shortage_amount": 100
    }
  ],
  "affected_outlets": [
    {
      "outlet_id": "shop-1",
      "first_shortage_date": "2026-11-10",
      "shortage_amount": 100
    }
  ],
  "minimum_replenishment": [
    {
      "outlet_id": "shop-1",
      "amount": 100
    },
    {
      "outlet_id": "shop-2",
      "amount": 0
    }
  ],
  "assumptions": [
    {
      "outlet_id": "shop-1",
      "assumption": "No expected demand was supplied for Wednesday. That day has no historical cash movement, so cash out uses the average of the historical days that were supplied."
    },
    {
      "outlet_id": "shop-2",
      "assumption": "No operating schedule was supplied. The outlet is projected as open every day."
    },
    {
      "outlet_id": "shop-2",
      "assumption": "No historical transactions and no expected demand were supplied. The balance changes only when a replenishment is supplied."
    }
  ]
}
```

### POST /api/v1/agent-networks/terminal-profitability

$0.04 USDC. 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.

Inputs: terminals, transaction_types, transactions

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-terminal-profitability

Example request:

```json
{
  "terminals": [
    {
      "id": "t1",
      "currency": "USD",
      "costs": {
        "rent": 200,
        "equipment": 50,
        "connectivity": 30,
        "maintenance": 20,
        "other": 10
      }
    },
    {
      "id": "t2",
      "currency": "USD",
      "costs": {
        "rent": 100,
        "connectivity": 20
      }
    },
    {
      "id": "t3",
      "currency": "EUR",
      "costs": {
        "rent": 150
      }
    }
  ],
  "transaction_types": [
    {
      "id": "cash_in",
      "fee": {
        "kind": "fixed",
        "amount": 50
      },
      "revenue_share_bps": 8000
    },
    {
      "id": "bill_pay",
      "fee": {
        "kind": "percent",
        "rate_bps": 150
      },
      "revenue_share_bps": 10000
    },
    {
      "id": "transfer",
      "fee": {
        "kind": "tiered",
        "tiers": [
          {
            "up_to": 10,
            "amount": 100
          },
          {
            "amount": 40,
            "rate_bps": 50
          }
        ]
      }
    }
  ],
  "transactions": [
    {
      "terminal_id": "t1",
      "type_id": "cash_in",
      "count": 20,
      "value": 400000
    },
    {
      "terminal_id": "t1",
      "type_id": "bill_pay",
      "count": 5,
      "value": 100000
    },
    {
      "terminal_id": "t1",
      "type_id": "transfer",
      "count": 12,
      "value": 240000
    },
    {
      "terminal_id": "t2",
      "type_id": "cash_in",
      "count": 4,
      "value": 80000
    },
    {
      "terminal_id": "t3",
      "type_id": "bill_pay",
      "count": 10,
      "value": 50000
    }
  ]
}
```

Example response:

```json
{
  "revenue_by_type": [
    {
      "terminal_id": "t1",
      "type_id": "cash_in",
      "count": 20,
      "value": 400000,
      "fee_before_share": 1000,
      "revenue_share_bps": 8000,
      "revenue": 800,
      "fee_steps": [
        {
          "step": "fixed",
          "count": 20,
          "amount": 50,
          "fee": 1000
        }
      ]
    },
    {
      "terminal_id": "t1",
      "type_id": "bill_pay",
      "count": 5,
      "value": 100000,
      "fee_before_share": 1500,
      "revenue_share_bps": 10000,
      "revenue": 1500,
      "fee_steps": [
        {
          "step": "percent",
          "value": 100000,
          "rate_bps": 150,
          "fee": 1500
        }
      ]
    },
    {
      "terminal_id": "t1",
      "type_id": "transfer",
      "count": 12,
      "value": 240000,
      "fee_before_share": 1280,
      "revenue_share_bps": 10000,
      "revenue": 1280,
      "fee_steps": [
        {
          "step": "tier",
          "index": 0,
          "count": 10,
          "value": 200000,
          "amount": 100,
          "rate_bps": 0,
          "fee": 1000
        },
        {
          "step": "tier",
          "index": 1,
          "count": 2,
          "value": 40000,
          "amount": 40,
          "rate_bps": 50,
          "fee": 280
        }
      ]
    },
    {
      "terminal_id": "t2",
      "type_id": "cash_in",
      "count": 4,
      "value": 80000,
      "fee_before_share": 200,
      "revenue_share_bps": 8000,
      "revenue": 160,
      "fee_steps": [
        {
          "step": "fixed",
          "count": 4,
          "amount": 50,
          "fee": 200
        }
      ]
    },
    {
      "terminal_id": "t3",
      "type_id": "bill_pay",
      "count": 10,
      "value": 50000,
      "fee_before_share": 750,
      "revenue_share_bps": 10000,
      "revenue": 750,
      "fee_steps": [
        {
          "step": "percent",
          "value": 50000,
          "rate_bps": 150,
          "fee": 750
        }
      ]
    }
  ],
  "total_revenue": [
    {
      "terminal_id": "t1",
      "currency": "USD",
      "amount": 3580
    },
    {
      "terminal_id": "t2",
      "currency": "USD",
      "amount": 160
    },
    {
      "terminal_id": "t3",
      "currency": "EUR",
      "amount": 750
    }
  ],
  "operating_costs": [
    {
      "terminal_id": "t1",
      "currency": "USD",
      "rent": 200,
      "equipment": 50,
      "connectivity": 30,
      "maintenance": 20,
      "other": 10,
      "total": 310
    },
    {
      "terminal_id": "t2",
      "currency": "USD",
      "rent": 100,
      "equipment": 0,
      "connectivity": 20,
      "maintenance": 0,
      "other": 0,
      "total": 120
    },
    {
      "terminal_id": "t3",
      "currency": "EUR",
      "rent": 150,
      "equipment": 0,
      "connectivity": 0,
      "maintenance": 0,
      "other": 0,
      "total": 150
    }
  ],
  "net_profit": [
    {
      "terminal_id": "t1",
      "currency": "USD",
      "amount": 3270,
      "profit_margin_bps": 9134,
      "transaction_count": 37,
      "revenue_per_transaction": 96,
      "break_even_count": 4
    },
    {
      "terminal_id": "t2",
      "currency": "USD",
      "amount": 40,
      "profit_margin_bps": 2500,
      "transaction_count": 4,
      "revenue_per_transaction": 40,
      "break_even_count": 3
    },
    {
      "terminal_id": "t3",
      "currency": "EUR",
      "amount": 600,
      "profit_margin_bps": 8000,
      "transaction_count": 10,
      "revenue_per_transaction": 75,
      "break_even_count": 2
    }
  ],
  "ranking": [
    {
      "terminal_id": "t3",
      "currency": "EUR",
      "net_profit": 600,
      "rank": 1
    },
    {
      "terminal_id": "t1",
      "currency": "USD",
      "net_profit": 3270,
      "rank": 1
    },
    {
      "terminal_id": "t2",
      "currency": "USD",
      "net_profit": 40,
      "rank": 2
    }
  ]
}
```

### POST /api/v1/agent-networks/commission-leakage

$0.04 USDC. 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.

Inputs: agents, rules, agreements, transactions, payments

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-commission-leakage

Example request:

```json
{
  "agents": [
    {
      "id": "ag-1",
      "currency": "USD"
    },
    {
      "id": "ag-2",
      "currency": "USD"
    }
  ],
  "rules": [
    {
      "id": "r-fixed",
      "kind": "fixed",
      "amount": 100
    },
    {
      "id": "r-percent",
      "kind": "percent",
      "rate_bps": 200,
      "transaction_types": [
        "cash_in"
      ]
    },
    {
      "id": "r-tier",
      "kind": "tiered",
      "tiers": [
        {
          "up_to": 2,
          "amount": 150
        },
        {
          "amount": 50,
          "rate_bps": 100
        }
      ]
    },
    {
      "id": "r-cap",
      "kind": "capped",
      "rate_bps": 500,
      "cap": 300,
      "transaction_types": [
        "bill_pay"
      ]
    }
  ],
  "agreements": [
    {
      "id": "a1",
      "agent_id": "ag-1",
      "rule_id": "r-percent",
      "effective_from": "2026-01-01",
      "effective_to": "2026-01-31"
    },
    {
      "id": "a2",
      "agent_id": "ag-1",
      "rule_id": "r-fixed",
      "effective_from": "2026-02-01"
    },
    {
      "id": "a3",
      "agent_id": "ag-1",
      "rule_id": "r-cap",
      "effective_from": "2026-01-01"
    },
    {
      "id": "a4",
      "agent_id": "ag-2",
      "rule_id": "r-tier",
      "effective_from": "2026-01-01"
    }
  ],
  "transactions": [
    {
      "id": "t1",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "amount": 100000,
      "date": "2026-01-10"
    },
    {
      "id": "t2",
      "agent_id": "ag-1",
      "type_id": "bill_pay",
      "amount": 100000,
      "date": "2026-01-15"
    },
    {
      "id": "t3",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "amount": 50000,
      "date": "2026-02-05"
    },
    {
      "id": "t4",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "amount": 20000,
      "date": "2026-01-05"
    },
    {
      "id": "t5",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "amount": 20000,
      "date": "2026-01-06"
    },
    {
      "id": "t6",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "amount": 20000,
      "date": "2026-01-07"
    }
  ],
  "payments": [
    {
      "id": "p1",
      "agent_id": "ag-1",
      "amount": 1500,
      "date": "2026-01-20",
      "transaction_id": "t1"
    },
    {
      "id": "p2",
      "agent_id": "ag-1",
      "amount": 100,
      "date": "2026-01-25"
    },
    {
      "id": "p3",
      "agent_id": "ag-2",
      "amount": 150,
      "date": "2026-01-10",
      "transaction_id": "t4"
    },
    {
      "id": "p4",
      "agent_id": "ag-2",
      "amount": 500,
      "date": "2026-01-20"
    }
  ]
}
```

Example response:

```json
{
  "expected_commissions": [
    {
      "transaction_id": "t4",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "date": "2026-01-05",
      "agreement_id": "a4",
      "rule_id": "r-tier",
      "expected": 150,
      "status": "entitled",
      "steps": [
        {
          "step": "tier",
          "index": 0,
          "position": 1,
          "value": 20000,
          "amount": 150,
          "rate_bps": 0,
          "commission": 150
        }
      ],
      "position": 1
    },
    {
      "transaction_id": "t5",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "date": "2026-01-06",
      "agreement_id": "a4",
      "rule_id": "r-tier",
      "expected": 150,
      "status": "entitled",
      "steps": [
        {
          "step": "tier",
          "index": 0,
          "position": 2,
          "value": 20000,
          "amount": 150,
          "rate_bps": 0,
          "commission": 150
        }
      ],
      "position": 2
    },
    {
      "transaction_id": "t6",
      "agent_id": "ag-2",
      "type_id": "transfer",
      "date": "2026-01-07",
      "agreement_id": "a4",
      "rule_id": "r-tier",
      "expected": 250,
      "status": "entitled",
      "steps": [
        {
          "step": "tier",
          "index": 1,
          "position": 3,
          "value": 20000,
          "amount": 50,
          "rate_bps": 100,
          "commission": 250
        }
      ],
      "position": 3
    },
    {
      "transaction_id": "t1",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-01-10",
      "agreement_id": "a1",
      "rule_id": "r-percent",
      "expected": 2000,
      "status": "entitled",
      "steps": [
        {
          "step": "percent",
          "value": 100000,
          "rate_bps": 200,
          "amount": 2000
        }
      ],
      "position": 1
    },
    {
      "transaction_id": "t2",
      "agent_id": "ag-1",
      "type_id": "bill_pay",
      "date": "2026-01-15",
      "agreement_id": "a3",
      "rule_id": "r-cap",
      "expected": 300,
      "status": "entitled",
      "steps": [
        {
          "step": "percent",
          "value": 100000,
          "rate_bps": 500,
          "amount": 5000
        },
        {
          "step": "cap",
          "before": 5000,
          "cap": 300,
          "amount": 300
        }
      ],
      "position": 1
    },
    {
      "transaction_id": "t3",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-02-05",
      "agreement_id": "a2",
      "rule_id": "r-fixed",
      "expected": 100,
      "status": "entitled",
      "steps": [
        {
          "step": "fixed",
          "amount": 100
        }
      ],
      "position": 1
    }
  ],
  "payments_applied": [
    {
      "payment_id": "p3",
      "agent_id": "ag-2",
      "amount": 150,
      "transaction_id": "t4",
      "allocation": "direct"
    },
    {
      "payment_id": "p1",
      "agent_id": "ag-1",
      "amount": 1500,
      "transaction_id": "t1",
      "allocation": "direct"
    },
    {
      "payment_id": "p4",
      "agent_id": "ag-2",
      "amount": 150,
      "transaction_id": "t5",
      "allocation": "fifo"
    },
    {
      "payment_id": "p4",
      "agent_id": "ag-2",
      "amount": 250,
      "transaction_id": "t6",
      "allocation": "fifo"
    },
    {
      "payment_id": "p4",
      "agent_id": "ag-2",
      "amount": 100,
      "allocation": "unallocated"
    },
    {
      "payment_id": "p2",
      "agent_id": "ag-1",
      "amount": 100,
      "transaction_id": "t1",
      "allocation": "fifo"
    }
  ],
  "discrepancies": [
    {
      "transaction_id": "t1",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-01-10",
      "agreement_id": "a1",
      "rule_id": "r-percent",
      "expected": 2000,
      "paid": 1600,
      "unpaid": 400,
      "overpaid": 0,
      "kind": "underpayment"
    },
    {
      "transaction_id": "t2",
      "agent_id": "ag-1",
      "type_id": "bill_pay",
      "date": "2026-01-15",
      "agreement_id": "a3",
      "rule_id": "r-cap",
      "expected": 300,
      "paid": 0,
      "unpaid": 300,
      "overpaid": 0,
      "kind": "missed"
    },
    {
      "transaction_id": "t3",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-02-05",
      "agreement_id": "a2",
      "rule_id": "r-fixed",
      "expected": 100,
      "paid": 0,
      "unpaid": 100,
      "overpaid": 0,
      "kind": "missed"
    },
    {
      "agent_id": "ag-2",
      "payment_id": "p4",
      "expected": 0,
      "paid": 100,
      "unpaid": 0,
      "overpaid": 100,
      "kind": "overpayment"
    }
  ],
  "responsible_transactions": [
    {
      "transaction_id": "t1",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-01-10",
      "agreement_id": "a1",
      "rule_id": "r-percent",
      "expected": 2000,
      "paid": 1600,
      "unpaid": 400,
      "overpaid": 0,
      "kind": "underpayment"
    },
    {
      "transaction_id": "t2",
      "agent_id": "ag-1",
      "type_id": "bill_pay",
      "date": "2026-01-15",
      "agreement_id": "a3",
      "rule_id": "r-cap",
      "expected": 300,
      "paid": 0,
      "unpaid": 300,
      "overpaid": 0,
      "kind": "missed"
    },
    {
      "transaction_id": "t3",
      "agent_id": "ag-1",
      "type_id": "cash_in",
      "date": "2026-02-05",
      "agreement_id": "a2",
      "rule_id": "r-fixed",
      "expected": 100,
      "paid": 0,
      "unpaid": 100,
      "overpaid": 0,
      "kind": "missed"
    }
  ],
  "by_agent": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "expected": 2400,
      "paid": 1600,
      "unpaid": 800,
      "overpaid": 0,
      "exposure": 800
    },
    {
      "agent_id": "ag-2",
      "currency": "USD",
      "expected": 550,
      "paid": 650,
      "unpaid": 0,
      "overpaid": 100,
      "exposure": 100
    }
  ],
  "total_financial_exposure": [
    {
      "currency": "USD",
      "unpaid": 800,
      "overpaid": 100,
      "exposure": 900
    }
  ]
}
```

### POST /api/v1/agent-networks/float-rebalancing

$0.04 USDC. 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.

Inputs: agents, transfer_costs, transfer_limits?, budget?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-float-rebalancing

Example request:

```json
{
  "agents": [
    {
      "id": "ag-1",
      "currency": "USD",
      "cash_balance": 5000,
      "minimum_float": 2000,
      "maximum_float": 8000,
      "expected_demand": 500
    },
    {
      "id": "ag-2",
      "currency": "USD",
      "cash_balance": 500,
      "minimum_float": 2000,
      "expected_demand": 200
    },
    {
      "id": "ag-3",
      "currency": "USD",
      "cash_balance": 9000,
      "minimum_float": 1000,
      "maximum_float": 7000
    },
    {
      "id": "ag-4",
      "currency": "EUR",
      "cash_balance": 100,
      "minimum_float": 500
    },
    {
      "id": "ag-5",
      "currency": "EUR",
      "cash_balance": 2000,
      "minimum_float": 500
    }
  ],
  "transfer_costs": [
    {
      "from_agent_id": "ag-1",
      "to_agent_id": "ag-2",
      "cost_per_unit": 2
    },
    {
      "from_agent_id": "ag-3",
      "to_agent_id": "ag-2",
      "cost_per_unit": 1
    },
    {
      "from_agent_id": "ag-3",
      "to_agent_id": "ag-1",
      "cost_per_unit": 5
    },
    {
      "from_agent_id": "ag-5",
      "to_agent_id": "ag-4",
      "cost_per_unit": 1
    }
  ],
  "transfer_limits": [
    {
      "from_agent_id": "ag-3",
      "to_agent_id": "ag-2",
      "max_amount": 1000
    }
  ],
  "budget": 5000
}
```

Example response:

```json
{
  "proposed_transfers": [
    {
      "from_agent_id": "ag-1",
      "to_agent_id": "ag-2",
      "amount": 700,
      "cost_per_unit": 2,
      "cost": 1400
    },
    {
      "from_agent_id": "ag-3",
      "to_agent_id": "ag-2",
      "amount": 1000,
      "cost_per_unit": 1,
      "cost": 1000
    },
    {
      "from_agent_id": "ag-5",
      "to_agent_id": "ag-4",
      "amount": 400,
      "cost_per_unit": 1,
      "cost": 400
    }
  ],
  "projected_balances": [
    {
      "agent_id": "ag-4",
      "currency": "EUR",
      "cash_balance": 100,
      "expected_demand": 0,
      "projected_before": 100,
      "projected_after": 500,
      "minimum_float": 500
    },
    {
      "agent_id": "ag-5",
      "currency": "EUR",
      "cash_balance": 2000,
      "expected_demand": 0,
      "projected_before": 2000,
      "projected_after": 1600,
      "minimum_float": 500
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "cash_balance": 5000,
      "expected_demand": 500,
      "projected_before": 4500,
      "projected_after": 3800,
      "minimum_float": 2000,
      "maximum_float": 8000
    },
    {
      "agent_id": "ag-2",
      "currency": "USD",
      "cash_balance": 500,
      "expected_demand": 200,
      "projected_before": 300,
      "projected_after": 2000,
      "minimum_float": 2000
    },
    {
      "agent_id": "ag-3",
      "currency": "USD",
      "cash_balance": 9000,
      "expected_demand": 0,
      "projected_before": 9000,
      "projected_after": 8000,
      "minimum_float": 1000,
      "maximum_float": 7000
    }
  ],
  "remaining_shortages": [],
  "excess_balances": [
    {
      "agent_id": "ag-5",
      "currency": "EUR",
      "amount": 1100,
      "above_maximum": 0
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "amount": 1800,
      "above_maximum": 0
    },
    {
      "agent_id": "ag-3",
      "currency": "USD",
      "amount": 7000,
      "above_maximum": 1000
    }
  ],
  "total_transfer_cost": 2800,
  "feasibility": [
    {
      "currency": "EUR",
      "feasible": true,
      "detail": "Every shortage in this currency is covered at minimum total transfer cost under the supplied corridors, limits, and budget. No transfer was initiated."
    },
    {
      "currency": "USD",
      "feasible": true,
      "detail": "Every shortage in this currency is covered at minimum total transfer cost under the supplied corridors, limits, and budget. No transfer was initiated."
    }
  ]
}
```

### POST /api/v1/agent-networks/liquidity-cost-analysis

$0.04 USDC. 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.

Inputs: period_days, annualization_days?, cost_of_capital_bps?, agents, funding_costs?, replenishments?, collections?, transfer_fees?, idle_periods?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-liquidity-cost-analysis

Example request:

```json
{
  "period_days": 30,
  "annualization_days": 365,
  "cost_of_capital_bps": 1200,
  "agents": [
    {
      "id": "ag-1",
      "currency": "USD",
      "cash_float": 100000,
      "electronic_float": 50000,
      "transaction_count": 200,
      "funding_rate_bps": 800
    },
    {
      "id": "ag-2",
      "currency": "USD",
      "cash_float": 20000,
      "electronic_float": 10000,
      "transaction_count": 50,
      "cost_of_capital_bps": 1000
    },
    {
      "id": "ag-3",
      "currency": "EUR",
      "cash_float": 80000,
      "electronic_float": 0,
      "transaction_count": 100,
      "funding_rate_bps": 600
    }
  ],
  "funding_costs": [
    {
      "agent_id": "ag-2",
      "amount": 25
    }
  ],
  "replenishments": [
    {
      "agent_id": "ag-1",
      "amount": 40000,
      "cost": 150
    }
  ],
  "collections": [
    {
      "agent_id": "ag-1",
      "amount": 20000,
      "cost": 80
    }
  ],
  "transfer_fees": [
    {
      "agent_id": "ag-3",
      "amount": 40
    }
  ],
  "idle_periods": [
    {
      "agent_id": "ag-1",
      "amount": 30000,
      "days": 10
    },
    {
      "agent_id": "ag-2",
      "amount": 15000,
      "days": 15
    }
  ]
}
```

Example response:

```json
{
  "period_days": 30,
  "annualization_days": 365,
  "lines": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "category": "funding",
      "nature": "actual",
      "amount": 986,
      "formula": "floor((cash_float + electronic_float) * funding_rate_bps * period_days / (10000 * annualization_days))",
      "intermediates": {
        "cash_float": 100000,
        "electronic_float": 50000,
        "total_float": 150000,
        "funding_rate_bps": 800,
        "period_days": 30,
        "annualization_days": 365,
        "numerator": 3600000000,
        "amount": 986
      }
    },
    {
      "agent_id": "ag-3",
      "currency": "EUR",
      "category": "funding",
      "nature": "actual",
      "amount": 394,
      "formula": "floor((cash_float + electronic_float) * funding_rate_bps * period_days / (10000 * annualization_days))",
      "intermediates": {
        "cash_float": 80000,
        "electronic_float": 0,
        "total_float": 80000,
        "funding_rate_bps": 600,
        "period_days": 30,
        "annualization_days": 365,
        "numerator": 1440000000,
        "amount": 394
      }
    },
    {
      "agent_id": "ag-2",
      "currency": "USD",
      "category": "funding",
      "nature": "actual",
      "amount": 25,
      "formula": "supplied funding_costs.amount",
      "intermediates": {
        "amount": 25
      }
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "category": "replenishment",
      "nature": "actual",
      "amount": 150,
      "formula": "supplied replenishments.cost",
      "intermediates": {
        "replenished_amount": 40000,
        "cost": 150
      }
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "category": "collection",
      "nature": "actual",
      "amount": 80,
      "formula": "supplied collections.cost",
      "intermediates": {
        "collected_amount": 20000,
        "cost": 80
      }
    },
    {
      "agent_id": "ag-3",
      "currency": "EUR",
      "category": "transfer_fee",
      "nature": "actual",
      "amount": 40,
      "formula": "supplied transfer_fees.amount",
      "intermediates": {
        "amount": 40
      }
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "category": "idle_capital",
      "nature": "opportunity",
      "amount": 98,
      "formula": "floor(idle_amount * cost_of_capital_bps * idle_days / (10000 * annualization_days))",
      "intermediates": {
        "idle_amount": 30000,
        "idle_days": 10,
        "cost_of_capital_bps": 1200,
        "annualization_days": 365,
        "numerator": 360000000,
        "amount": 98
      }
    },
    {
      "agent_id": "ag-2",
      "currency": "USD",
      "category": "idle_capital",
      "nature": "opportunity",
      "amount": 61,
      "formula": "floor(idle_amount * cost_of_capital_bps * idle_days / (10000 * annualization_days))",
      "intermediates": {
        "idle_amount": 15000,
        "idle_days": 15,
        "cost_of_capital_bps": 1000,
        "annualization_days": 365,
        "numerator": 225000000,
        "amount": 61
      }
    }
  ],
  "by_agent": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "transaction_count": 200,
      "funding_cost": 986,
      "replenishment_cost": 150,
      "collection_cost": 80,
      "transfer_fee_cost": 0,
      "idle_capital_cost": 98,
      "actual_cost": 1216,
      "opportunity_cost": 98,
      "total_liquidity_cost": 1314,
      "cost_per_transaction": 6,
      "formula": "total_liquidity_cost = funding_cost + replenishment_cost + collection_cost + transfer_fee_cost + idle_capital_cost; cost_per_transaction = floor(total_liquidity_cost / transaction_count) when transaction_count > 0"
    },
    {
      "agent_id": "ag-2",
      "currency": "USD",
      "transaction_count": 50,
      "funding_cost": 25,
      "replenishment_cost": 0,
      "collection_cost": 0,
      "transfer_fee_cost": 0,
      "idle_capital_cost": 61,
      "actual_cost": 25,
      "opportunity_cost": 61,
      "total_liquidity_cost": 86,
      "cost_per_transaction": 1,
      "formula": "total_liquidity_cost = funding_cost + replenishment_cost + collection_cost + transfer_fee_cost + idle_capital_cost; cost_per_transaction = floor(total_liquidity_cost / transaction_count) when transaction_count > 0"
    },
    {
      "agent_id": "ag-3",
      "currency": "EUR",
      "transaction_count": 100,
      "funding_cost": 394,
      "replenishment_cost": 0,
      "collection_cost": 0,
      "transfer_fee_cost": 40,
      "idle_capital_cost": 0,
      "actual_cost": 434,
      "opportunity_cost": 0,
      "total_liquidity_cost": 434,
      "cost_per_transaction": 4,
      "formula": "total_liquidity_cost = funding_cost + replenishment_cost + collection_cost + transfer_fee_cost + idle_capital_cost; cost_per_transaction = floor(total_liquidity_cost / transaction_count) when transaction_count > 0"
    }
  ],
  "by_currency": [
    {
      "currency": "EUR",
      "funding_cost": 394,
      "replenishment_cost": 0,
      "collection_cost": 0,
      "transfer_fee_cost": 40,
      "idle_capital_cost": 0,
      "actual_cost": 434,
      "opportunity_cost": 0,
      "total_liquidity_cost": 434,
      "transaction_count": 100,
      "cost_per_transaction": 4,
      "formula": "Sums are per currency with no conversion. actual_cost excludes idle_capital_cost. opportunity_cost is idle capital only."
    },
    {
      "currency": "USD",
      "funding_cost": 1011,
      "replenishment_cost": 150,
      "collection_cost": 80,
      "transfer_fee_cost": 0,
      "idle_capital_cost": 159,
      "actual_cost": 1241,
      "opportunity_cost": 159,
      "total_liquidity_cost": 1400,
      "transaction_count": 250,
      "cost_per_transaction": 5,
      "formula": "Sums are per currency with no conversion. actual_cost excludes idle_capital_cost. opportunity_cost is idle capital only."
    }
  ],
  "formulas": [
    "funding from rate: floor((cash_float + electronic_float) * funding_rate_bps * period_days / (10000 * annualization_days))",
    "funding from funding_costs: supplied amount",
    "replenishment_cost: supplied replenishments.cost",
    "collection_cost: supplied collections.cost",
    "transfer_fee_cost: supplied transfer_fees.amount",
    "idle_capital_cost: floor(idle_amount * cost_of_capital_bps * idle_days / (10000 * annualization_days))",
    "actual_cost: funding + replenishment + collection + transfer fees",
    "opportunity_cost: idle capital only",
    "total_liquidity_cost: actual_cost + opportunity_cost",
    "cost_per_transaction: floor(total_liquidity_cost / transaction_count) when transaction_count > 0"
  ]
}
```

### POST /api/v1/agent-networks/outlet-performance-benchmark

$0.04 USDC. 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.

Inputs: outlets

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-outlet-performance-benchmark

Example request:

```json
{
  "outlets": [
    {
      "id": "o1",
      "currency": "USD",
      "category": "urban",
      "transaction_count": 300,
      "transaction_value": 900000,
      "active_days": 20,
      "operating_hours": 160,
      "commission": 4500,
      "operating_cost": 1200,
      "cash_available": 8000,
      "cash_capacity": 10000
    },
    {
      "id": "o2",
      "currency": "USD",
      "category": "urban",
      "transaction_count": 180,
      "transaction_value": 720000,
      "active_days": 20,
      "operating_hours": 160,
      "commission": 3600,
      "operating_cost": 1500,
      "cash_available": 5000,
      "cash_capacity": 10000
    },
    {
      "id": "o3",
      "currency": "USD",
      "category": "rural",
      "transaction_count": 90,
      "transaction_value": 450000,
      "active_days": 15,
      "operating_hours": 90,
      "commission": 1800,
      "operating_cost": 900,
      "cash_available": 3000,
      "cash_capacity": 6000
    },
    {
      "id": "o4",
      "currency": "EUR",
      "transaction_count": 120,
      "transaction_value": 240000,
      "commission": 2400,
      "operating_cost": 800
    }
  ]
}
```

Example response:

```json
{
  "outlets": [
    {
      "outlet_id": "o3",
      "currency": "USD",
      "category": "rural",
      "peer_group": "rural:USD",
      "peer_size": 1,
      "transaction_count": 90,
      "transaction_value": 450000,
      "active_days": 15,
      "operating_hours": 90,
      "commission": 1800,
      "operating_cost": 900,
      "cash_available": 3000,
      "cash_capacity": 6000,
      "transactions_per_active_day": 6,
      "revenue_per_operating_hour": 20,
      "average_transaction_value": 5000,
      "commission_per_transaction": 20,
      "operating_cost_per_transaction": 10,
      "utilization_bps": 5000,
      "peer_averages": {
        "transactions_per_active_day": 6,
        "revenue_per_operating_hour": 20,
        "average_transaction_value": 5000,
        "commission_per_transaction": 20,
        "operating_cost_per_transaction": 10,
        "utilization_bps": 5000,
        "transaction_count": 90,
        "commission": 1800
      },
      "metric_ranks": {
        "transactions_per_active_day_or_count": 1,
        "revenue_per_operating_hour_or_commission": 1,
        "average_transaction_value": 1,
        "commission_per_transaction": 1,
        "operating_cost_per_transaction": 1,
        "utilization_bps": 1
      },
      "productivity_score": 6,
      "productivity_rank": 1,
      "metric_count": 6,
      "formulas": {
        "transactions_per_active_day": "floor(transaction_count / active_days) when active_days is supplied",
        "revenue_per_operating_hour": "floor(commission / operating_hours) when operating_hours is supplied",
        "average_transaction_value": "floor(transaction_value / transaction_count) when transaction_count > 0",
        "commission_per_transaction": "floor(commission / transaction_count) when transaction_count > 0",
        "operating_cost_per_transaction": "floor(operating_cost / transaction_count) when transaction_count > 0",
        "utilization_bps": "floor(cash_available * 10000 / cash_capacity) when both are supplied",
        "productivity_score": "sum of competition ranks for available metrics inside the peer group; lower is better",
        "productivity_rank": "competition rank of productivity_score inside the peer group; 1 is best"
      }
    },
    {
      "outlet_id": "o4",
      "currency": "EUR",
      "peer_group": "ungrouped:EUR",
      "peer_size": 1,
      "transaction_count": 120,
      "transaction_value": 240000,
      "commission": 2400,
      "operating_cost": 800,
      "average_transaction_value": 2000,
      "commission_per_transaction": 20,
      "operating_cost_per_transaction": 6,
      "peer_averages": {
        "average_transaction_value": 2000,
        "commission_per_transaction": 20,
        "operating_cost_per_transaction": 6,
        "transaction_count": 120,
        "commission": 2400
      },
      "metric_ranks": {
        "transactions_per_active_day_or_count": 1,
        "revenue_per_operating_hour_or_commission": 1,
        "average_transaction_value": 1,
        "commission_per_transaction": 1,
        "operating_cost_per_transaction": 1
      },
      "productivity_score": 5,
      "productivity_rank": 1,
      "metric_count": 5,
      "formulas": {
        "transactions_per_active_day": "floor(transaction_count / active_days) when active_days is supplied",
        "revenue_per_operating_hour": "floor(commission / operating_hours) when operating_hours is supplied",
        "average_transaction_value": "floor(transaction_value / transaction_count) when transaction_count > 0",
        "commission_per_transaction": "floor(commission / transaction_count) when transaction_count > 0",
        "operating_cost_per_transaction": "floor(operating_cost / transaction_count) when transaction_count > 0",
        "utilization_bps": "floor(cash_available * 10000 / cash_capacity) when both are supplied",
        "productivity_score": "sum of competition ranks for available metrics inside the peer group; lower is better",
        "productivity_rank": "competition rank of productivity_score inside the peer group; 1 is best"
      }
    },
    {
      "outlet_id": "o1",
      "currency": "USD",
      "category": "urban",
      "peer_group": "urban:USD",
      "peer_size": 2,
      "transaction_count": 300,
      "transaction_value": 900000,
      "active_days": 20,
      "operating_hours": 160,
      "commission": 4500,
      "operating_cost": 1200,
      "cash_available": 8000,
      "cash_capacity": 10000,
      "transactions_per_active_day": 15,
      "revenue_per_operating_hour": 28,
      "average_transaction_value": 3000,
      "commission_per_transaction": 15,
      "operating_cost_per_transaction": 4,
      "utilization_bps": 8000,
      "peer_averages": {
        "transactions_per_active_day": 12,
        "revenue_per_operating_hour": 25,
        "average_transaction_value": 3500,
        "commission_per_transaction": 17,
        "operating_cost_per_transaction": 6,
        "utilization_bps": 6500,
        "transaction_count": 240,
        "commission": 4050
      },
      "metric_ranks": {
        "transactions_per_active_day_or_count": 1,
        "revenue_per_operating_hour_or_commission": 1,
        "average_transaction_value": 2,
        "commission_per_transaction": 2,
        "operating_cost_per_transaction": 1,
        "utilization_bps": 1
      },
      "productivity_score": 8,
      "productivity_rank": 1,
      "metric_count": 6,
      "formulas": {
        "transactions_per_active_day": "floor(transaction_count / active_days) when active_days is supplied",
        "revenue_per_operating_hour": "floor(commission / operating_hours) when operating_hours is supplied",
        "average_transaction_value": "floor(transaction_value / transaction_count) when transaction_count > 0",
        "commission_per_transaction": "floor(commission / transaction_count) when transaction_count > 0",
        "operating_cost_per_transaction": "floor(operating_cost / transaction_count) when transaction_count > 0",
        "utilization_bps": "floor(cash_available * 10000 / cash_capacity) when both are supplied",
        "productivity_score": "sum of competition ranks for available metrics inside the peer group; lower is better",
        "productivity_rank": "competition rank of productivity_score inside the peer group; 1 is best"
      }
    },
    {
      "outlet_id": "o2",
      "currency": "USD",
      "category": "urban",
      "peer_group": "urban:USD",
      "peer_size": 2,
      "transaction_count": 180,
      "transaction_value": 720000,
      "active_days": 20,
      "operating_hours": 160,
      "commission": 3600,
      "operating_cost": 1500,
      "cash_available": 5000,
      "cash_capacity": 10000,
      "transactions_per_active_day": 9,
      "revenue_per_operating_hour": 22,
      "average_transaction_value": 4000,
      "commission_per_transaction": 20,
      "operating_cost_per_transaction": 8,
      "utilization_bps": 5000,
      "peer_averages": {
        "transactions_per_active_day": 12,
        "revenue_per_operating_hour": 25,
        "average_transaction_value": 3500,
        "commission_per_transaction": 17,
        "operating_cost_per_transaction": 6,
        "utilization_bps": 6500,
        "transaction_count": 240,
        "commission": 4050
      },
      "metric_ranks": {
        "transactions_per_active_day_or_count": 2,
        "revenue_per_operating_hour_or_commission": 2,
        "average_transaction_value": 1,
        "commission_per_transaction": 1,
        "operating_cost_per_transaction": 2,
        "utilization_bps": 2
      },
      "productivity_score": 10,
      "productivity_rank": 2,
      "metric_count": 6,
      "formulas": {
        "transactions_per_active_day": "floor(transaction_count / active_days) when active_days is supplied",
        "revenue_per_operating_hour": "floor(commission / operating_hours) when operating_hours is supplied",
        "average_transaction_value": "floor(transaction_value / transaction_count) when transaction_count > 0",
        "commission_per_transaction": "floor(commission / transaction_count) when transaction_count > 0",
        "operating_cost_per_transaction": "floor(operating_cost / transaction_count) when transaction_count > 0",
        "utilization_bps": "floor(cash_available * 10000 / cash_capacity) when both are supplied",
        "productivity_score": "sum of competition ranks for available metrics inside the peer group; lower is better",
        "productivity_rank": "competition rank of productivity_score inside the peer group; 1 is best"
      }
    }
  ],
  "rankings": [
    {
      "outlet_id": "o3",
      "peer_group": "rural:USD",
      "currency": "USD",
      "category": "rural",
      "productivity_score": 6,
      "productivity_rank": 1
    },
    {
      "outlet_id": "o4",
      "peer_group": "ungrouped:EUR",
      "currency": "EUR",
      "productivity_score": 5,
      "productivity_rank": 1
    },
    {
      "outlet_id": "o1",
      "peer_group": "urban:USD",
      "currency": "USD",
      "category": "urban",
      "productivity_score": 8,
      "productivity_rank": 1
    },
    {
      "outlet_id": "o2",
      "peer_group": "urban:USD",
      "currency": "USD",
      "category": "urban",
      "productivity_score": 10,
      "productivity_rank": 2
    }
  ],
  "peer_groups": [
    {
      "peer_group": "rural:USD",
      "size": 1,
      "outlet_ids": [
        "o3"
      ]
    },
    {
      "peer_group": "ungrouped:EUR",
      "size": 1,
      "outlet_ids": [
        "o4"
      ]
    },
    {
      "peer_group": "urban:USD",
      "size": 2,
      "outlet_ids": [
        "o1",
        "o2"
      ]
    }
  ],
  "explanations": [
    "transactions_per_active_day = floor(transaction_count / active_days) when active_days is supplied. Comparisons use this instead of raw transaction_count when active_days is present.",
    "revenue_per_operating_hour = floor(commission / operating_hours) when operating_hours is supplied. Comparisons use this instead of raw commission when operating_hours is present.",
    "average_transaction_value = floor(transaction_value / transaction_count) when transaction_count > 0.",
    "commission_per_transaction = floor(commission / transaction_count) when transaction_count > 0.",
    "operating_cost_per_transaction = floor(operating_cost / transaction_count) when transaction_count > 0. Lower is better in ranking.",
    "utilization_bps = floor(cash_available * 10000 / cash_capacity) when both are supplied. This is cash-on-hand versus capacity from the request only.",
    "Peer groups are category:currency. Outlets without a category use ungrouped. Currencies are never mixed.",
    "Metric ranks are competition ranks inside the peer group (1 is best). Missing metrics are omitted from that outlet's productivity_score.",
    "productivity_score is the sum of the outlet's metric ranks. Lower is better. productivity_rank is the competition rank of that score inside the peer group.",
    "No industry benchmark or external market figure is used."
  ]
}
```

### POST /api/v1/agent-networks/cash-denomination-optimization

$0.04 USDC. 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.

Inputs: denominations, agents, transactions, replenishment?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-cash-denomination-optimization

Example request:

```json
{
  "denominations": [
    {
      "currency": "USD",
      "value": 10000
    },
    {
      "currency": "USD",
      "value": 5000
    },
    {
      "currency": "USD",
      "value": 1000
    },
    {
      "currency": "USD",
      "value": 500
    },
    {
      "currency": "USD",
      "value": 100
    },
    {
      "currency": "EUR",
      "value": 5000
    },
    {
      "currency": "EUR",
      "value": 1000
    },
    {
      "currency": "EUR",
      "value": 200
    }
  ],
  "agents": [
    {
      "id": "ag-1",
      "currency": "USD",
      "inventory": [
        {
          "value": 10000,
          "quantity": 1
        },
        {
          "value": 5000,
          "quantity": 0
        },
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 500,
          "quantity": 1
        },
        {
          "value": 100,
          "quantity": 3
        }
      ],
      "minimum_reserves": [
        {
          "value": 100,
          "quantity": 5
        },
        {
          "value": 1000,
          "quantity": 2
        }
      ]
    },
    {
      "id": "ag-2",
      "currency": "EUR",
      "inventory": [
        {
          "value": 5000,
          "quantity": 2
        },
        {
          "value": 1000,
          "quantity": 1
        },
        {
          "value": 200,
          "quantity": 0
        }
      ]
    }
  ],
  "transactions": [
    {
      "id": "t1",
      "agent_id": "ag-1",
      "direction": "out",
      "amount": 2700
    },
    {
      "id": "t2",
      "agent_id": "ag-1",
      "direction": "in",
      "amount": 1500,
      "tender": 2000
    },
    {
      "id": "t3",
      "agent_id": "ag-1",
      "direction": "out",
      "amount": 8500
    },
    {
      "id": "t4",
      "agent_id": "ag-2",
      "direction": "out",
      "amount": 2400
    }
  ],
  "replenishment": [
    {
      "agent_id": "ag-1",
      "value": 1000,
      "max_quantity": 10
    },
    {
      "agent_id": "ag-1",
      "value": 100,
      "max_quantity": 50
    },
    {
      "agent_id": "ag-1",
      "value": 5000,
      "max_quantity": 5
    },
    {
      "agent_id": "ag-2",
      "value": 200,
      "max_quantity": 20
    },
    {
      "agent_id": "ag-2",
      "value": 1000,
      "max_quantity": 5
    }
  ]
}
```

Example response:

```json
{
  "agents": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "starting_inventory": [
        {
          "value": 10000,
          "quantity": 1
        },
        {
          "value": 5000,
          "quantity": 0
        },
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 500,
          "quantity": 1
        },
        {
          "value": 100,
          "quantity": 3
        }
      ],
      "recommended_acquisitions": [
        {
          "agent_id": "ag-1",
          "currency": "USD",
          "value": 100,
          "quantity": 14,
          "amount": 1400,
          "action": "acquire"
        },
        {
          "agent_id": "ag-1",
          "currency": "USD",
          "value": 5000,
          "quantity": 1,
          "amount": 5000,
          "action": "acquire"
        },
        {
          "agent_id": "ag-1",
          "currency": "USD",
          "value": 1000,
          "quantity": 2,
          "amount": 2000,
          "action": "acquire"
        },
        {
          "agent_id": "ag-1",
          "currency": "USD",
          "value": 500,
          "quantity": 2,
          "amount": 1000,
          "action": "acquire"
        }
      ],
      "projected_inventory": [
        {
          "value": 10000,
          "quantity": 1
        },
        {
          "value": 5000,
          "quantity": 0
        },
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 500,
          "quantity": 0
        },
        {
          "value": 100,
          "quantity": 5
        }
      ],
      "starting_cash": 12800,
      "acquired_cash": 9400,
      "projected_cash": 12500,
      "minimum_cash_required": 22200,
      "transactions_total": 3,
      "transactions_fulfilled": 3,
      "fully_feasible": true,
      "formulas": {
        "dispense": "Greedy largest-first using free notes above minimum_reserves, then reserved notes if still short.",
        "deposit": "Greedy largest-first composition of tender (or amount when tender is omitted) added to inventory before change is dispensed.",
        "acquire": "While shortages remain, acquire the greedy composition of each shortage amount, capped by replenishment.max_quantity, then top up minimum_reserves.",
        "minimum_cash_required": "starting inventory value plus recommended acquisition value."
      }
    },
    {
      "agent_id": "ag-2",
      "currency": "EUR",
      "starting_inventory": [
        {
          "value": 5000,
          "quantity": 2
        },
        {
          "value": 1000,
          "quantity": 1
        },
        {
          "value": 200,
          "quantity": 0
        }
      ],
      "recommended_acquisitions": [
        {
          "agent_id": "ag-2",
          "currency": "EUR",
          "value": 1000,
          "quantity": 1,
          "amount": 1000,
          "action": "acquire"
        },
        {
          "agent_id": "ag-2",
          "currency": "EUR",
          "value": 200,
          "quantity": 2,
          "amount": 400,
          "action": "acquire"
        }
      ],
      "projected_inventory": [
        {
          "value": 5000,
          "quantity": 2
        },
        {
          "value": 1000,
          "quantity": 0
        },
        {
          "value": 200,
          "quantity": 0
        }
      ],
      "starting_cash": 11000,
      "acquired_cash": 1400,
      "projected_cash": 10000,
      "minimum_cash_required": 12400,
      "transactions_total": 1,
      "transactions_fulfilled": 1,
      "fully_feasible": true,
      "formulas": {
        "dispense": "Greedy largest-first using free notes above minimum_reserves, then reserved notes if still short.",
        "deposit": "Greedy largest-first composition of tender (or amount when tender is omitted) added to inventory before change is dispensed.",
        "acquire": "While shortages remain, acquire the greedy composition of each shortage amount, capped by replenishment.max_quantity, then top up minimum_reserves.",
        "minimum_cash_required": "starting inventory value plus recommended acquisition value."
      }
    }
  ],
  "recommended_denominations": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "value": 100,
      "quantity": 14,
      "amount": 1400,
      "action": "acquire"
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "value": 5000,
      "quantity": 1,
      "amount": 5000,
      "action": "acquire"
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "value": 1000,
      "quantity": 2,
      "amount": 2000,
      "action": "acquire"
    },
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "value": 500,
      "quantity": 2,
      "amount": 1000,
      "action": "acquire"
    },
    {
      "agent_id": "ag-2",
      "currency": "EUR",
      "value": 1000,
      "quantity": 1,
      "amount": 1000,
      "action": "acquire"
    },
    {
      "agent_id": "ag-2",
      "currency": "EUR",
      "value": 200,
      "quantity": 2,
      "amount": 400,
      "action": "acquire"
    }
  ],
  "fulfilment": [
    {
      "transaction_id": "t1",
      "agent_id": "ag-1",
      "fulfilled": true,
      "dispensed": 2700,
      "composition": [
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 500,
          "quantity": 1
        },
        {
          "value": 100,
          "quantity": 2
        }
      ]
    },
    {
      "transaction_id": "t2",
      "agent_id": "ag-1",
      "fulfilled": true,
      "received": 2000,
      "change_dispensed": 500,
      "tender_composition": [
        {
          "value": 1000,
          "quantity": 2
        }
      ],
      "change_composition": [
        {
          "value": 500,
          "quantity": 1
        }
      ]
    },
    {
      "transaction_id": "t3",
      "agent_id": "ag-1",
      "fulfilled": true,
      "dispensed": 8500,
      "composition": [
        {
          "value": 5000,
          "quantity": 1
        },
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 500,
          "quantity": 1
        },
        {
          "value": 100,
          "quantity": 10
        }
      ]
    },
    {
      "transaction_id": "t4",
      "agent_id": "ag-2",
      "fulfilled": true,
      "dispensed": 2400,
      "composition": [
        {
          "value": 1000,
          "quantity": 2
        },
        {
          "value": 200,
          "quantity": 2
        }
      ]
    }
  ],
  "change_shortages": [],
  "excess_denominations": [
    {
      "agent_id": "ag-1",
      "currency": "USD",
      "value": 10000,
      "quantity": 1,
      "amount": 10000
    },
    {
      "agent_id": "ag-2",
      "currency": "EUR",
      "value": 5000,
      "quantity": 2,
      "amount": 10000
    }
  ],
  "explanations": [
    "Denominations come only from the request. No currency or note set is assumed.",
    "Cash-out dispenses the amount with a largest-first greedy composition against on-hand quantities.",
    "Cash-in adds a greedy composition of tender (defaulting to amount) and dispenses change of tender minus amount the same way.",
    "minimum_reserves are preferred as a soft floor during dispense, then used if required to fulfil the amount.",
    "Recommended acquisitions cover remaining shortage compositions and reserve top-ups, limited by replenishment.max_quantity when supplied.",
    "excess_denominations are projected ending quantities above minimum_reserves after applying recommended acquisitions.",
    "This endpoint does not initiate replenishment or redistribution."
  ]
}
```

### POST /api/v1/agent-networks/outlet-capacity-allocation

$0.04 USDC. 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.

Inputs: outlets, demand, service_level_targets?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-outlet-capacity-allocation

Example request:

```json
{
  "outlets": [
    {
      "id": "o1",
      "location_id": "loc-a",
      "service_types": [
        "cash_in",
        "cash_out"
      ],
      "capacity_per_hour": 20,
      "staff_count": 2,
      "staff_capacity_per_hour": 15,
      "operating_hours": [
        {
          "interval_id": "morning",
          "hours": 4
        },
        {
          "interval_id": "afternoon",
          "hours": 4
        }
      ]
    },
    {
      "id": "o2",
      "location_id": "loc-a",
      "service_types": [
        "cash_out"
      ],
      "capacity_per_hour": 10,
      "operating_hours": [
        {
          "interval_id": "morning",
          "hours": 4
        }
      ]
    },
    {
      "id": "o3",
      "location_id": "loc-b",
      "service_types": [
        "cash_in",
        "bill_pay"
      ],
      "capacity_per_hour": 12,
      "operating_hours": [
        {
          "interval_id": "morning",
          "hours": 3
        }
      ]
    }
  ],
  "demand": [
    {
      "id": "d1",
      "location_id": "loc-a",
      "interval_id": "morning",
      "service_type": "cash_out",
      "transactions": 100
    },
    {
      "id": "d2",
      "location_id": "loc-a",
      "interval_id": "morning",
      "service_type": "cash_in",
      "transactions": 50
    },
    {
      "id": "d3",
      "location_id": "loc-a",
      "interval_id": "afternoon",
      "service_type": "cash_out",
      "transactions": 30
    },
    {
      "id": "d4",
      "location_id": "loc-b",
      "interval_id": "morning",
      "service_type": "bill_pay",
      "transactions": 40
    },
    {
      "id": "d5",
      "location_id": "loc-b",
      "interval_id": "morning",
      "service_type": "cash_out",
      "transactions": 10
    }
  ],
  "service_level_targets": [
    {
      "location_id": "loc-a",
      "interval_id": "morning",
      "fulfil_bps": 10000
    },
    {
      "location_id": "loc-b",
      "service_type": "bill_pay",
      "fulfil_bps": 9000
    }
  ]
}
```

Example response:

```json
{
  "allocations": [
    {
      "demand_id": "d1",
      "outlet_id": "o1",
      "location_id": "loc-a",
      "interval_id": "morning",
      "service_type": "cash_out",
      "transactions": 80
    },
    {
      "demand_id": "d1",
      "outlet_id": "o2",
      "location_id": "loc-a",
      "interval_id": "morning",
      "service_type": "cash_out",
      "transactions": 20
    },
    {
      "demand_id": "d3",
      "outlet_id": "o1",
      "location_id": "loc-a",
      "interval_id": "afternoon",
      "service_type": "cash_out",
      "transactions": 30
    },
    {
      "demand_id": "d4",
      "outlet_id": "o3",
      "location_id": "loc-b",
      "interval_id": "morning",
      "service_type": "bill_pay",
      "transactions": 36
    }
  ],
  "utilization": [
    {
      "outlet_id": "o1",
      "interval_id": "afternoon",
      "capacity": 80,
      "allocated": 30,
      "unused_capacity": 50,
      "overload": 0,
      "utilization_bps": 3750,
      "overloaded": false
    },
    {
      "outlet_id": "o1",
      "interval_id": "morning",
      "capacity": 80,
      "allocated": 80,
      "unused_capacity": 0,
      "overload": 0,
      "utilization_bps": 10000,
      "overloaded": true
    },
    {
      "outlet_id": "o2",
      "interval_id": "morning",
      "capacity": 40,
      "allocated": 20,
      "unused_capacity": 20,
      "overload": 0,
      "utilization_bps": 5000,
      "overloaded": false
    },
    {
      "outlet_id": "o3",
      "interval_id": "morning",
      "capacity": 36,
      "allocated": 36,
      "unused_capacity": 0,
      "overload": 0,
      "utilization_bps": 10000,
      "overloaded": true
    }
  ],
  "overloaded_outlets": [
    {
      "outlet_id": "o1",
      "interval_id": "morning",
      "capacity": 80,
      "allocated": 80,
      "unused_capacity": 0,
      "overload": 0,
      "utilization_bps": 10000,
      "overloaded": true
    },
    {
      "outlet_id": "o3",
      "interval_id": "morning",
      "capacity": 36,
      "allocated": 36,
      "unused_capacity": 0,
      "overload": 0,
      "utilization_bps": 10000,
      "overloaded": true
    }
  ],
  "unused_capacity": [
    {
      "outlet_id": "o1",
      "interval_id": "afternoon",
      "unused_capacity": 50
    },
    {
      "outlet_id": "o2",
      "interval_id": "morning",
      "unused_capacity": 20
    }
  ],
  "unmet_demand": [
    {
      "demand_id": "d2",
      "location_id": "loc-a",
      "interval_id": "morning",
      "service_type": "cash_in",
      "transactions": 50,
      "detail": "Matching outlets already used their remaining interval capacity on earlier demand."
    },
    {
      "demand_id": "d4",
      "location_id": "loc-b",
      "interval_id": "morning",
      "service_type": "bill_pay",
      "transactions": 4,
      "detail": "Eligible outlets ran out of remaining interval capacity before the demand was fully allocated."
    },
    {
      "demand_id": "d5",
      "location_id": "loc-b",
      "interval_id": "morning",
      "service_type": "cash_out",
      "transactions": 10,
      "detail": "No open outlet at this location supports the service type for the interval."
    }
  ],
  "service_levels": [
    {
      "location_id": "loc-a",
      "interval_id": "morning",
      "fulfil_bps": 10000,
      "demand_transactions": 150,
      "allocated_transactions": 100,
      "target_transactions": 150,
      "achieved_bps": 6666,
      "capacity_required": 50,
      "met": false,
      "formula": "target_transactions = floor(demand_transactions * fulfil_bps / 10000); capacity_required = max(0, target_transactions - allocated_transactions)"
    },
    {
      "location_id": "loc-b",
      "service_type": "bill_pay",
      "fulfil_bps": 9000,
      "demand_transactions": 40,
      "allocated_transactions": 36,
      "target_transactions": 36,
      "achieved_bps": 9000,
      "capacity_required": 0,
      "met": true,
      "formula": "target_transactions = floor(demand_transactions * fulfil_bps / 10000); capacity_required = max(0, target_transactions - allocated_transactions)"
    }
  ],
  "capacity_required": [
    {
      "location_id": "loc-a",
      "interval_id": "morning",
      "capacity_required": 50,
      "detail": "Additional transaction capacity needed in this scope to reach the supplied fulfil_bps target after the deterministic allocation."
    }
  ],
  "explanations": [
    "Interval capacity = capacity_per_hour * operating hours. When staffing is supplied it is also min'd with staff_count * staff_capacity_per_hour * hours.",
    "Demand is processed in demand id order. Eligible outlets share location_id, support the service_type, and have hours > 0 in the interval.",
    "Allocation fills the eligible outlet with the most remaining capacity first, then by outlet id. No external map or demand source is used.",
    "utilization_bps = floor(allocated * 10000 / capacity). unused_capacity is capacity minus allocated.",
    "capacity_required is the extra allocated transactions still needed to reach floor(demand * fulfil_bps / 10000) for each supplied service-level target."
  ]
}
```

### POST /api/v1/agent-networks/agent-concentration-risk

$0.04 USDC. 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.

Inputs: entities, outages?, top_counts?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-agent-concentration-risk

Example request:

```json
{
  "top_counts": [
    1,
    2,
    3
  ],
  "entities": [
    {
      "id": "ag-1",
      "kind": "agent",
      "transaction_volume": 500,
      "transaction_value": 100000,
      "revenue": 5000,
      "segments": [
        {
          "dimension": "region",
          "label": "north"
        },
        {
          "dimension": "channel",
          "label": "retail"
        }
      ],
      "replacement_capacity": 100
    },
    {
      "id": "ag-2",
      "kind": "agent",
      "transaction_volume": 300,
      "transaction_value": 60000,
      "revenue": 2500,
      "segments": [
        {
          "dimension": "region",
          "label": "north"
        },
        {
          "dimension": "channel",
          "label": "mobile"
        }
      ],
      "replacement_capacity": 200
    },
    {
      "id": "ag-3",
      "kind": "agent",
      "transaction_volume": 200,
      "transaction_value": 40000,
      "revenue": 1500,
      "segments": [
        {
          "dimension": "region",
          "label": "south"
        }
      ],
      "replacement_capacity": 50
    },
    {
      "id": "op-1",
      "kind": "operator",
      "transaction_volume": 800,
      "transaction_value": 160000,
      "revenue": 7000,
      "segments": [
        {
          "dimension": "region",
          "label": "north"
        }
      ],
      "replacement_capacity": 0
    },
    {
      "id": "out-1",
      "kind": "outlet",
      "transaction_volume": 150,
      "transaction_value": 30000,
      "revenue": 900,
      "segments": [
        {
          "dimension": "region",
          "label": "south"
        },
        {
          "dimension": "channel",
          "label": "retail"
        }
      ],
      "replacement_capacity": 80
    }
  ],
  "outages": [
    {
      "id": "lose-top-agent",
      "unavailable_ids": [
        "ag-1"
      ]
    },
    {
      "id": "lose-operator",
      "unavailable_ids": [
        "op-1",
        "ag-2"
      ]
    }
  ]
}
```

Example response:

```json
{
  "top_counts": [
    1,
    2,
    3
  ],
  "analyses": [
    {
      "metric": "transaction_volume",
      "entity_count": 5,
      "total": 1950,
      "hhi": 2740,
      "hhi_formula": "HHI = floor(sum(share_bps^2) / 10000) where share_bps = floor(amount * 10000 / total)",
      "concentration_ratios": [
        {
          "top_n": 1,
          "entity_ids": [
            "op-1"
          ],
          "amount": 800,
          "share_bps": 4102,
          "formula": "CR1 = floor(sum(top 1 amounts) * 10000 / total)"
        },
        {
          "top_n": 2,
          "entity_ids": [
            "op-1",
            "ag-1"
          ],
          "amount": 1300,
          "share_bps": 6666,
          "formula": "CR2 = floor(sum(top 2 amounts) * 10000 / total)"
        },
        {
          "top_n": 3,
          "entity_ids": [
            "op-1",
            "ag-1",
            "ag-2"
          ],
          "amount": 1600,
          "share_bps": 8205,
          "formula": "CR3 = floor(sum(top 3 amounts) * 10000 / total)"
        }
      ],
      "dependency_ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 800,
          "share_bps": 4102
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 500,
          "share_bps": 2564
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 300,
          "share_bps": 1538
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 200,
          "share_bps": 1025
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 150,
          "share_bps": 769
        }
      ]
    },
    {
      "metric": "transaction_value",
      "entity_count": 5,
      "total": 390000,
      "hhi": 2740,
      "hhi_formula": "HHI = floor(sum(share_bps^2) / 10000) where share_bps = floor(amount * 10000 / total)",
      "concentration_ratios": [
        {
          "top_n": 1,
          "entity_ids": [
            "op-1"
          ],
          "amount": 160000,
          "share_bps": 4102,
          "formula": "CR1 = floor(sum(top 1 amounts) * 10000 / total)"
        },
        {
          "top_n": 2,
          "entity_ids": [
            "op-1",
            "ag-1"
          ],
          "amount": 260000,
          "share_bps": 6666,
          "formula": "CR2 = floor(sum(top 2 amounts) * 10000 / total)"
        },
        {
          "top_n": 3,
          "entity_ids": [
            "op-1",
            "ag-1",
            "ag-2"
          ],
          "amount": 320000,
          "share_bps": 8205,
          "formula": "CR3 = floor(sum(top 3 amounts) * 10000 / total)"
        }
      ],
      "dependency_ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 160000,
          "share_bps": 4102
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 100000,
          "share_bps": 2564
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 60000,
          "share_bps": 1538
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 40000,
          "share_bps": 1025
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 30000,
          "share_bps": 769
        }
      ]
    },
    {
      "metric": "revenue",
      "entity_count": 5,
      "total": 16900,
      "hhi": 2916,
      "hhi_formula": "HHI = floor(sum(share_bps^2) / 10000) where share_bps = floor(amount * 10000 / total)",
      "concentration_ratios": [
        {
          "top_n": 1,
          "entity_ids": [
            "op-1"
          ],
          "amount": 7000,
          "share_bps": 4142,
          "formula": "CR1 = floor(sum(top 1 amounts) * 10000 / total)"
        },
        {
          "top_n": 2,
          "entity_ids": [
            "op-1",
            "ag-1"
          ],
          "amount": 12000,
          "share_bps": 7100,
          "formula": "CR2 = floor(sum(top 2 amounts) * 10000 / total)"
        },
        {
          "top_n": 3,
          "entity_ids": [
            "op-1",
            "ag-1",
            "ag-2"
          ],
          "amount": 14500,
          "share_bps": 8579,
          "formula": "CR3 = floor(sum(top 3 amounts) * 10000 / total)"
        }
      ],
      "dependency_ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 7000,
          "share_bps": 4142
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 5000,
          "share_bps": 2958
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 2500,
          "share_bps": 1479
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 1500,
          "share_bps": 887
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 900,
          "share_bps": 532
        }
      ]
    }
  ],
  "dependency_rankings": [
    {
      "metric": "transaction_volume",
      "ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 800,
          "share_bps": 4102
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 500,
          "share_bps": 2564
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 300,
          "share_bps": 1538
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 200,
          "share_bps": 1025
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 150,
          "share_bps": 769
        }
      ]
    },
    {
      "metric": "transaction_value",
      "ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 160000,
          "share_bps": 4102
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 100000,
          "share_bps": 2564
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 60000,
          "share_bps": 1538
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 40000,
          "share_bps": 1025
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 30000,
          "share_bps": 769
        }
      ]
    },
    {
      "metric": "revenue",
      "ranking": [
        {
          "entity_id": "op-1",
          "kind": "operator",
          "amount": 7000,
          "share_bps": 4142
        },
        {
          "entity_id": "ag-1",
          "kind": "agent",
          "amount": 5000,
          "share_bps": 2958
        },
        {
          "entity_id": "ag-2",
          "kind": "agent",
          "amount": 2500,
          "share_bps": 1479
        },
        {
          "entity_id": "ag-3",
          "kind": "agent",
          "amount": 1500,
          "share_bps": 887
        },
        {
          "entity_id": "out-1",
          "kind": "outlet",
          "amount": 900,
          "share_bps": 532
        }
      ]
    }
  ],
  "outage_scenarios": [
    {
      "outage_id": "lose-top-agent",
      "unavailable_ids": [
        "ag-1"
      ],
      "affected_transaction_volume": 500,
      "affected_transaction_value": 100000,
      "affected_revenue": 5000,
      "affected_volume_share_bps": 2564,
      "remaining_entity_count": 4,
      "replacement_capacity": 330,
      "replacement_shortfall": 170,
      "replacement_capacity_required": 170,
      "formula": "replacement_shortfall = max(0, affected_transaction_volume - sum(remaining entities' replacement_capacity))",
      "detail": "Remaining supplied replacement_capacity is below the unavailable entities' transaction volume."
    },
    {
      "outage_id": "lose-operator",
      "unavailable_ids": [
        "ag-2",
        "op-1"
      ],
      "affected_transaction_volume": 1100,
      "affected_transaction_value": 220000,
      "affected_revenue": 9500,
      "affected_volume_share_bps": 5641,
      "remaining_entity_count": 3,
      "replacement_capacity": 230,
      "replacement_shortfall": 870,
      "replacement_capacity_required": 870,
      "formula": "replacement_shortfall = max(0, affected_transaction_volume - sum(remaining entities' replacement_capacity))",
      "detail": "Remaining supplied replacement_capacity is below the unavailable entities' transaction volume."
    }
  ],
  "explanations": [
    "share_bps = floor(amount * 10000 / total) inside the analysis scope.",
    "HHI = floor(sum(share_bps^2) / 10000). One entity with the whole total scores 10000. No industry threshold is applied or invented.",
    "Concentration ratios use top_counts 1, 2, 3: CR_n is the share of the largest n entities by the metric.",
    "Analyses run for transaction_volume, transaction_value, and revenue overall, per entity kind, and for each supplied segment dimension/label.",
    "Dependency rankings order entities by the metric descending, then by entity id.",
    "Outage scenarios remove unavailable_ids, sum their volume/value/revenue, and compare that volume with remaining entities' replacement_capacity.",
    "replacement_capacity_required equals replacement_shortfall. No external capacity source is used."
  ]
}
```

### POST /api/v1/agent-networks/dormant-outlet-detect

$0.04 USDC. 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.

Inputs: as_of_date, inactive_days_threshold?, permanent_days_threshold?, decline_bps_threshold?, baseline_days?, recent_days?, outlets, transactions, schedules?, status_records?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-dormant-outlet-detect

Example request:

```json
{
  "as_of_date": "2026-11-06",
  "inactive_days_threshold": 7,
  "permanent_days_threshold": 30,
  "decline_bps_threshold": 5000,
  "baseline_days": 14,
  "recent_days": 7,
  "outlets": [
    {
      "id": "o1",
      "activation_date": "2026-01-01",
      "expected_transactions_per_active_day": 10
    },
    {
      "id": "o2",
      "activation_date": "2026-01-01"
    },
    {
      "id": "o3",
      "activation_date": "2026-01-01"
    },
    {
      "id": "o4",
      "activation_date": "2026-12-01"
    },
    {
      "id": "o5",
      "activation_date": "2026-01-01"
    }
  ],
  "transactions": [
    {
      "id": "t1",
      "outlet_id": "o1",
      "date": "2026-10-27",
      "count": 20
    },
    {
      "id": "t2",
      "outlet_id": "o1",
      "date": "2026-10-28",
      "count": 18
    },
    {
      "id": "t3",
      "outlet_id": "o1",
      "date": "2026-11-05",
      "count": 3
    },
    {
      "id": "t4",
      "outlet_id": "o2",
      "date": "2026-09-01",
      "count": 8
    },
    {
      "id": "t5",
      "outlet_id": "o3",
      "date": "2026-08-01",
      "count": 5
    },
    {
      "id": "t6",
      "outlet_id": "o5",
      "date": "2026-10-20",
      "count": 4
    },
    {
      "id": "t7",
      "outlet_id": "o1",
      "date": "2026-10-29",
      "count": 16
    }
  ],
  "schedules": [
    {
      "outlet_id": "o1",
      "weekday": 1
    },
    {
      "outlet_id": "o1",
      "weekday": 2
    },
    {
      "outlet_id": "o1",
      "weekday": 3
    },
    {
      "outlet_id": "o1",
      "weekday": 4
    },
    {
      "outlet_id": "o1",
      "weekday": 5
    },
    {
      "outlet_id": "o2",
      "weekday": 1
    },
    {
      "outlet_id": "o2",
      "weekday": 2
    },
    {
      "outlet_id": "o2",
      "weekday": 3
    },
    {
      "outlet_id": "o2",
      "weekday": 4
    },
    {
      "outlet_id": "o2",
      "weekday": 5
    },
    {
      "outlet_id": "o3",
      "weekday": 1
    },
    {
      "outlet_id": "o3",
      "weekday": 2
    },
    {
      "outlet_id": "o3",
      "weekday": 3
    },
    {
      "outlet_id": "o3",
      "weekday": 4
    },
    {
      "outlet_id": "o3",
      "weekday": 5
    },
    {
      "outlet_id": "o5",
      "weekday": 1
    },
    {
      "outlet_id": "o5",
      "weekday": 2
    },
    {
      "outlet_id": "o5",
      "weekday": 3
    },
    {
      "outlet_id": "o5",
      "weekday": 4
    },
    {
      "outlet_id": "o5",
      "weekday": 5
    }
  ],
  "status_records": [
    {
      "outlet_id": "o5",
      "kind": "seasonal",
      "start_date": "2026-10-21",
      "end_date": "2026-11-30"
    },
    {
      "outlet_id": "o3",
      "kind": "suspension",
      "start_date": "2026-10-01"
    }
  ]
}
```

Example response:

```json
{
  "as_of_date": "2026-11-06",
  "thresholds": {
    "inactive_days_threshold": 7,
    "permanent_days_threshold": 30,
    "decline_bps_threshold": 5000,
    "baseline_days": 14,
    "recent_days": 7
  },
  "outlets": [
    {
      "outlet_id": "o1",
      "classification": "declining",
      "requires_investigation": true,
      "last_transaction_date": "2026-11-05",
      "open_days_without_activity": 1,
      "activity_decline_bps": 9445,
      "recent_volume": 3,
      "baseline_volume": 54,
      "active_status_kinds": [],
      "evidence": [
        "Last transaction date is 2026-11-05.",
        "Open days without activity through as_of_date: 1 (threshold 7).",
        "Recent 7-day volume 3 versus prior baseline window volume 54 gives decline_bps 9445 (threshold 5000).",
        "Caller expected_transactions_per_active_day is 10.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified declining because decline_bps 9445 meets decline_bps_threshold 5000."
      ]
    },
    {
      "outlet_id": "o2",
      "classification": "permanently_inactive",
      "requires_investigation": true,
      "last_transaction_date": "2026-09-01",
      "inactivity_start_date": "2026-09-02",
      "open_days_without_activity": 48,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [],
      "evidence": [
        "Last transaction date is 2026-09-01.",
        "Open days without activity through as_of_date: 48 (threshold 7).",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified permanently_inactive because open days without activity (48) meet permanent_days_threshold (30)."
      ]
    },
    {
      "outlet_id": "o3",
      "classification": "suspended",
      "requires_investigation": true,
      "last_transaction_date": "2026-08-01",
      "inactivity_start_date": "2026-08-02",
      "open_days_without_activity": 43,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [
        "suspension"
      ],
      "evidence": [
        "Last transaction date is 2026-08-01.",
        "Open days without activity through as_of_date: 43 (threshold 7).",
        "Status suspension covers as_of_date from 2026-10-01 with no end_date.",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified suspended because a suspension status record covers as_of_date."
      ]
    },
    {
      "outlet_id": "o4",
      "classification": "not_yet_active",
      "requires_investigation": false,
      "open_days_without_activity": 0,
      "evidence": [
        "activation_date 2026-12-01 is after as_of_date 2026-11-06."
      ]
    },
    {
      "outlet_id": "o5",
      "classification": "seasonal_inactive",
      "requires_investigation": false,
      "last_transaction_date": "2026-10-20",
      "inactivity_start_date": "2026-10-21",
      "open_days_without_activity": 0,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [
        "seasonal"
      ],
      "evidence": [
        "Last transaction date is 2026-10-20.",
        "Open days without activity through as_of_date: 0 (threshold 7).",
        "Status seasonal covers as_of_date from 2026-10-21 to 2026-11-30.",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified seasonal_inactive because a seasonal status record covers as_of_date."
      ]
    }
  ],
  "inactive_outlets": [
    {
      "outlet_id": "o2",
      "classification": "permanently_inactive",
      "requires_investigation": true,
      "last_transaction_date": "2026-09-01",
      "inactivity_start_date": "2026-09-02",
      "open_days_without_activity": 48,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [],
      "evidence": [
        "Last transaction date is 2026-09-01.",
        "Open days without activity through as_of_date: 48 (threshold 7).",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified permanently_inactive because open days without activity (48) meet permanent_days_threshold (30)."
      ]
    },
    {
      "outlet_id": "o3",
      "classification": "suspended",
      "requires_investigation": true,
      "last_transaction_date": "2026-08-01",
      "inactivity_start_date": "2026-08-02",
      "open_days_without_activity": 43,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [
        "suspension"
      ],
      "evidence": [
        "Last transaction date is 2026-08-01.",
        "Open days without activity through as_of_date: 43 (threshold 7).",
        "Status suspension covers as_of_date from 2026-10-01 with no end_date.",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified suspended because a suspension status record covers as_of_date."
      ]
    },
    {
      "outlet_id": "o5",
      "classification": "seasonal_inactive",
      "requires_investigation": false,
      "last_transaction_date": "2026-10-20",
      "inactivity_start_date": "2026-10-21",
      "open_days_without_activity": 0,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [
        "seasonal"
      ],
      "evidence": [
        "Last transaction date is 2026-10-20.",
        "Open days without activity through as_of_date: 0 (threshold 7).",
        "Status seasonal covers as_of_date from 2026-10-21 to 2026-11-30.",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified seasonal_inactive because a seasonal status record covers as_of_date."
      ]
    }
  ],
  "requiring_investigation": [
    {
      "outlet_id": "o1",
      "classification": "declining",
      "requires_investigation": true,
      "last_transaction_date": "2026-11-05",
      "open_days_without_activity": 1,
      "activity_decline_bps": 9445,
      "recent_volume": 3,
      "baseline_volume": 54,
      "active_status_kinds": [],
      "evidence": [
        "Last transaction date is 2026-11-05.",
        "Open days without activity through as_of_date: 1 (threshold 7).",
        "Recent 7-day volume 3 versus prior baseline window volume 54 gives decline_bps 9445 (threshold 5000).",
        "Caller expected_transactions_per_active_day is 10.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified declining because decline_bps 9445 meets decline_bps_threshold 5000."
      ]
    },
    {
      "outlet_id": "o2",
      "classification": "permanently_inactive",
      "requires_investigation": true,
      "last_transaction_date": "2026-09-01",
      "inactivity_start_date": "2026-09-02",
      "open_days_without_activity": 48,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [],
      "evidence": [
        "Last transaction date is 2026-09-01.",
        "Open days without activity through as_of_date: 48 (threshold 7).",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified permanently_inactive because open days without activity (48) meet permanent_days_threshold (30)."
      ]
    },
    {
      "outlet_id": "o3",
      "classification": "suspended",
      "requires_investigation": true,
      "last_transaction_date": "2026-08-01",
      "inactivity_start_date": "2026-08-02",
      "open_days_without_activity": 43,
      "recent_volume": 0,
      "baseline_volume": 0,
      "active_status_kinds": [
        "suspension"
      ],
      "evidence": [
        "Last transaction date is 2026-08-01.",
        "Open days without activity through as_of_date: 43 (threshold 7).",
        "Status suspension covers as_of_date from 2026-10-01 with no end_date.",
        "Baseline window volume is 0; decline_bps is not calculated.",
        "Schedule weekdays: Monday, Tuesday, Wednesday, Thursday, Friday.",
        "Classified suspended because a suspension status record covers as_of_date."
      ]
    }
  ],
  "explanations": [
    "Open days are calendar days that match the outlet schedule (or every day when no schedule is supplied) and are not covered by closure, suspension, or seasonal status records.",
    "open_days_without_activity counts open days after the last transaction (or after activation when there is none) through as_of_date.",
    "inactive_days_threshold marks temporary inactivity; permanent_days_threshold marks permanent inactivity when no covering status explains the gap.",
    "seasonal_inactive requires a seasonal status covering as_of_date. suspended and closed follow suspension/closure status records.",
    "activity_decline_bps = 10000 - floor(recent_volume * 10000 / baseline_volume) when baseline_volume > 0.",
    "Every classification lists the evidence strings used. No external industry dormancy rule is invented."
  ]
}
```

### POST /api/v1/agent-networks/cash-replenishment-route-plan

$0.04 USDC. 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.

Inputs: outlets, depots, vehicles, distances?, minutes_per_distance_unit?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-cash-replenishment-route-plan

Example request:

```json
{
  "outlets": [
    {
      "id": "o1",
      "latitude": 0.01,
      "longitude": 0,
      "replenishment_amount": 40000,
      "delivery_cost": 500
    },
    {
      "id": "o2",
      "latitude": 0,
      "longitude": 0.02,
      "replenishment_amount": 30000,
      "delivery_cost": 500
    },
    {
      "id": "o3",
      "latitude": -0.015,
      "longitude": 0.01,
      "replenishment_amount": 50000,
      "delivery_cost": 700
    },
    {
      "id": "o4",
      "latitude": 0.03,
      "longitude": -0.01,
      "replenishment_amount": 120000,
      "delivery_cost": 900
    }
  ],
  "depots": [
    {
      "id": "depot-a",
      "latitude": 0,
      "longitude": 0
    }
  ],
  "vehicles": [
    {
      "id": "van-1",
      "depot_id": "depot-a",
      "capacity": 100000,
      "cost_per_distance_unit": 2,
      "max_stops": 3
    },
    {
      "id": "van-2",
      "depot_id": "depot-a",
      "capacity": 80000,
      "cost_per_distance_unit": 2,
      "max_stops": 3
    }
  ],
  "distances": [
    {
      "from_id": "depot-a",
      "to_id": "o1",
      "distance": 1100
    },
    {
      "from_id": "o1",
      "to_id": "depot-a",
      "distance": 1100
    },
    {
      "from_id": "depot-a",
      "to_id": "o2",
      "distance": 2200
    },
    {
      "from_id": "o2",
      "to_id": "depot-a",
      "distance": 2200
    }
  ]
}
```

Example response:

```json
{
  "distance_basis": {
    "unit": "meters",
    "supplied_pairs": 4,
    "straight_line_pairs": 16,
    "note": "supplied_pairs count directed distances[] lookups. straight_line_pairs count rounded haversine meters from coordinates. Mapping or road-network APIs are not used."
  },
  "routes": [
    {
      "vehicle_id": "van-1",
      "depot_id": "depot-a",
      "stops": [
        {
          "sequence": 1,
          "outlet_id": "o1",
          "cash_allocated": 40000,
          "leg_distance": 1100,
          "leg_distance_source": "supplied",
          "cumulative_distance": 1100,
          "cumulative_cash": 40000
        },
        {
          "sequence": 2,
          "outlet_id": "o2",
          "cash_allocated": 30000,
          "leg_distance": 2486,
          "leg_distance_source": "straight_line",
          "cumulative_distance": 3586,
          "cumulative_cash": 70000
        }
      ],
      "return_leg_distance": 2200,
      "return_leg_distance_source": "supplied",
      "total_distance": 5786,
      "total_cash": 70000,
      "capacity": 100000,
      "capacity_utilization_bps": 7000,
      "stop_delivery_cost": 1000,
      "travel_cost": 11572,
      "delivery_cost": 12572
    },
    {
      "vehicle_id": "van-2",
      "depot_id": "depot-a",
      "stops": [
        {
          "sequence": 1,
          "outlet_id": "o3",
          "cash_allocated": 50000,
          "leg_distance": 2005,
          "leg_distance_source": "straight_line",
          "cumulative_distance": 2005,
          "cumulative_cash": 50000
        }
      ],
      "return_leg_distance": 2005,
      "return_leg_distance_source": "straight_line",
      "total_distance": 4010,
      "total_cash": 50000,
      "capacity": 80000,
      "capacity_utilization_bps": 6250,
      "stop_delivery_cost": 700,
      "travel_cost": 8020,
      "delivery_cost": 8720
    }
  ],
  "unserved_outlets": [
    {
      "outlet_id": "o4",
      "replenishment_amount": 120000,
      "reasons": [
        "replenishment_amount exceeds every vehicle capacity"
      ]
    }
  ],
  "totals": {
    "route_count": 2,
    "outlets_served": 3,
    "outlets_unserved": 1,
    "cash_delivered": 120000,
    "total_distance": 9796,
    "delivery_cost": 21292
  },
  "explanations": [
    "Routes are built with a capacitated nearest-neighbor heuristic from each vehicle depot, then improved with intra-route 2-opt. A second pass inserts unserved outlets at the cheapest feasible position.",
    "Each stop is served in full for its replenishment_amount. Partial fills and split deliveries are not created.",
    "Distance prefers a supplied distances[] entry for the directed pair. Otherwise rounded haversine meters are calculated from coordinates and labeled straight_line.",
    "capacity_utilization_bps = floor(total_cash * 10000 / capacity). travel_cost = total_distance * cost_per_distance_unit. delivery_cost adds optional per-outlet delivery_cost values.",
    "When time windows or due_minute are present, travel minutes = distance * minutes_per_distance_unit. Early arrivals wait until window_start_minute.",
    "No mapping, routing, or external optimization API is called."
  ]
}
```

### POST /api/v1/agent-networks/settlement-reconciliation

$0.04 USDC. 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.

Inputs: transactions, settlements

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-settlement-reconciliation

Example request:

```json
{
  "transactions": [
    {
      "id": "tx-1",
      "amount": 10000,
      "currency": "USD",
      "occurred_at": "2026-11-05T10:00:00.000Z",
      "fee": 100,
      "settlement_reference": "S-1"
    },
    {
      "id": "tx-2",
      "amount": 25000,
      "currency": "USD",
      "occurred_at": "2026-11-05T11:00:00.000Z",
      "fee": 200
    },
    {
      "id": "tx-3",
      "amount": 5000,
      "currency": "USD",
      "occurred_at": "2026-11-05T12:00:00.000Z"
    },
    {
      "id": "tx-4",
      "amount": 7000,
      "currency": "USD",
      "occurred_at": "2026-11-05T13:00:00.000Z"
    }
  ],
  "settlements": [
    {
      "id": "st-1",
      "amount": 10000,
      "currency": "USD",
      "settled_at": "2026-11-05T18:00:00.000Z",
      "fee": 150,
      "reference": "S-1"
    },
    {
      "id": "st-2",
      "amount": 24000,
      "currency": "USD",
      "settled_at": "2026-11-05T18:05:00.000Z",
      "fee": 200,
      "transaction_id": "tx-2"
    },
    {
      "id": "st-3",
      "amount": 7000,
      "currency": "USD",
      "settled_at": "2026-11-05T18:10:00.000Z"
    },
    {
      "id": "st-4",
      "amount": 7000,
      "currency": "USD",
      "settled_at": "2026-11-05T18:11:00.000Z"
    },
    {
      "id": "st-5",
      "amount": 900,
      "currency": "USD",
      "settled_at": "2026-11-05T18:12:00.000Z",
      "kind": "credit"
    }
  ]
}
```

Example response:

```json
{
  "matched": [
    {
      "transaction_id": "tx-1",
      "settlement_id": "st-1",
      "currency": "USD",
      "transaction_amount": 10000,
      "settlement_amount": 10000,
      "amount_delta": 0,
      "transaction_fee": 100,
      "settlement_fee": 150,
      "fee_delta": 50,
      "match_basis": "settlement.reference=transaction.settlement_reference",
      "status": "matched_with_discrepancy"
    },
    {
      "transaction_id": "tx-2",
      "settlement_id": "st-2",
      "currency": "USD",
      "transaction_amount": 25000,
      "settlement_amount": 24000,
      "amount_delta": -1000,
      "transaction_fee": 200,
      "settlement_fee": 200,
      "fee_delta": 0,
      "match_basis": "settlement.transaction_id",
      "status": "matched_with_discrepancy"
    }
  ],
  "missing_settlements": [
    {
      "transaction_id": "tx-3",
      "amount": 5000,
      "currency": "USD",
      "occurred_at": "2026-11-05T12:00:00.000Z",
      "evidence": [
        "No unique settlement row matched this transaction by transaction_id, settlement_reference, or currency+amount."
      ]
    }
  ],
  "unmatched_credits": [
    {
      "settlement_id": "st-5",
      "amount": 900,
      "currency": "USD",
      "settled_at": "2026-11-05T18:12:00.000Z",
      "kind": "credit",
      "evidence": [
        "No unique transaction matched this settlement row."
      ]
    }
  ],
  "duplicate_entries": [],
  "amount_discrepancies": [
    {
      "transaction_id": "tx-2",
      "settlement_id": "st-2",
      "currency": "USD",
      "transaction_amount": 25000,
      "settlement_amount": 24000,
      "amount_delta": -1000,
      "evidence": [
        "Settlement amount 24000 differs from transaction amount 25000 under settlement.transaction_id."
      ]
    }
  ],
  "fee_discrepancies": [
    {
      "transaction_id": "tx-1",
      "settlement_id": "st-1",
      "currency": "USD",
      "transaction_fee": 100,
      "settlement_fee": 150,
      "fee_delta": 50,
      "evidence": [
        "Settlement fee 150 differs from transaction fee 100 under settlement.reference=transaction.settlement_reference."
      ]
    }
  ],
  "ambiguous_matches": [
    {
      "transaction_id": "tx-4",
      "settlement_id": "st-3",
      "basis": "currency+amount",
      "amount_delta": 0,
      "fee_delta": 0,
      "evidence": [
        "Candidate linked by currency+amount but another equally plausible candidate exists or the link is not unique."
      ]
    },
    {
      "transaction_id": "tx-4",
      "settlement_id": "st-4",
      "basis": "currency+amount",
      "amount_delta": 0,
      "fee_delta": 0,
      "evidence": [
        "Candidate linked by currency+amount but another equally plausible candidate exists or the link is not unique."
      ]
    }
  ],
  "summary": {
    "transactions": 4,
    "settlements": 5,
    "matched": 2,
    "missing_settlements": 1,
    "unmatched_credits": 1,
    "ambiguous_matches": 2,
    "amount_discrepancies": 1,
    "fee_discrepancies": 1,
    "absolute_amount_gap": 1000,
    "absolute_fee_gap": 50
  },
  "explanations": [
    "Confirmed matches require a unique settlement.transaction_id, a unique settlement.reference equal to transaction.settlement_reference, or a unique currency+amount pair among unused rows.",
    "Ambiguous matches are listed separately and are not counted as confirmed. Silent confirmation is never applied when more than one candidate remains.",
    "amount_delta = settlement_amount - transaction_amount. fee_delta = settlement_fee - transaction_fee with missing fees treated as 0 only for delta math.",
    "No FX conversion is performed. Currencies must already match for a pair to be considered."
  ]
}
```

### POST /api/v1/agent-networks/shift-handover-audit

$0.04 USDC. 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.

Inputs: shifts, handovers?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-shift-handover-audit

Example request:

```json
{
  "shifts": [
    {
      "id": "shift-1",
      "agent_id": "ag-1",
      "started_at": "2026-11-05T08:00:00.000Z",
      "ended_at": "2026-11-05T16:00:00.000Z",
      "opening_cash": 100000,
      "closing_cash": 120000,
      "opening_float": 50000,
      "closing_float": 45000,
      "cash_count": 119000,
      "transaction_cash_in": 40000,
      "transaction_cash_out": 20000,
      "transaction_float_in": 0,
      "transaction_float_out": 5000,
      "adjustments": [
        {
          "id": "adj-1",
          "kind": "cash",
          "amount": 0
        }
      ]
    },
    {
      "id": "shift-2",
      "agent_id": "ag-1",
      "started_at": "2026-11-05T16:00:00.000Z",
      "ended_at": "2026-11-05T23:00:00.000Z",
      "opening_cash": 120000,
      "closing_cash": 110000,
      "opening_float": 45000,
      "closing_float": 47000,
      "transaction_cash_in": 10000,
      "transaction_cash_out": 20000,
      "transaction_float_in": 2000,
      "transaction_float_out": 0
    },
    {
      "id": "shift-3",
      "agent_id": "ag-1",
      "started_at": "2026-11-06T08:00:00.000Z",
      "ended_at": "2026-11-06T16:00:00.000Z",
      "opening_cash": 110000,
      "closing_cash": 110000,
      "opening_float": 47000,
      "closing_float": 47000
    }
  ],
  "handovers": [
    {
      "id": "ho-1",
      "from_shift_id": "shift-1",
      "to_shift_id": "shift-2",
      "cash_handed": 120000,
      "float_handed": 45000,
      "recorded_at": "2026-11-05T16:00:00.000Z"
    }
  ]
}
```

Example response:

```json
{
  "shift_audits": [
    {
      "shift_id": "shift-1",
      "agent_id": "ag-1",
      "expected_cash": 120000,
      "actual_cash": 119000,
      "cash_delta": -1000,
      "expected_float": 45000,
      "actual_float": 45000,
      "float_delta": 0,
      "closing_cash": 120000,
      "closing_float": 45000,
      "closing_cash_delta": 0,
      "closing_float_delta": 0,
      "evidence": [
        "expected_cash = opening_cash + transaction_cash_in - transaction_cash_out + cash adjustments = 120000.",
        "expected_float = opening_float + transaction_float_in - transaction_float_out + float adjustments = 45000."
      ]
    },
    {
      "shift_id": "shift-2",
      "agent_id": "ag-1",
      "expected_cash": 110000,
      "actual_cash": 110000,
      "cash_delta": 0,
      "expected_float": 47000,
      "actual_float": 47000,
      "float_delta": 0,
      "closing_cash": 110000,
      "closing_float": 47000,
      "closing_cash_delta": 0,
      "closing_float_delta": 0,
      "evidence": [
        "expected_cash = opening_cash + transaction_cash_in - transaction_cash_out + cash adjustments = 110000.",
        "expected_float = opening_float + transaction_float_in - transaction_float_out + float adjustments = 47000."
      ]
    },
    {
      "shift_id": "shift-3",
      "agent_id": "ag-1",
      "expected_cash": 110000,
      "actual_cash": 110000,
      "cash_delta": 0,
      "expected_float": 47000,
      "actual_float": 47000,
      "float_delta": 0,
      "closing_cash": 110000,
      "closing_float": 47000,
      "closing_cash_delta": 0,
      "closing_float_delta": 0,
      "evidence": [
        "expected_cash = opening_cash + transaction_cash_in - transaction_cash_out + cash adjustments = 110000.",
        "expected_float = opening_float + transaction_float_in - transaction_float_out + float adjustments = 47000."
      ]
    }
  ],
  "unexplained_discrepancies": [
    {
      "shift_id": "shift-1",
      "agent_id": "ag-1",
      "cash_delta": -1000,
      "float_delta": 0,
      "closing_cash_delta": 0,
      "closing_float_delta": 0,
      "evidence": [
        "Unexplained cash delta -1000 between actual and expected."
      ]
    }
  ],
  "missing_handovers": [
    {
      "from_shift_id": "shift-2",
      "to_shift_id": "shift-3",
      "agent_id": "ag-1",
      "evidence": [
        "Consecutive shifts for the same agent have no handover record."
      ]
    }
  ],
  "handover_findings": [
    {
      "handover_id": "ho-1",
      "from_shift_id": "shift-1",
      "to_shift_id": "shift-2",
      "status": "consistent",
      "cash_handed": 120000,
      "float_handed": 45000,
      "from_closing_cash": 120000,
      "from_closing_float": 45000,
      "to_opening_cash": 120000,
      "to_opening_float": 45000,
      "cash_vs_from_closing_delta": 0,
      "float_vs_from_closing_delta": 0,
      "to_opening_cash_vs_handed_delta": 0,
      "to_opening_float_vs_handed_delta": 0
    }
  ],
  "inconsistent_adjustments": [
    {
      "shift_id": "shift-1",
      "kind": "cash_count_vs_closing_cash",
      "cash_count": 119000,
      "closing_cash": 120000,
      "detail": "cash_count differs from closing_cash."
    }
  ],
  "summary": {
    "shifts": 3,
    "handovers": 1,
    "shifts_with_unexplained_discrepancies": 1,
    "missing_handovers": 1,
    "inconsistent_handovers": 0
  },
  "explanations": [
    "expected_cash = opening_cash + transaction_cash_in - transaction_cash_out + sum(cash adjustments).",
    "expected_float = opening_float + transaction_float_in - transaction_float_out + sum(float adjustments).",
    "actual_cash uses cash_count when supplied, otherwise closing_cash. actual_float uses electronic_float_balance when supplied, otherwise closing_float.",
    "Consecutive shifts for the same agent are ordered by started_at. A handover is expected between each consecutive pair.",
    "No external till or vault balance is invented."
  ]
}
```

### POST /api/v1/agent-networks/failed-transaction-dispute

$0.04 USDC. 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.

Inputs: dispute, events, receipts?, reversals?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-failed-transaction-dispute

Example request:

```json
{
  "dispute": {
    "id": "dsp-1",
    "transaction_id": "tx-9",
    "customer_claimed_amount": 15000,
    "currency": "USD",
    "claimed_at": "2026-11-05T15:00:00.000Z",
    "customer_detail": "Customer says the card was charged."
  },
  "events": [
    {
      "id": "ev-1",
      "transaction_id": "tx-9",
      "at": "2026-11-05T14:00:00.000Z",
      "type": "initiated",
      "amount": 15000,
      "source": "agent"
    },
    {
      "id": "ev-2",
      "transaction_id": "tx-9",
      "at": "2026-11-05T14:00:05.000Z",
      "type": "provider_response",
      "provider_code": "TIMEOUT",
      "detail": "No host response",
      "source": "provider"
    },
    {
      "id": "ev-3",
      "transaction_id": "tx-9",
      "at": "2026-11-05T14:00:06.000Z",
      "type": "failed",
      "amount": 15000,
      "source": "system"
    }
  ],
  "receipts": [
    {
      "id": "rc-1",
      "transaction_id": "tx-9",
      "amount": 15000,
      "issued_at": "2026-11-05T14:00:07.000Z",
      "status": "issued"
    }
  ],
  "reversals": []
}
```

Example response:

```json
{
  "dispute_id": "dsp-1",
  "transaction_id": "tx-9",
  "currency": "USD",
  "customer_claimed_amount": 15000,
  "timeline": [
    {
      "at": "2026-11-05T14:00:00.000Z",
      "kind": "event",
      "type": "initiated",
      "id": "ev-1",
      "amount": 15000,
      "source": "agent",
      "classification": "supplied_fact"
    },
    {
      "at": "2026-11-05T14:00:05.000Z",
      "kind": "event",
      "type": "provider_response",
      "id": "ev-2",
      "provider_code": "TIMEOUT",
      "detail": "No host response",
      "source": "provider",
      "classification": "supplied_fact"
    },
    {
      "at": "2026-11-05T14:00:06.000Z",
      "kind": "event",
      "type": "failed",
      "id": "ev-3",
      "amount": 15000,
      "source": "system",
      "classification": "supplied_fact"
    },
    {
      "at": "2026-11-05T14:00:07.000Z",
      "kind": "receipt",
      "type": "issued",
      "id": "rc-1",
      "amount": 15000,
      "classification": "supplied_fact"
    },
    {
      "at": "2026-11-05T15:00:00.000Z",
      "kind": "dispute",
      "type": "customer_claim",
      "id": "dsp-1",
      "amount": 15000,
      "detail": "Customer says the card was charged.",
      "classification": "customer_claim"
    }
  ],
  "conflicting_evidence": [
    {
      "code": "receipt_without_settled_event",
      "detail": "An active receipt exists while events include failed and do not include settled. Success is not inferred.",
      "receipt_ids": [
        "rc-1"
      ]
    }
  ],
  "missing_lifecycle_events": [
    {
      "code": "missing_reversal_after_failed_with_receipt",
      "detail": "Failed event plus active receipt without a reversal record."
    }
  ],
  "possible_duplicate_charges": [],
  "reversal_inconsistencies": [],
  "assessment": "evidence_conflict",
  "assessment_evidence": [
    "Conflicting lifecycle or receipt facts were supplied. No success state is invented."
  ],
  "explanations": [
    "Timeline entries are only created from supplied events, receipts, reversals, and the dispute claim.",
    "A successful payment is never inferred from absence of failure. settled must be present as a supplied fact.",
    "Ambiguous or conflicting records produce evidence_conflict or inconclusive assessments rather than a silent confirmation."
  ]
}
```

### POST /api/v1/agent-networks/terminal-downtime-impact

$0.04 USDC. 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.

Inputs: terminals, outages, history?, averages?

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-terminal-downtime-impact

Example request:

```json
{
  "terminals": [
    {
      "id": "term-1",
      "agent_id": "ag-1",
      "location_id": "loc-a"
    },
    {
      "id": "term-2",
      "agent_id": "ag-2",
      "location_id": "loc-b"
    }
  ],
  "outages": [
    {
      "id": "out-1",
      "terminal_id": "term-1",
      "started_at": "2026-11-05T10:00:00.000Z",
      "ended_at": "2026-11-05T13:00:00.000Z"
    },
    {
      "id": "out-2",
      "terminal_id": "term-2",
      "started_at": "2026-11-05T09:00:00.000Z",
      "ended_at": "2026-11-05T10:30:00.000Z"
    }
  ],
  "history": [
    {
      "terminal_id": "term-1",
      "date": "2026-11-05",
      "transaction_count": 4,
      "transaction_value": 8000,
      "commission": 80
    }
  ],
  "averages": [
    {
      "terminal_id": "term-1",
      "transactions_per_hour": 10,
      "average_transaction_value": 2000,
      "commission_bps": 100
    },
    {
      "terminal_id": "term-2",
      "transactions_per_hour": 6,
      "average_transaction_value": 1500,
      "commission_bps": 100
    }
  ]
}
```

Example response:

```json
{
  "outage_impacts": [
    {
      "outage_id": "out-1",
      "terminal_id": "term-1",
      "agent_id": "ag-1",
      "location_id": "loc-a",
      "started_at": "2026-11-05T10:00:00.000Z",
      "ended_at": "2026-11-05T13:00:00.000Z",
      "downtime_minutes": 180,
      "measured_transaction_count": 4,
      "measured_transaction_value": 8000,
      "measured_commission": 80,
      "measurement_basis": "Measured from 1 history row(s) on outage start date 2026-11-05. These are observed totals for that date, not lost volume.",
      "estimated_lost_transactions": 30,
      "estimated_lost_value": 60000,
      "estimated_lost_commission": 600,
      "estimate_basis": "Estimate uses transactions_per_hour 10 over 180 downtime minutes (floor hours plus residual minutes).",
      "priority_score": 600
    },
    {
      "outage_id": "out-2",
      "terminal_id": "term-2",
      "agent_id": "ag-2",
      "location_id": "loc-b",
      "started_at": "2026-11-05T09:00:00.000Z",
      "ended_at": "2026-11-05T10:30:00.000Z",
      "downtime_minutes": 90,
      "estimated_lost_transactions": 9,
      "estimated_lost_value": 13500,
      "estimated_lost_commission": 135,
      "estimate_basis": "Estimate uses transactions_per_hour 6 over 90 downtime minutes (floor hours plus residual minutes).",
      "priority_score": 135
    }
  ],
  "downtime_ranking": [
    {
      "terminal_id": "term-1",
      "agent_id": "ag-1",
      "location_id": "loc-a",
      "outage_count": 1,
      "downtime_minutes": 180,
      "estimated_lost_transactions": 30,
      "estimated_lost_value": 60000,
      "estimated_lost_commission": 600,
      "priority_score": 600
    },
    {
      "terminal_id": "term-2",
      "agent_id": "ag-2",
      "location_id": "loc-b",
      "outage_count": 1,
      "downtime_minutes": 90,
      "estimated_lost_transactions": 9,
      "estimated_lost_value": 13500,
      "estimated_lost_commission": 135,
      "priority_score": 135
    }
  ],
  "restoration_priority": [
    {
      "rank": 1,
      "terminal_id": "term-1",
      "agent_id": "ag-1",
      "location_id": "loc-a",
      "priority_score": 600,
      "reason": "Highest estimated lost commission 600."
    },
    {
      "rank": 2,
      "terminal_id": "term-2",
      "agent_id": "ag-2",
      "location_id": "loc-b",
      "priority_score": 135,
      "reason": "Highest estimated lost commission 135."
    }
  ],
  "affected_agents": [
    "ag-1",
    "ag-2"
  ],
  "summary": {
    "terminals": 2,
    "outages": 2,
    "total_downtime_minutes": 270,
    "estimated_lost_transactions": 39,
    "estimated_lost_value": 73500,
    "estimated_lost_commission": 735
  },
  "explanations": [
    "measured_* fields come only from history rows on the outage start date. They are observed activity, not calculated losses.",
    "estimated_lost_* fields come only from supplied averages.transactions_per_hour and optional average_transaction_value / commission_bps.",
    "estimated_lost_transactions = transactions_per_hour * floor(downtime_minutes/60) + floor(transactions_per_hour * (downtime_minutes%60) / 60).",
    "estimated_lost_commission = floor(estimated_lost_value * commission_bps / 10000) when both value and commission_bps are available.",
    "priority_score prefers estimated lost commission, then value, then transactions, then downtime minutes. No market benchmark is invented."
  ]
}
```

### POST /api/v1/agent-networks/agent-dispute-evidence

$0.04 USDC. 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.

Inputs: dispute, records

Docs: https://www.brainiac.software/api/agent-networks/docs#agent-networks-agent-dispute-evidence

Example request:

```json
{
  "dispute": {
    "id": "ad-1",
    "agent_id": "ag-1",
    "currency": "USD",
    "disputed_amount": 5000,
    "opened_at": "2026-11-06T12:00:00.000Z",
    "categories": [
      "balance",
      "commission",
      "cash_deposit"
    ],
    "detail": "Agent disputes a settlement deduction."
  },
  "records": [
    {
      "id": "r1",
      "at": "2026-11-05T08:00:00.000Z",
      "kind": "balance_snapshot",
      "balance": 100000,
      "currency": "USD"
    },
    {
      "id": "r2",
      "at": "2026-11-05T10:00:00.000Z",
      "kind": "transaction",
      "amount": 20000,
      "currency": "USD",
      "reference": "tx-1"
    },
    {
      "id": "r3",
      "at": "2026-11-05T11:00:00.000Z",
      "kind": "commission",
      "amount": 5000,
      "currency": "USD",
      "reference": "tx-1"
    },
    {
      "id": "r4",
      "at": "2026-11-05T12:00:00.000Z",
      "kind": "cash_deposit",
      "amount": -15000,
      "currency": "USD"
    },
    {
      "id": "r5",
      "at": "2026-11-05T18:00:00.000Z",
      "kind": "balance_snapshot",
      "balance": 108000,
      "currency": "USD"
    },
    {
      "id": "r6",
      "at": "2026-11-05T18:30:00.000Z",
      "kind": "settlement",
      "amount": -5000,
      "currency": "USD",
      "detail": "Deduction under review"
    }
  ]
}
```

Example response:

```json
{
  "dispute_id": "ad-1",
  "agent_id": "ag-1",
  "currency": "USD",
  "disputed_amount": 5000,
  "timeline": [
    {
      "id": "r1",
      "at": "2026-11-05T08:00:00.000Z",
      "kind": "balance_snapshot",
      "balance": 100000,
      "classification": "verified_fact"
    },
    {
      "id": "r2",
      "at": "2026-11-05T10:00:00.000Z",
      "kind": "transaction",
      "amount": 20000,
      "reference": "tx-1",
      "classification": "verified_fact"
    },
    {
      "id": "r3",
      "at": "2026-11-05T11:00:00.000Z",
      "kind": "commission",
      "amount": 5000,
      "reference": "tx-1",
      "classification": "verified_fact"
    },
    {
      "id": "r4",
      "at": "2026-11-05T12:00:00.000Z",
      "kind": "cash_deposit",
      "amount": -15000,
      "classification": "verified_fact"
    },
    {
      "id": "r5",
      "at": "2026-11-05T18:00:00.000Z",
      "kind": "balance_snapshot",
      "balance": 108000,
      "classification": "verified_fact"
    },
    {
      "id": "r6",
      "at": "2026-11-05T18:30:00.000Z",
      "kind": "settlement",
      "amount": -5000,
      "detail": "Deduction under review",
      "classification": "verified_fact"
    }
  ],
  "inconsistencies": [
    {
      "code": "unexplained_balance_change",
      "from_record_id": "r1",
      "to_record_id": "r5",
      "from_balance": 100000,
      "to_balance": 108000,
      "explained_movement": 10000,
      "expected_balance": 110000,
      "unexplained_delta": -2000,
      "classification": "inconsistency",
      "evidence": [
        "Balance moved from 100000 to 108000 while signed intervening amounts sum to 10000."
      ]
    },
    {
      "code": "reference_amount_conflict",
      "reference": "tx-1",
      "record_ids": [
        "r2",
        "r3"
      ],
      "classification": "inconsistency",
      "evidence": [
        "Records that share a reference disagree on amount."
      ]
    }
  ],
  "missing_evidence": [],
  "disputed_amount_breakdown": [
    {
      "category": "balance",
      "record_count": 0,
      "signed_amount_total": 0,
      "record_ids": []
    },
    {
      "category": "commission",
      "record_count": 1,
      "signed_amount_total": 5000,
      "record_ids": [
        "r3"
      ]
    },
    {
      "category": "cash_deposit",
      "record_count": 1,
      "signed_amount_total": -15000,
      "record_ids": [
        "r4"
      ]
    }
  ],
  "resolution_report": {
    "verified_fact_count": 6,
    "inconsistency_count": 2,
    "missing_evidence_count": 0,
    "status": "needs_review",
    "summary": "Supplied records contain inconsistencies or gaps that require human review. No party liability is assigned."
  },
  "explanations": [
    "Every timeline row is a verified_fact only in the sense that it was supplied by the caller. Nothing outside the request is fetched.",
    "Balance transitions are checked against intervening signed amounts. Residual deltas are inconsistencies, not automatic fault findings.",
    "Missing evidence is reported when a declared dispute category has no supporting record kinds or when no record amount matches disputed_amount.",
    "The API does not decide the dispute outcome or invent compensating transactions."
  ]
}
```