Add alfredpay support

.gitignore

@@ -42,6 +42,8 @@ storybook-static
 
 CLAUDE.local.md
 .claude
-/contracts/relayer/artifacts/*
-/contracts/relayer/cache/*
 /.roo/*
+
+# hardhat generated files in workspace contract projects
+contracts/*/artifacts
+contracts/*/cache

.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

README.md

@@ -13,13 +13,16 @@ Vortex is a gateway for cross-border payments. It is built on top of the Pendulu
 
 ## Repository Structure
 
-This is a **Bun monorepo** containing multiple sub-projects organized into apps and packages:
+This is a **Bun monorepo** containing multiple sub-projects organized into apps, packages, and contracts:
 
 ### Apps
 
 - **[apps/api](apps/api)** - Backend API service providing signature services, on/off-ramping flows, quote generation, and transaction state management
 - **[apps/frontend](apps/frontend)** - React-based web application built with Vite for the Vortex user interface
 - **[apps/rebalancer](apps/rebalancer)** - Service for automated liquidity rebalancing across chains
+### Contracts
+
+- **[contracts/relayer](contracts/relayer)** - Hardhat project for relayer smart contracts and deployment scripts
 
 ### Packages
 
@@ -69,6 +72,11 @@ bun dev:backend
 bun dev:rebalancer
 ```
 
+**Relayer contract local node:**
+```bash
+bun dev:contracts:relayer
+```
+
 ### Building
 
 **Build all projects:**
@@ -91,6 +99,15 @@ bun build:sdk
 bun build:shared
 ```
 
+**Relayer contract:**
+```bash
+# Compile contracts
+bun compile:contracts:relayer
+
+# Run contract tests
+bun test:contracts:relayer
+```
+
 ## Sub-Project Specific Instructions
 
 ### Frontend (apps/frontend)

apps/api/.env.example

@@ -64,3 +64,8 @@ DELTA_D_BASIS_POINTS=0.3
 # RSA Keys for Webhook Signing
 # Only the private key is needed - public key is derived from it
 WEBHOOK_PRIVATE_KEY=your-webhook-private-key
+
+# AlfredPay
+ALFREDPAY_BASE_URL=your-alfredpay-base-url
+ALFREDPAY_API_KEY=your-alfredpay-api-key
+ALFREDPAY_API_SECRET=your-alfredpay-api-secret