AiFinPay Gemini Commerce Agent

AiFinPay Gemini Commerce Agent is a self-serve autonomous commerce agent built for the Build with Gemini XPRIZE. It combines Gemini reasoning with deterministic financial policy and AiFinPay payment rails so an agent can evaluate a paid digital resource, stay inside operator-defined limits, pay a supported HTTP 402/x402 endpoint, verify delivery, and leave an auditable record.

The core rule is simple: Gemini may propose a financial action, but it cannot authorize or sign it. Financial authority remains in deterministic code and the agent's own non-custodial wallet.

The problem

Human checkout assumes a person is present to open a page, review a cart, enter payment details, and approve each transaction. Autonomous agents need a different model: machine-readable offers, bounded budgets, deterministic authorization, non-custodial signing, receipts, and verifiable delivery. Merchants and digital-service providers also need a way to monetize agent traffic instead of either blocking it or giving it unrestricted access.

User flow

This project is now self-serve. The public Render service is the hackathon runtime and evidence surface; it is not a shared customer wallet.

A user installs the agent package.
init creates a new local encrypted wallet for that operator.
The operator can view public funding addresses with address.
The agent visits a known paid URL or receives one from a discovery workflow.
Gemini evaluates the objective or offer and proposes an action.
Deterministic policy checks price, merchant, network, asset, confidence, per-call cap, and daily budget.
If approved, AiFinPay executes AIFP-1 first; if the response is another supported HTTP 402/x402 format, the installed SDK can use its generic supported-facilitator path.
Receipt metadata and delivery evidence are recorded without exposing private keys or raw paid content.

A merchant does not need to register on the hackathon landing page for an agent to pay a known compatible x402 URL. Merchant catalog APIs are optional discovery sources, not a prerequisite for direct payment.

Quick start

Create a unique local agent and encrypted non-custodial wallet:

npx aifinpay-gemini-commerce-agent@0.3.0 init

Optional local limits:

npx aifinpay-gemini-commerce-agent@0.3.0 init --daily-budget 5 --per-call 0.10

Show public funding addresses:

npx aifinpay-gemini-commerce-agent@0.3.0 address

Pay a supported HTTP 402/x402 URL directly:

npx aifinpay-gemini-commerce-agent@0.3.0 fetch https://merchant.example/paid --max-usd 0.05

Run the full local Gemini commerce service:

export GEMINI_API_KEY=...
npx aifinpay-gemini-commerce-agent@0.3.0 start

The local wallet uses a fresh 32-byte seed encrypted at rest with AES-256-GCM and a scrypt-derived key. The seed is not sent to the public Render service.

Architecture

Operator / external agent
        |
        v
Objective or paid URL
        |
        v
Gemini reasoning
(proposes PAY / NEGOTIATE / ASK_USER / REJECT)
        |
        v
Deterministic policy engine
(budget + merchant + network + asset + confidence controls)
        |
        v
Local non-custodial agent wallet
        |
        +--> AiFinPay AIFP-1 HTTP 402 / receipt flow
        |
        +--> supported generic x402 facilitator path
        |
        v
Merchant / paid digital service
        |
        v
Receipt metadata + delivery hash + metrics / evidence

Reasoning and financial authority are deliberately separated. Gemini never receives the private key, agent seed, admin token, or Circle entity secret. Model output is re-validated against the original offer before any payment can proceed.

The current production/hackathon architecture, including the live Render topology, self-serve wallet flow, trust boundaries, integration status, and evidence rules, is documented in HACKATHON_ARCHITECTURE.md. The broader component and sequence design remains in ARCHITECTURE.md. Advanced negotiation, multimodal procurement, recovery semantics, and direct-URL payment behavior are documented in ADVANCED_COMMERCE.md.

What is new hackathon work

The project uses pre-existing AiFinPay payment infrastructure as a disclosed foundation. New work created for this hackathon includes:

Gemini structured decision workflow for autonomous commerce;
deterministic financial policy bridge;
multimodal procurement input;
bounded merchant negotiation;
self-healing payment/retry logic;
self-serve encrypted per-user wallet onboarding;
direct supported HTTP 402/x402 URL execution;
operational dashboard and metrics;
optional Firestore adapter and Google Cloud deployment/evidence architecture;
protected Circle Developer-Controlled Wallet integration path;
automated tests, CI, architecture, security, deployment, evidence, and disclosure documentation.

Pre-existing resources are explicitly disclosed: AiFinPay Agent SDK, MCP server, AIFP-1/AIFP-2/AIFP-3, payment contracts and settlement infrastructure, existing packages, website, audience, and relationships.

Current production status

Production web service: live on Render.
Gemini: live production structured-function-call smoke test verified.
AiFinPay executor: configured and active.
npm package: aifinpay-gemini-commerce-agent@0.3.0 published.
Automated validation: 24 tests pass; production build passes; dependency audit reported zero known vulnerabilities at release validation.
Self-serve wallet: clean consumer installation verified with persistent encrypted wallet creation and repeat address recovery.
Google Firestore: adapter and architecture exist, but the current public runtime does not claim Firestore as configured production evidence yet.
Circle wallet proof: integration path exists, but no funded Circle transaction is claimed yet.
Funded AIFP-1 settlement / third-party customer revenue: not claimed until verifiable external evidence exists.

This distinction is intentional: the project page does not convert code coverage or integrations into claims of real users, revenue, or settlement events.

Business model and category impact

The project targets Money & Financial Access by giving autonomous software controlled access to digital commerce. AiFinPay's AIFP-1 model charges a fixed 1% protocol fee per successful transaction, with 99% going to the merchant. The infrastructure can support publishers, APIs, MCP servers, data providers, model/inference services, and other digital merchants that want to monetize agent traffic programmatically.

Success is measured through Gemini decisions, deterministic approval/rejection rates, successful paid actions, gross payment volume, protocol revenue, merchant revenue, verified receipt/delivery rate, active and paying third-party users, latency, cost, and production evidence.