Adds fiat settlement entry formatting

Introduces a function to format fiat settlement entries for Beancount, handling cash, bank transfers, and other non-lightning payments.

This allows for recording transactions in fiat currency with sats as metadata.

Updates the API endpoint to use the new function when settling receivables with fiat currencies.

beancount_format.py

@@ -528,6 +528,112 @@ def format_payment_entry(
     )
 
 
+def format_fiat_settlement_entry(
+    user_id: str,
+    payment_account: str,
+    payable_or_receivable_account: str,
+    fiat_amount: Decimal,
+    fiat_currency: str,
+    amount_sats: int,
+    description: str,
+    entry_date: date,
+    is_payable: bool = True,
+    payment_method: str = "cash",
+    reference: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Format a fiat (cash/bank) settlement entry.
+
+    Unlike Lightning payments, fiat settlements use fiat currency as the primary amount
+    with SATS stored as metadata for reference.
+
+    Args:
+        user_id: User ID
+        payment_account: Payment method account (e.g., "Assets:Cash", "Assets:Bank")
+        payable_or_receivable_account: User's account being settled
+        fiat_amount: Amount in fiat currency (unsigned)
+        fiat_currency: Fiat currency code (EUR, USD, etc.)
+        amount_sats: Equivalent amount in satoshis (for metadata only)
+        description: Payment description
+        entry_date: Date of settlement
+        is_payable: True if castle paying user (payable), False if user paying castle (receivable)
+        payment_method: Payment method (cash, bank_transfer, check, etc.)
+        reference: Optional reference
+
+    Returns:
+        Fava API entry dict
+    """
+    fiat_amount_abs = abs(fiat_amount)
+    amount_sats_abs = abs(amount_sats)
+
+    if is_payable:
+        # Castle paying user: DR Payable, CR Cash/Bank
+        postings = [
+            {
+                "account": payable_or_receivable_account,
+                "amount": f"{fiat_amount_abs:.2f} {fiat_currency}",
+                "meta": {
+                    "sats-equivalent": str(amount_sats_abs)
+                }
+            },
+            {
+                "account": payment_account,
+                "amount": f"-{fiat_amount_abs:.2f} {fiat_currency}",
+                "meta": {
+                    "sats-equivalent": str(amount_sats_abs)
+                }
+            }
+        ]
+    else:
+        # User paying castle: DR Cash/Bank, CR Receivable
+        postings = [
+            {
+                "account": payment_account,
+                "amount": f"{fiat_amount_abs:.2f} {fiat_currency}",
+                "meta": {
+                    "sats-equivalent": str(amount_sats_abs)
+                }
+            },
+            {
+                "account": payable_or_receivable_account,
+                "amount": f"-{fiat_amount_abs:.2f} {fiat_currency}",
+                "meta": {
+                    "sats-equivalent": str(amount_sats_abs)
+                }
+            }
+        ]
+
+    # Map payment method to appropriate source and tag
+    payment_method_map = {
+        "cash": ("cash_settlement", "cash-payment"),
+        "bank_transfer": ("bank_settlement", "bank-transfer"),
+        "check": ("check_settlement", "check-payment"),
+        "btc_onchain": ("onchain_settlement", "onchain-payment"),
+        "other": ("manual_settlement", "manual-payment")
+    }
+
+    source, tag = payment_method_map.get(payment_method.lower(), ("manual_settlement", "manual-payment"))
+
+    entry_meta = {
+        "user-id": user_id,
+        "source": source
+    }
+
+    links = []
+    if reference:
+        links.append(reference)
+
+    return format_transaction(
+        date_val=entry_date,
+        flag="*",  # Cleared (payment already happened)
+        narration=description,
+        postings=postings,
+        tags=[tag],
+        links=links,
+        meta=entry_meta
+    )
+
+
 def format_net_settlement_entry(
     user_id: str,
     payment_account: str,