Most financial APIs expose endpoints. Autonomous software needs a safer abstraction: explicit intent, policy evaluation, normalized execution, durable state, and receipts it can reason about.

Neobank Primitives is building that layer for two consumers:

• Fintech applications that want reusable identity, account, balance, and transaction building blocks.
• AI agents that need narrowly scoped financial tools, machine-readable outcomes, and human approval when policy requires it.

The repository is useful now as a fully interactive neobank starter with realistic demo data and a Swipelux sandbox integration. The MCP server, standalone SDK, policy engine, and full KYB surface described below are the direction of the project and are not yet shipped as a production runtime.

The contract is designed to stay provider-neutral. Swipelux is the first adapter, not the shape every integration must inherit.

Demo mode runs without credentials and remains interactive across personal and business accounts, onboarding, deposits, payouts, and wallet transfers. Turn on How it works to see the financial steps behind each product action.

Business accounts · fiat and stablecoin balances	Identity · KYC and account provisioning	Deposit rails · SEPA and USDC
Transaction execution · quote, compliance context, conversion, and payout

Agents should not receive an unrestricted payment endpoint. They should receive constrained tools backed by the same typed SDK used by the application, with policy checks between intent and execution.

flowchart LR
    A[Autonomous agent] --> M[MCP tools]
    F[Fintech application] --> S[TypeScript SDK]
    M --> P[Policy engine]
    P --> S
    S --> N[Normalized primitives]
    N --> W[Swipelux adapter]
    N --> X[Additional adapters]
    W --> I[Financial infrastructure]
    X --> I
    P --> H[Human approval for exceptions]
    I --> O[States, receipts, audit history]
    O --> A
    O --> F

Every operation follows the same lifecycle:

validate intent → evaluate policy → authorize → execute → normalize → audit

The target contract treats idempotency, limits, destination rules, approvals, status, and receipts as first-class concerns—not application-specific afterthoughts.

Target interface — illustrative, not yet part of the published runtime.

{
  "name": "transactions.quote",
  "arguments": {
    "sourceAccountId": "acct_operating_eur",
    "destination": { "type": "bank_recipient", "id": "rcpt_maria" },
    "amount": { "value": "250.00", "currency": "EUR" },
    "purpose": "invoice_payment",
    "idempotencyKey": "inv_2041_quote"
  }
}

The tool response should give the agent enough information to make the next bounded decision:

{
  "status": "approval_required",
  "quoteId": "quote_01",
  "recipientGets": { "value": "247.75", "currency": "EUR" },
  "fee": { "value": "2.25", "currency": "EUR" },
  "policy": {
    "decision": "review",
    "reason": "new_destination"
  },
  "expiresAt": "2026-07-13T18:30:00Z"
}

The intended safety model is simple:

1. An application or agent submits a structured financial intent.
2. Policy validates identity state, permissions, limits, destination rules, purpose, and idempotency.
3. Allowed operations execute automatically; exceptions pause for an authorized human.
4. The adapter returns normalized status, provider references, receipts, and audit events.

This makes autonomy configurable instead of binary. A treasury agent might rebalance approved wallets automatically while a first-time bank recipient always requires review.

git clone https://github.com/andry-lebedev/neobank-primitives.git
cd neobank-primitives
npm install
npm run dev

No .env file is required for demo mode. Open the local URL, switch between personal and business personas, onboard a customer, add funds, request a payout quote, and inspect the execution story.

Click Go live in the app and provide a Swipelux sandbox API key. The key is held in the browser session and the same screens switch from realistic local data to the live adapter.

The existing integration lives under src/data/live, behind the same DataSource contract used by the demo implementation. Provider documentation: Swipelux API reference · Swipelux docs

This is an early build. Do not use demo addresses for real funds, and do not treat the current UI as a production compliance or custody system. Production users remain responsible for provider onboarding, credentials, jurisdictional requirements, policy configuration, and operational controls.

The UI is intentionally easy to fork. Give the following prompt to a coding agent after cloning:

Read AGENTS.md and PROMPT.md, then adapt this neobank starter to my product.
Ask for my company name, audience, and brand direction. Work on a new branch,
keep financial flows and tests intact, edit the documented brand surfaces first,
run the quality checks, and show me the finished local app.

Brand-only changes are concentrated in src/theme.css and src/brand.config.ts. Feature extensions should preserve the domain boundary so future SDK and MCP surfaces can share the same primitives.

npm test
npm run lint
npm run typecheck
npm run build

The most valuable contributions strengthen the primitive boundary: normalized transaction states, adapter contracts, policy decisions, approvals, receipts, KYB requirements, and deterministic demo scenarios. Open an issue before making a large architectural change so the application, SDK, and MCP direction stay aligned.