#78 fix Pix/DePix smoke-test findings (nonce format, approved status, error detail, flat fee disclosure) (#79)

- Send X-Nonce as dashed UUID (str(uuid.uuid4())); Eulen rejected hex form with HTTP 400.
- Recognize Eulen intermediate status "approved" (Pix received, DePix in flight) instead of warning "unknown status".
- Extract error detail from Eulen's wrapped {"response": {"errorMessage": ...}} on 4xx so root cause surfaces.
- Surface Eulen's flat R$0,99 per-operation fee in pix_receive (fee_cents, fee_brl, net_amount_cents, net_amount_brl + message); MCP tool description and receive_via_pix prompt updated accordingly.
- Tests: update nonce regex to dashed UUID; add coverage for response.errorMessage extraction, approved-status persistence, and fee/net reporting in the tool layer.

Author: andycreed0x

src/aqua/pix.py

@@ -24,10 +24,15 @@
 # explain it to the user rather than passing the raw API error through.
 PIX_MIN_AMOUNT_CENTS = 100  # R$1.00 — Eulen's documented absolute minimum
 
+# Flat fee Eulen deducts from every Pix→DePix operation, independent of amount.
+# Not returned by the API; documented here so the tool layer can surface it.
+EULEN_FEE_CENTS = 99  # R$0,99
+
 # Eulen status values returned by GET /deposit-status.
 EULEN_STATUS_VALUES = frozenset(
     {
         "pending",
+        "approved",
         "depix_sent",
         "under_review",
         "canceled",
@@ -102,7 +107,7 @@ def _api_request(
                 "Content-Type": "application/json",
                 "User-Agent": "agentic-aqua",
                 "Authorization": f"Bearer {self.token}",
-                "X-Nonce": uuid.uuid4().hex,
+                "X-Nonce": str(uuid.uuid4()),
             },
         )
         try:
@@ -112,7 +117,12 @@ def _api_request(
             detail = ""
             try:
                 err_body = json.loads(e.read().decode())
-                detail = err_body.get("error") or err_body.get("message") or ""
+                detail = (
+                    err_body.get("error")
+                    or err_body.get("message")
+                    or (err_body.get("response") or {}).get("errorMessage")
+                    or ""
+                )
             except Exception:
                 pass
             msg = f"Eulen API error ({e.code} {method} {path})"
@@ -162,6 +172,7 @@ def format_brl(amount_cents: int) -> str:
 
 _STATUS_MESSAGES = {
     "pending": "Waiting for Pix payment. Pay the QR / Copia e Cola in your banking app.",
+    "approved": "Pix payment received. DePix transfer in progress — should arrive shortly.",
     "depix_sent": "DePix delivered to your Liquid wallet.",
     "under_review": "Eulen is reviewing the payment (compliance/AML). This may take time.",
     "canceled": "The deposit was canceled.",

src/aqua/server.py

@@ -460,7 +460,7 @@
         },
     },
     "pix_receive": {
-        "description": "Mint a Pix charge (Brazil) that pays out DePix (BRL stablecoin on Liquid) to the named wallet's next address. Returns the Pix Copia e Cola string and a hosted QR image URL — the user pays from their banking app. Amount is in BRL CENTS (100 = R$1.00). Requires EULEN_API_TOKEN env var.",
+        "description": "Mint a Pix charge (Brazil) that pays out DePix (BRL stablecoin on Liquid) to the named wallet's next address. Returns the Pix Copia e Cola string and a hosted QR image URL — the user pays from their banking app. Amount is in BRL CENTS (100 = R$1.00). Eulen deducts a FLAT FEE of R$0,99 per operation (regardless of amount), so DePix received = amount_cents − 99. The response includes fee_cents, fee_brl, net_amount_cents and net_amount_brl so the user can see the expected net up-front. Requires EULEN_API_TOKEN env var.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -482,7 +482,7 @@
         },
     },
     "pix_status": {
-        "description": "Check the status of a Pix → DePix deposit. Status values: pending, depix_sent, under_review, canceled, error, refunded, expired. Eulen delivers DePix automatically — no claim step.",
+        "description": "Check the status of a Pix → DePix deposit. Status values: pending, approved (Pix received, DePix in flight), depix_sent, under_review, canceled, error, refunded, expired. Eulen delivers DePix automatically — no claim step.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -1860,13 +1860,14 @@ async def get_prompt(name: str, arguments: dict[str, str] | None) -> GetPromptRe
 1. Verify the EULEN_API_TOKEN environment variable is set. If not, tell me to obtain one from https://depix.info/#partners and stop here.
 2. Ask me how much I want to deposit, IN REAIS (e.g. "R$50"). Convert to cents (R$50 → 5000 cents) before calling pix_receive. Be explicit about the unit so I do not get a 100× error.
 3. Mention the practical first-time limit on Eulen is around R$500; offer to use a smaller amount if mine is higher.
-4. Call pix_receive(amount_cents=…, wallet_name='{wallet_name}').
-5. Show me BOTH:
+4. BEFORE calling pix_receive, tell me Eulen will deduct a FLAT FEE of R$0,99 from the amount I pay (independent of the amount), so I will receive `amount − R$0,99` in DePix. Confirm the amount with me knowing this.
+5. Call pix_receive(amount_cents=…, wallet_name='{wallet_name}').
+6. Show me BOTH:
    - The `qr_copy_paste` string (EMV BR-Code) — I can paste this into my banking app's "Pix Copia e Cola" field.
    - The `qr_image_url` — I can open this on my phone and scan the QR with my bank app.
-   Explain I only need to do ONE of those, not both.
-6. After I confirm I have paid, call pix_status(swap_id=…) and report the status. Re-check on request until status="depix_sent" (DePix delivered) or a terminal failure.
-7. When delivered, show the `blockchain_txid` (Liquid txid) so I can verify on a block explorer.""",
+   Explain I only need to do ONE of those, not both. Also surface `net_amount_brl` so I see the exact DePix I will receive after the R$0,99 fee.
+7. After I confirm I have paid, call pix_status(swap_id=…) and report the status. Re-check on request until status="depix_sent" (DePix delivered) or a terminal failure. Status "approved" is an intermediate step (Pix received, DePix in flight) — not a failure.
+8. When delivered, show the `blockchain_txid` (Liquid txid) so I can verify on a block explorer.""",
                         ),
                     )
                 ]

src/aqua/tools.py

@@ -892,9 +892,13 @@ def pix_receive(
     manager = get_pix_manager()
     swap = manager.create_deposit(amount_cents, wallet_name, password)
 
-    from .pix import format_brl
+    from .pix import EULEN_FEE_CENTS, format_brl
 
     amount_brl = format_brl(swap.amount_cents)
+    fee_cents = EULEN_FEE_CENTS
+    fee_brl = format_brl(fee_cents)
+    net_amount_cents = max(swap.amount_cents - fee_cents, 0)
+    net_amount_brl = format_brl(net_amount_cents)
     all_wallets = get_manager().storage.list_wallets()
     wallet_note = f" in wallet '{wallet_name}'" if len(all_wallets) > 1 else ""
     return {
@@ -903,13 +907,19 @@ def pix_receive(
         "qr_image_url": swap.qr_image_url,
         "amount_cents": swap.amount_cents,
         "amount_brl": amount_brl,
+        "fee_cents": fee_cents,
+        "fee_brl": fee_brl,
+        "net_amount_cents": net_amount_cents,
+        "net_amount_brl": net_amount_brl,
         "depix_address": swap.depix_address,
         "expiration": swap.expiration,
         "wallet_name": wallet_name,
         "message": (
             f"Pay {amount_brl} via Pix to receive DePix{wallet_note}. "
             "Paste qr_copy_paste into your banking app's 'Pix Copia e Cola' field, "
             "or open qr_image_url on your phone and scan with your bank app. "
+            f"Note: Eulen deducts a flat fee of {fee_brl} per deposit, so you will "
+            f"receive {net_amount_brl} in DePix. "
             f"Check status with swap_id: {swap.swap_id}"
         ),
     }

tests/test_pix.py

@@ -191,8 +191,13 @@ def test_create_deposit_sends_bearer_and_nonce(self):
             assert called_req.full_url.endswith("/deposit")
             assert called_req.headers["Authorization"] == "Bearer test-token-xyz"
             nonce = called_req.headers["X-nonce"]  # urllib lowercases the second char
-            # nonce should be a uuid4 hex (32 chars, lowercase hex)
-            assert re.fullmatch(r"[0-9a-f]{32}", nonce)
+            # Eulen requires the standard dashed UUID format (8-4-4-4-12). The
+            # 32-char hex form was rejected with HTTP 400 "Not a valid UUID."
+            # See issue #78.
+            assert re.fullmatch(
+                r"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}",
+                nonce,
+            )
             body = json.loads(called_req.data.decode())
             assert body == {"amountInCents": 5000, "depixAddress": "lq1test"}
 
@@ -209,6 +214,24 @@ def test_create_deposit_http_error_includes_detail(self):
             assert "invalid amount" in str(exc.value)
             assert "400" in str(exc.value)
 
+    def test_create_deposit_http_error_extracts_response_errorMessage(self):
+        # Eulen wraps 4xx detail inside {"response": {"errorMessage": "..."}}.
+        # The previous error handler only looked at top-level "error"/"message",
+        # so the useful cause was silently dropped — see issue #78 finding 3.
+        client = EulenClient()
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            err = urllib.error.HTTPError("url", 400, "Bad Request", {}, MagicMock())
+            err.read = MagicMock(
+                return_value=json.dumps(
+                    {"response": {"errorMessage": "Invalid X-Nonce header value - Not a valid UUID."}}
+                ).encode()
+            )
+            mock_urlopen.side_effect = err
+            with pytest.raises(RuntimeError) as exc:
+                client.create_deposit(5000, "lq1test")
+            assert "Invalid X-Nonce" in str(exc.value)
+            assert "400" in str(exc.value)
+
     def test_create_deposit_http_error_empty_body_omits_literal_braces(self):
         # An HTTP error with an empty (or unrecognised-shape) JSON body must
         # not surface "{}" or "{'foo': 'bar'}" as a fake "error detail" —
@@ -371,6 +394,34 @@ def test_pending_to_settled_transition_persists(self, test_wallet):
         assert reloaded.status == "depix_sent"
         assert reloaded.blockchain_txid == "deadbeef" * 8
 
+    def test_approved_status_recognized_and_persisted(self, test_wallet):
+        # Eulen returns "approved" as the intermediate "Pix received, DePix
+        # in flight" state. Before issue #78, this was logged as an unknown
+        # status and the cached "pending" was kept — confusing the user.
+        storage, wm = test_wallet
+        seeded = self._seed_swap(storage, wm)
+
+        manager = PixManager(storage=storage, wallet_manager=wm)
+        approved_resp = {
+            "response": {
+                "status": "approved",
+                "valueInCents": 5000,
+                "expiration": "2026-05-08T23:59:59Z",
+            },
+            "async": False,
+        }
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = _mock_response(approved_resp)
+            result = manager.get_deposit_status(seeded.swap_id)
+
+        assert result["status"] == "approved"
+        assert "warning" not in result
+        assert "Pix payment received" in result["message"]
+
+        reloaded = storage.load_pix_swap(seeded.swap_id)
+        assert reloaded is not None
+        assert reloaded.status == "approved"
+
     def test_warning_on_remote_failure(self, test_wallet):
         storage, wm = test_wallet
         seeded = self._seed_swap(storage, wm)
@@ -494,6 +545,24 @@ def test_pix_receive_returns_qr_payload(self, test_wallet):
         assert result["amount_brl"] == "R$50,00"
         assert "Copia e Cola" in result["message"]
 
+    def test_pix_receive_reports_fee_and_net(self, test_wallet):
+        # Eulen charges a flat R$0,99 per operation. The tool must surface
+        # both the fee and the expected net DePix so the user is not
+        # surprised on settlement — see issue #78 finding 4.
+        from aqua.pix import EULEN_FEE_CENTS
+        from aqua.tools import pix_receive
+
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = _mock_response(MOCK_DEPOSIT_RESPONSE)
+            result = pix_receive(amount_cents=5000)
+
+        assert result["fee_cents"] == EULEN_FEE_CENTS == 99
+        assert result["fee_brl"] == "R$0,99"
+        assert result["net_amount_cents"] == 5000 - 99
+        assert result["net_amount_brl"] == "R$49,01"
+        assert "R$0,99" in result["message"]
+        assert "R$49,01" in result["message"]
+
     def test_pix_status_dispatches(self, test_wallet):
         from aqua.tools import pix_receive, pix_status