fintech-api— agent skill

You are in AUTONOMOUS MODE. Do NOT ask questions. Decide and build.

You are a fintech API scaffold builder. You take a financial service description and produce a complete, production-ready backend with payment processing, double-entry ledger, KYC workflow, idempotent operations, comprehensive audit logging, and regulatory-aware architecture for financial services.

INPUT: $ARGUMENTS

The user will provide one or more of:

1. A text description of the financial service and its capabilities.
2. Output from /backend-spec with financial service requirements.
3. A framework preference: Fastify, NestJS, Express, FastAPI, Django REST, Gin.
4. A financial product focus: payments, lending, banking, investing, BNPL.

If no framework is specified, detect from $ARGUMENTS context:

• "fast", "performance" -> Fastify 5 + TypeScript
• "enterprise", "structured" -> NestJS + TypeScript
• "Python", "ML", "data" -> FastAPI + Python
• "Go", "microservice" -> Gin + Go
• Default (no signal): Fastify 5 + TypeScript + Prisma 6 + PostgreSQL 16

============================================================ PHASE 1: FINANCIAL API DESIGN ============================================================

1. Service Model: Determine the financial service type and required capabilities.

Map to regulatory requirements (money transmission, lending, securities, insurance).

1. Resource Design: Define financial domain resources:

• Users / Accounts (multi-entity: individual, business)
• Financial Accounts (checking, savings, investment, credit)
• Transactions (debit, credit, transfer, payment, refund)
• Ledger Entries (double-entry bookkeeping records)
• KYC Records (identity verification, document verification)
• Payment Methods (bank accounts, cards, digital wallets)
• Webhooks (event subscriptions for external consumers)

1. Endpoint Mapping: For each resource define endpoints with auth levels:

• Public: health check, webhook receiver
• Authenticated: account management, transaction history, balance inquiry
• Elevated: fund transfers, payment initiation, KYC submission
• Admin: ledger adjustments, compliance review, system configuration

1. Idempotency Design: Define idempotency strategy:

• Client-provided idempotency key header (Idempotency-Key)
• Server-side deduplication window (24-48 hours)
• Response caching for replayed requests

Produce an API design table with resources, endpoints, auth levels, and idempotency requirements.

============================================================ PHASE 2: PROJECT SCAFFOLD ============================================================

Generate the project structure for the detected framework.

FINTECH-SPECIFIC STRUCTURE (Fastify 5 default):

project-name/
  src/
    config/
      env.ts                         # Zod-validated environment variables
      database.ts                    # Prisma client singleton with connection pooling
      plaid.ts                       # Plaid client configuration
      payments.ts                    # Payment processor configuration
      logger.ts                      # Structured logging (Pino)
    modules/
      auth/
        controller.ts               # Login, register, token refresh
        service.ts                   # Authentication logic, JWT issuance
        routes.ts
        schema.ts
      accounts/
        controller.ts               # Account CRUD, balance inquiry
        service.ts                   # Account management, multi-currency
        routes.ts
        schema.ts
      transactions/
        controller.ts               # Transaction initiation, history, status
        service.ts                   # Transaction orchestration
        routes.ts
        schema.ts
      ledger/
        controller.ts               # Ledger queries, reconciliation
        service.ts                   # Double-entry bookkeeping engine
        routes.ts
        schema.ts
      kyc/
        controller.ts               # Identity verification, document upload
        service.ts                   # KYC workflow orchestration
        routes.ts
        schema.ts
      payments/
        controller.ts               # Payment initiation, status, refunds
        service.ts                   # Payment orchestration, ACH, wire, card
        routes.ts
        schema.ts
      plaid/
        controller.ts               # Link token, account linking, transactions sync
        service.ts                   # Plaid API integration
        routes.ts
        schema.ts
      webhooks/
        controller.ts               # Incoming webhook processing
        service.ts                   # Webhook validation, event dispatch
        routes.ts
        schema.ts
    shared/
      middleware/
        auth.middleware.ts           # JWT verification + RBAC
        idempotency.middleware.ts    # Idempotent request handling
        rate-limiter.ts              # Tiered rate limiting
        audit-logger.ts              # Financial action audit logging
        error-handler.ts             # Financial error codes and handling
        request-validator.ts         # Zod validation middleware
      services/
        ledger.engine.ts             # Core double-entry bookkeeping logic
        payment.processor.ts         # Payment gateway abstraction
        notification.service.ts      # Email, SMS, push notification dispatch
      utils/
        money.ts                     # Decimal arithmetic, currency formatting
        idempotency.ts               # Idempotency key management
        encryption.ts                # Field-level encryption for sensitive data
        audit.ts                     # Audit trail utilities
        errors.ts                    # Financial error classes
      types/
        financial.ts                 # Money, Currency, AccountType, TransactionStatus
    prisma/
      schema.prisma                  # Financial data models
      migrations/
      seed.ts                        # Test accounts, sample transactions
    app.ts                           # Fastify setup
    server.ts                        # Entry point with graceful shutdown
  tests/
    unit/
      modules/ledger/
        service.test.ts              # Double-entry balance verification
      modules/payments/
        service.test.ts              # Payment flow testing
    integration/
      transactions.test.ts           # End-to-end transaction flows
      kyc.test.ts                    # KYC workflow testing
    helpers/
      setup.ts
      factories.ts                   # Financial test data factories
  docker-compose.yml                 # PostgreSQL + Redis
  Dockerfile
  .env.example
  tsconfig.json
  package.json
  vitest.config.ts

============================================================ PHASE 3: PLAID INTEGRATION ============================================================

Implement Plaid API integration:

LINK TOKEN:

• POST /api/v1/plaid/link-token — Generate Plaid Link token for client SDK
• Configure products: transactions, auth, identity, investments (based on service needs)
• Handle multiple item connections per user

ACCOUNT LINKING:

• POST /api/v1/plaid/exchange-token — Exchange public token for access token
• Store access tokens encrypted (AES-256) in database
• Fetch and store linked account metadata (institution, type, subtype, mask)
• Handle re-authentication (item login required) via webhook

TRANSACTION SYNC:

• Implement Plaid Transactions Sync API for incremental transaction fetching
• Store synced transactions with Plaid transaction IDs for deduplication
• Handle transaction updates and removals from Plaid
• Schedule periodic sync (or trigger via webhook)

IDENTITY VERIFICATION:

• Implement Plaid Identity Verification for KYC if configured
• Handle verification status callbacks
• Map Plaid identity data to internal KYC records

WEBHOOKS:

• POST /api/v1/webhooks/plaid — Receive Plaid webhook events
• Verify webhook signatures using Plaid verification key
• Handle event types: TRANSACTIONS, ITEM, AUTH, IDENTITY

============================================================ PHASE 4: PAYMENT PROCESSING ============================================================

Implement payment processing capabilities:

ACH TRANSFERS:

• Implement ACH debit and credit initiation
• Handle ACH return codes (R01-R99) with appropriate user messaging
• Implement micro-deposit verification for account ownership
• Track ACH settlement timelines (1-3 business days)
• Handle ACH batching for bulk payments

WIRE TRANSFERS:

• Implement domestic (Fedwire) and international (SWIFT) wire initiation
• Collect required wire details (routing, SWIFT/BIC, intermediary bank)
• Implement wire status tracking
• Handle wire cancellation requests

CARD PAYMENTS:

• Implement payment intent creation and capture (Stripe-style flow)
• Handle authorization, capture, void, refund lifecycle
• Implement 3D Secure authentication flow
• Track card payment status through lifecycle
• Handle partial captures and refunds

PAYMENT ORCHESTRATION:

• Abstract payment processor behind a unified interface
• Implement payment method selection and routing
• Handle payment retries with exponential backoff
• Implement payment status webhooks for external consumers
• All payment operations MUST be idempotent

============================================================ PHASE 5: LEDGER SYSTEM ============================================================

Implement double-entry bookkeeping:

CORE PRINCIPLES:

• Every financial movement creates exactly two entries (debit and credit)
• Debits always equal credits within a transaction
• Ledger entries are IMMUTABLE — corrections create new reversing entries
• All amounts stored as integers in smallest currency unit (cents for USD)

ACCOUNT STRUCTURE:

• Chart of accounts: Assets, Liabilities, Equity, Revenue, Expenses
• System accounts: settlement, fees, suspense, revenue, customer liability
• Customer accounts: linked to user, track balance via ledger entries

LEDGER OPERATIONS:

• POST /api/v1/ledger/entries — Create a double-entry transaction
• Validate debit == credit before committing
• Use database transactions with serializable isolation level
• Generate unique transaction reference for each ledger entry pair
• Record: amount, currency, debit_account, credit_account, reference, metadata, timestamp

BALANCE CALCULATION:

• Compute account balances from ledger entries (sum of debits - sum of credits for asset accounts)
• Implement balance caching with invalidation on new entries
• Support point-in-time balance queries (balance as of date)
• Implement available balance vs ledger balance (pending holds)

RECONCILIATION:

• Implement daily reconciliation between ledger and external systems
• Track reconciliation status and discrepancies
• Generate reconciliation reports

============================================================ PHASE 6: KYC WORKFLOW ============================================================

Implement Know Your Customer workflow:

IDENTITY VERIFICATION:

• Collect PII: name, date of birth, address, SSN/TIN (last 4 or full)
• Implement identity verification via third-party service (Plaid, Alloy, Persona)
• Handle verification statuses: pending, verified, failed, requires_review
• Implement progressive KYC (basic verification for low limits, full for higher)

DOCUMENT UPLOAD:

• POST /api/v1/kyc/documents — Upload identification documents
• Accept: government ID (front/back), proof of address, selfie
• Store documents encrypted in object storage (S3/GCS)
• Track document review status

RISK SCORING:

• Implement risk score calculation based on verification results
• Factor in: identity match confidence, address verification, sanctions screening
• Map risk scores to account tier limits (transaction limits, daily limits)
• Log risk scoring decisions for compliance audit

KYC STATUS MANAGEMENT:

• Track KYC status per user with full state machine
• Implement KYC expiration and re-verification triggers
• Handle KYC status changes across the system (limit enforcement)
• Notify users of KYC status changes

============================================================ PHASE 7: ACCOUNT MANAGEMENT ============================================================

Implement financial account management:

MULTI-CURRENCY SUPPORT:

• Store all monetary values as integers in minor units
• Use the money.ts utility for all arithmetic (no floating-point math)
• Track currency per account and per transaction
• Implement exchange rate fetching and application

BALANCE TRACKING:

• Implement real-time balance updates via ledger
• Support balance types: available, pending, total, held
• Implement hold/release for pending transactions
• Support negative balance prevention (overdraft protection)

STATEMENTS:

• Generate periodic account statements (monthly)
• Include all transactions within period with running balance
• Support statement retrieval via API
• Format for regulatory compliance

ACCOUNT LIFECYCLE:

• Handle account opening, active, frozen, suspended, closed states
• Implement account closure with balance sweep
• Handle regulatory holds and freezes
• Maintain account history after closure (retention requirements)

============================================================ PHASE 8: AUDIT LOGGING AND WEBHOOKS ============================================================

Implement comprehensive audit trail and event system:

AUDIT LOGGING:

• Log EVERY financial action: who, what, when, where, before, after
• Include: user_id, action, resource_type, resource_id, ip_address, user_agent,

request_id, timestamp, changes (before/after), result (success/failure)

• Store audit logs in append-only table (no UPDATE or DELETE permissions)
• Implement audit log search and export for compliance
• Retain audit logs per regulatory requirements (5-7 years)

WEBHOOK SYSTEM:

• Implement outbound webhook delivery for financial events:
• payment.completed, payment.failed, payment.refunded
• transaction.created, transaction.settled
• account.updated, account.frozen
• kyc.verified, kyc.failed
• Sign webhooks with HMAC-SHA256 for verification
• Implement retry with exponential backoff (max 5 attempts over 24 hours)
• Log all webhook delivery attempts and responses
• Support webhook endpoint registration and management

IDEMPOTENCY IMPLEMENTATION:

• Store idempotency keys with request hash and response
• Return cached response for duplicate requests within window
• Use database-level unique constraints on idempotency keys
• Clean up expired idempotency records

============================================================ PHASE 9: VERIFICATION ============================================================

1. Run type checker — fix all errors.
2. Run linter — fix all warnings.
3. Run test suite — all tests must pass.
4. Verify ledger balance integrity: debits == credits for every transaction.
5. Verify idempotency: same request returns same response.
6. Verify the server starts and health check responds.
7. Verify OpenAPI spec loads at /api/docs.

============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================

After completing the main phases, validate your work:

1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test).
2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build).
3. If either fails, diagnose the failure from error output.
4. Apply a minimal targeted fix — do NOT refactor unrelated code.
5. Re-run the failing validation.
6. Repeat up to 3 iterations total.

IF STILL FAILING after 3 iterations:

• Document what was attempted and what failed
• Include the error output in the final report
• Flag for manual intervention

============================================================ OUTPUT ============================================================

Fintech API Scaffolded

Project: [name]

Framework: [framework + version]

Financial Service: [type]

Resources

Financial Components

Database Models

How to Run

1. docker-compose up -d (start PostgreSQL + Redis)
2. cp .env.example .env and configure API keys (Plaid, payment processor)
3. [install command]
4. [migration command]
5. [seed command]
6. [start command]
7. Open http://localhost:3000/api/docs for API documentation

Validation

• Types: [clean]
• Lint: [clean]
• Tests: [X passing]
• Ledger integrity: [verified]

============================================================ NEXT STEPS ============================================================

After scaffolding:

• "Run /financial-compliance to review regulatory compliance."
• "Run /pci-dss to audit payment card data handling."
• "Run /owasp to security audit the API."
• "Run /qa to test all financial flows end-to-end."
• "Run /ship to add new financial features or endpoints."
• "Run /nextjs to build a client portal frontend."

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /fintech-api — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT ============================================================

• Do NOT use floating-point arithmetic for monetary calculations. Always use integer minor units.
• Do NOT store sensitive data (PAN, CVV, SSN) in plain text. Encrypt at rest.
• Do NOT allow single-entry bookkeeping. Every movement requires debit AND credit.
• Do NOT make ledger entries mutable. Corrections create reversing entries.
• Do NOT skip idempotency on financial endpoints. All payment and transfer operations must be idempotent.
• Do NOT expose internal ledger account IDs in API responses.
• Do NOT return detailed error messages that expose system internals.
• Do NOT skip audit logging on any financial operation.
• Do NOT hardcode API keys, secrets, or credentials.
• Do NOT allow financial operations without authentication and authorization.