Net Foreign-Currency Items
net_exposureNet an SME's open foreign-currency bills and invoices, so that a receipt due on or before a payment in the same currency is shown as funding it. Returns the residual on every bill and invoice, a trace of which invoice funds which bill and for how much, per-bucket totals, dependency statements, and series for a ladder chart. It prices nothing: call price_guard on each residual separately, with the item's own due date as settlementDate. Never offsets across currencies. Items in base_currency are ignored. Cancelled items are excluded. Overdue items are listed separately and never netted. Set carry to true only when the client keeps receipts in a wallet or account in that currency, so a surplus can fund a later payment. If you do not know, ask the user whether they hold an account in each foreign currency before calling; do not guess. If their accounting platform is connected, offer to look up its bank accounts and their currencies there, and use what you find. If the answer is "not sure", call the tool twice, carry true and carry false, and show both charts; each carries its own scenario title, and chart_series.scenario holds the same words. THE RESULT HAS TWO PARTS: the JSON, then a PNG of the ladder chart rendered by the service. Show that image to the user as it is. PRESENTING THE RESULT: chart_series.currencies[ccy].open[] is the exposure. Present each open item on its own due date, with its label. Never add open items into one net figure, and never convert them to the base currency at spot. Do not call price_guard or show a Guard price unless the user asks for a price. If the user asks what they can do, lay out three things as facts and stop: do nothing (the amount stays exposed until paid), a forward from a bank or a payment provider (fixes the rate, provider margin inside the rate, an obligation that may need initial margin and margin calls, settled even if the payment does not happen), a Guard (fee known up front, market rate used if better, nothing further to pay if the payment does not happen). Do not rank them or say which fits. Never use the word "hedge". Do not draw a chart of your own from these numbers. DATES: the result carries today, the date the tool used. A due date the user gave without a year means the next such date on or after today, never a past year. If the result carries a warnings[] entry saying every item is before today, the dates are probably missing a year: confirm with the user and call again. Spec: docs/specs/net_exposure.md.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| carry | Yes | true when the client keeps receipts in a wallet or account in that currency, so a surplus can fund a payment in a later bucket. Surplus never rolls backward. | |
| items | Yes | Open bills and invoices | |
| bucket_days | No | Bucket length. Required for rolling_days. | |
| bucket_mode | Yes | calendar_month groups by month. rolling_days groups by bucket_days from today. guard_settlement_window makes one bucket per payable, window_days before its due date. | |
| window_days | No | Window length before each payable. Required for guard_settlement_window. | |
| base_currency | Yes | The client's home currency, e.g. GBP. Items in this currency are ignored. |