MCP 服务器

AiFinPay Wallet MCP Server

Enables ChatGPT to interact with multiple blockchain networks for reading balances and managing wallet operations through a non-custodial local vault and policy engine.

README

AiFinPay Wallet for ChatGPT

A non-custodial wallet interface and programmable approval layer for people and AI agents.

[!IMPORTANT] This public repository is a transparent hackathon/reference implementation. Balances are read-only across all 13 mainnet networks (Casper reads native CSPR from a key-gated node). Mainnet transaction signing and broadcasting are deliberately disabled until per-user authentication, durable storage and reviewed local signing are complete. Do not treat this beta as a bank, exchange, custodian or financial adviser.

Try it

The hosted instance uses a free preview environment and can cold-start after inactivity. Judges and reviewers can test the complete connection and read-only balance flow without rebuilding the project.

Product status

Capability	Status	Trust boundary
Local 12/15-word wallet creation and restore	Beta	Recovery phrase stays in the browser Vault
Local AES-256-GCM encrypted Vault	Beta	Password and ciphertext remain on the device
EVM, Solana, NEAR, Aptos and Casper address derivation	Beta	OAuth tokens contain public addresses only
One-time ChatGPT connection and automatic dashboard opening	Beta	OAuth 2.1 authorization code flow with PKCE
13-mainnet selector	Live	Every selected network returns read-only balances from public RPC (Casper via a key-gated node)
Public mainnet deployment registry	Declared, verification pending	13 contract/program identifiers; signing remains disabled
Native + USDC balances across all 13 mainnets	Live, read-only	Native token on all 13 (Casper CSPR via `query_balance` on a key-gated node); verified Circle USDC on 6 EVM chains (Polygon, Avalanche, Arbitrum, BNB, Base, Optimism)
Receive flow	Live	Displays public addresses only
Agent policy engine and audit trail	Reference implementation	Server-side deterministic rules
Mainnet transaction signing	Disabled	Requires personal auth and local user approval
Mainnet broadcasting	Disabled	No production transaction submission in this release

Why AiFinPay

AI agents can call APIs, purchase data and complete workflows, but an unrestricted wallet key is not an acceptable payment interface. AiFinPay separates four responsibilities:

GPT-5.6 interprets the user's natural-language intent and selects a narrow MCP tool.
Deterministic code validates amounts, addresses, limits and policy rules.
The user keeps recovery material and future signing authority in an encrypted local Vault.
The app returns concise structured results and a purpose-built interface inside ChatGPT.

The model can request an operation, but it cannot access recovery words or override the policy engine.

Architecture

flowchart TD
    U["User"] --> C["ChatGPT + GPT-5.6"]
    C --> M["AiFinPay MCP server"]
    M --> P["Policy and intent services"]
    M --> R["12-network public RPC (read-only)"]
    M --> A["OAuth 2.1 + PKCE"]
    M --> D[("Runtime intent and audit store")]
    C --> W["React wallet widget"]
    U --> V["Encrypted local Vault"]
    V -->|"one-time consent; public addresses only"| A
    V -. "future local signing" .-> W

The monorepo contains a TypeScript MCP server, a compact React widget, a separately loaded Vault application and shared policy/schema packages. The ChatGPT widget excludes the heavier wallet-derivation libraries so it remains responsive on mobile. See Architecture, Mainnet deployment registry and Public/private boundary.

Repository layout

apps/
  mcp-server/       MCP tools, public routes, adapters and storage
  wallet-widget/    ChatGPT widget and separately bundled local Vault
packages/
  shared/           Schemas, types, amounts and network metadata
  aifinpay-adapter/ Policy engine and wallet adapter contract
  demo-ledger/      Deterministic test-only adapter
docs/               Architecture, security, deployment and submission docs
.github/             CI, dependency updates and contribution templates

Local development

Requirements: Node.js 22+ (Node 24 recommended) and npm 11+.

npm ci
cp .env.example .env
npm run check
npm start

Local routes:

Route	Purpose
`http://localhost:8787/mcp`	MCP endpoint
`http://localhost:8787/health`	Health and active adapter
`http://localhost:8787/preview`	Browser widget preview
`http://localhost:8787/vault`	Local non-custodial Vault
`http://localhost:8787/privacy`	Privacy notice
`http://localhost:8787/terms`	Beta terms

Inspect the MCP server:

npx @modelcontextprotocol/inspector@latest --server-url http://localhost:8787/mcp --transport http

Connect from ChatGPT

Enable Developer Mode in ChatGPT.
Add https://aifinpay-wallet-chatgpt.onrender.com/mcp as the MCP server.
Ask: Open my AiFinPay wallet.
On first use only, choose Connect, create or restore the local Vault, and approve sharing its public addresses.
Future Open my AiFinPay wallet requests go directly to the dashboard until the app is disconnected in ChatGPT.

Never paste a recovery phrase, private key, Vault password or API credential into ChatGPT, an issue, a screenshot or a tool input. Full instructions: ChatGPT setup.

Configuration

The checked-in .env.example contains placeholders only. Read-only mainnet mode (all 13 networks) is the default; demo mode must be selected explicitly. Each network falls back to public RPC defaults and can be overridden with a <NETWORK>_RPC_URLS variable. Casper mainnet nodes are API-key gated: set CASPER_RPC_URLS and CASPER_RPC_AUTH (the provider key sent as the Authorization header) to enable CSPR balance reads.

AIFINPAY_WALLET_MODE=mainnet
POLYGON_RPC_URLS=https://polygon.drpc.org,https://polygon.publicnode.com
AIFINPAY_DEMO_MODE=false
DATABASE_URL=./data/aifinpay-local.sqlite
SESSION_SECRET=replace-with-at-least-32-random-characters

AIFINPAY_DEMO_MODE=false is mandatory for any shared deployment. The blockchain adapter is selected separately with AIFINPAY_WALLET_MODE.

Security and privacy

Recovery words are generated or entered only in the Vault page and are encrypted locally.
User-specific tools require OAuth 2.1 with PKCE and separate read/write scopes; access and refresh tokens carry validated public addresses only.
The MCP tool surface does not accept seed phrases, private keys, passwords or API keys.
Mainnet reads use each network's official chain parameters and, where available, its verified Circle USDC contract (native token elsewhere).
Financial values use integer base units rather than floating point.
CSP domains are explicit and the ChatGPT widget makes no direct network requests.
CI scans for accidentally committed keys, databases, archives and production configuration.

Read Security policy, Security model, Threat model, Privacy and Terms.

Public and private repositories

This repository remains public and contains the reviewable app, reference policy engine, UI, tests and documentation. It must never contain production credentials, customer data, treasury configuration, proprietary risk rules, production infrastructure state or signing material.

The future private repository will own production authentication, managed databases, signing orchestration, internal monitoring, deployment secrets, customer integrations and confidential operating procedures. Interfaces may be shared between repositories; confidential implementations and data may not. See Public/private boundary.

OpenAI Build Week submission

This repository targets the Apps for Your Life track as a personal-finance ChatGPT app.

Devpost requires a working project, English submission materials, a public or reviewer-shared repository with relevant licensing, clear setup/testing instructions, a public YouTube demo of three minutes or less with voiceover, specific Codex/GPT-5.6 usage, and the primary /feedback Codex Session ID. The repository contains a compliance checklist, submission draft, demo script and dated build log.

How Codex accelerated the build

Codex was used as an engineering collaborator throughout the primary build thread to:

audit the initial empty repository and create the monorepo contract;
research current Apps SDK and MCP requirements;
implement and test the MCP server, React widget and local Vault;
diagnose mobile bundle size and split the Vault from the inline widget;
replace fabricated demo balances with read-only mainnet RPC data across all 13 networks;
model security boundaries, run regression checks and prepare deployment;
reconcile README, legal, security and submission documentation with actual behavior.

Key human product decisions included choosing non-custodial local recovery, prohibiting mainnet signing until personal authentication exists, using Polygon as the first live network before extending read-only balances to all 13 mainnets, and keeping confidential production systems outside the public repository.

GPT-5.6 is the conversational orchestration layer: it interprets wallet requests, selects the appropriate MCP tool and explains deterministic results. It is not the source of truth for policy, balances or transaction authorization.

[!NOTE] The Devpost form still requires the repository owner to add the public YouTube URL and the /feedback Codex Session ID. These values are intentionally not invented or exposed here.

Quality gates

npm run lint
npm run typecheck
npm test
npm run build
npm run security:public
npm audit --audit-level=high --omit=dev

Community and governance

Legal

The source code is available under the MIT License. Third-party packages remain governed by their respective licenses; see Third-party licenses.

The software license is not a banking, money-transmission, virtual-asset, custody or securities license. No regulatory authorization is claimed by this repository. See Compliance posture.

AiFinPay is an independent project and is not affiliated with or endorsed by OpenAI, Polygon Labs, Circle, Stripe, PayPal or Visa. Third-party names are used only to identify interoperable platforms and technologies.