[READY] Feature: Alfredpay Fiat Accounts

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "linear-server": {
+      "type": "sse",
+      "url": "https://mcp.linear.app/sse"
+    },
+    "obsidian": {
+      "args": ["-y", "obsidian-mcp", "$OBSIDIAN_VAULT_PATH"],
+      "command": "npx"
+    }
+  }
+}

CLAUDE.md

@@ -18,6 +18,8 @@ This is a **Bun monorepo** using workspaces:
 
 ## Essential Commands
 
+> Always use `bun`- never `npm`, `yarn`, or `pnpm`. Run `bun lint:fix` after any code change.
+
 ```bash
 # Install all dependencies
 bun install
@@ -70,7 +72,7 @@ Phase metadata and valid transitions are stored in PostgreSQL and seeded via `se
 ### Frontend Architecture
 
 - **State**: Zustand stores (`stores/`) + React Context (`contexts/`)
-- **Forms**: React Hook Form with Yup validation
+- **Forms**: React Hook Form with Zod validation (not Yup)
 - **Data Fetching**: TanStack Query
 - **Routing**: TanStack Router (route tree auto-generated in `routeTree.gen.ts`)
 - **State Machines**: XState machines in `machines/` for complex flows (KYC, ramp process)
@@ -95,6 +97,8 @@ Contains cross-package utilities:
 
 **Important**: Always rebuild shared when making changes: `bun build:shared`
 
+After ANY change to `packages/shared`, run `bun build:shared` before running frontend/api.
+
 ## Code Style Guidelines
 
 From `.clinerules/`:
@@ -110,6 +114,11 @@ From `.clinerules/`:
 - Extract complex conditional rendering into new components
 - Skip useless comments; only comment race conditions, TODOs, or genuinely confusing code
 
+### XState v5
+- Use `setup({ ... }).createMachine(...)` API- not `createMachine` directly
+- Actor refs from `useActor` / `useSelector` from `@xstate/react`
+- Machine files live in `apps/frontend/src/machines/`
+
 ### Biome Configuration
 - Line width: 128
 - Indent: 2 spaces
@@ -118,6 +127,22 @@ From `.clinerules/`:
 - Quote style: double
 - Sorted Tailwind classes enforced via `useSortedClasses` rule
 
+## Token Exhaustiveness
+
+`FiatToken` currently has 6 values: `EURC`, `ARS`, `BRL`, `USD`, `MXN`, `COP`.
+
+Any `Record<FiatToken, X>` must include ALL six. Missing entries cause TypeScript errors
+when shared is rebuilt. Check: tokenAvailability, mapFiatToDestination, success page
+ARRIVAL_TEXT_BY_TOKEN, sep10 tokenMapping.
+
+## No Over-Engineering
+
+- Don't add features, refactors, or "improvements" beyond what was asked
+- Don't add docstrings/comments to code you didn't touch
+- Don't create helpers/utilities for one-time operations
+- Don't validate inputs that can't be invalid (internal calls, typed params)
+- Three similar lines is better than a premature abstraction
+
 ## Testing
 
 ### Backend Integration Tests

apps/api/src/api/controllers/alfredpay.controller.ts

@@ -6,14 +6,10 @@ import {
   AlfredpayCreateCustomerResponse,
   AlfredpayCustomerType,
   AlfredpayGetKybRedirectLinkResponse,
-  AlfredpayGetKybStatusResponse,
   AlfredpayGetKycRedirectLinkRequest,
   AlfredpayGetKycRedirectLinkResponse,
-  AlfredpayGetKycStatusRequest,
   AlfredpayGetKycStatusResponse,
   AlfredpayKybStatus,
-  AlfredpayKycRedirectFinishedRequest,
-  AlfredpayKycRedirectOpenedRequest,
   AlfredpayKycStatus,
   AlfredpayStatusRequest,
   AlfredpayStatusResponse
@@ -258,10 +254,8 @@ export class AlfredpayController {
         : await alfredpayService.getKycStatus(alfredPayCustomer.alfredPayId, lastSubmission.submissionId);
 
       const newStatus = AlfredpayController.mapKycStatus(statusResponse.status);
-      console.log("newStatus", newStatus);
       const updateData: Partial<AlfredPayCustomer> = {};
 
-      console.log("our status", alfredPayCustomer.status);
       if (newStatus && newStatus !== alfredPayCustomer.status) {
         updateData.status = newStatus;
       }

apps/api/src/api/services/phases/handlers/final-settlement-subsidy.ts

@@ -8,7 +8,6 @@ import {
   getNetworkId,
   getOnChainTokenDetails,
   getRoute,
-  isEvmToken,
   multiplyByPowerOfTen,
   Networks,
   RampCurrency,

apps/api/src/api/services/sep10/sep10.service.ts

@@ -34,7 +34,9 @@ export const signSep10Challenge = async (
     [FiatToken.EURC]: "EURC",
     [FiatToken.ARS]: "ARS",
     [FiatToken.BRL]: "BRL",
-    [FiatToken.USD]: "USDC" // USD maps to USDC for consistency, though not used for SEP10
+    [FiatToken.USD]: "USDC",
+    [FiatToken.MXN]: "USDC",
+    [FiatToken.COP]: "USDC"
   };
 
   const outToken = tokenMapping[fiatToken];

apps/frontend/.impeccable.md

@@ -0,0 +1,82 @@
+## Design Context
+
+### Users
+
+**Primary:** Crypto-native DeFi users who need to move money between fiat and crypto efficiently. They understand wallets, slippage, liquidity — but still expect fast, frictionless UX.
+
+**Integration partners:** Protocols like Pendle that embed Vortex as a ramping layer. Users arrive mid-flow from another product and need zero onboarding friction.
+
+**High-volume P2P operators:** Businesses like IaCrypto (Brazil) processing millions in daily volume. They care about reliability, speed, and trust signals — not aesthetics. Every failure costs real money.
+
+**Implication:** The interface must feel immediately legible to someone who has used Aave or Uniswap. No hand-holding, no consumer-app softness. Assume competence.
+
+---
+
+### Brand Personality
+
+**Three words:** Reliable. Modern. Calm.
+
+- **Reliable** — Every element should signal that this system works, is audited, and handles real money. No flashy UI that feels like a casino. When something goes wrong, error states are clear and non-panicking.
+- **Modern** — On par visually with Aave, not behind it. Clean, high-contrast, purposeful use of space. No legacy fintech feel.
+- **Calm** — Payments are stressful. The UI absorbs that stress. Generous whitespace, unhurried layouts, smooth transitions — not jarring or jumpy.
+
+**Voice:** Concise, direct, confident. No filler copy. Labels describe exactly what they mean. Errors explain what happened and what to do.
+
+---
+
+### Aesthetic Direction
+
+**Primary reference:** Aave — dark-capable, information-dense but not cluttered, strong typographic hierarchy, restrained use of color, data displayed with precision.
+
+**Theme:** Light mode only (current). White cards on near-white backgrounds, blue as the single action color, pink as a secondary signal only where needed.
+
+**Anti-references:**
+
+- Consumer fintech (Revolut, Cash App) — too playful, too colorful, wrong audience
+- Crypto degen UIs — cluttered, aggressive, no hierarchy
+- Legacy banking UIs — dated, corporate, low trust with DeFi users
+
+**Color discipline:** Blue for all primary actions. Pink accent used sparingly — not decoratively. Grays carry most of the layout weight. No rainbow, no gradients for decoration.
+
+**Motion:** Purposeful only. Appear/slide-up transitions on mount, scale feedback on press. No looping animations, no attention-grabbing movement.
+
+---
+
+### Design Principles
+
+1. **Precision over decoration** — Every pixel should communicate information or create breathing room. Remove anything that doesn't do one of those two things.
+2. **Trust is the product** — Visual consistency, clear number formatting, explicit fee disclosure, and legible error states are not polish — they are the core UX. High-volume users will abandon on the first sign of confusion.
+3. **Assume competence** — Skip tutorials and tooltips for basic crypto concepts. Show data at the right level of detail. Let advanced users read everything they need directly from the UI.
+4. **Calm under load** — Loading states, errors, and multi-step flows should feel controlled and unhurried. Use skeletons, not spinners. Use descriptive status labels, not raw error codes.
+5. **Aave-level finish** — The standard is: would this component look at home in the Aave interface? Consistent border radii, aligned grids, correct font weights, no stray margins. Ship nothing that falls below that bar.
+
+---
+
+### Design System
+
+**Stack:** Tailwind CSS v4 + DaisyUI v5 + Framer Motion (`motion/react`). All color tokens in OKLCH.
+
+**Color tokens** (defined in `apps/frontend/App.css` `:root`):
+- `--color-primary` / `--color-primary-hover` — brand blue, all primary actions
+- `--color-accent` — pink, secondary signal only (never decorative)
+- `--color-error/success/warning` + `-hover` variants — semantic state colors
+- `--color-primary-hover`, `--color-secondary-hover`, `--color-error-hover`, `--color-success-hover`, `--color-warning-hover` — darkened versions for button hover states (never invert on hover)
+
+**Button variants** (in `App.css`):
+- `.btn-vortex-primary` — blue, main CTA
+- `.btn-vortex-primary-inverse` — outlined blue
+- `.btn-vortex-secondary` — pink
+- `.btn-vortex-accent` — gray, tertiary
+- `.btn-vortex-success` / `.btn-vortex-danger` / `.btn-vortex-warning` — state variants
+- All hover states darken (use `-hover` tokens), never invert to light background
+
+**Spacing utilities:**
+- `.pb-footer-offset` — `calc(var(--quote-summary-height) + 1rem)` for content above absolute footer
+- `.bottom-above-quote` — positions elements above the QuoteSummary panel
+- `.touch-target` — expands hit area by 8px on all sides via `::after` pseudo-element without affecting layout; use on small interactive elements instead of inflating their visual size
+
+**Z-index scale** (named utilities, never arbitrary values):
+- `.z-footer` (5) → `.z-quote` (10) → `.z-overlay` (20) → `.z-modal` (50) → `.z-toast` (100)
+
+**Typography:** `"Red Hat Display"` only. Use `.text-widget-title`, `.text-section-title`, `.text-amount`, `.text-label`, `.text-caption` for widget UI — never raw Tailwind font sizes inside the widget.
+