aifinpay-gemini-commerce-agent

v0.3.0

Published

14 days ago

Gemini-powered self-serve commerce agent with local encrypted wallets, multimodal procurement, negotiation, self-healing, and AIFP-1/x402 payments.

AiFinPay Gemini Commerce Agent

AiFinPay Gemini Commerce Agent is a policy-controlled commerce operator for autonomous software. It evaluates paid digital services with Gemini, independently enforces budgets and allowlists, executes AIFP-1 HTTP 402 payments, verifies delivery, and records auditable evidence.

Built for the Build with Gemini XPRIZE on top of disclosed, pre-existing AiFinPay payment infrastructure.

Production: https://aifinpay-gemini-commerce-agent.onrender.com

[!NOTE] The public Render deployment and a real Gemini 3.6 Flash structured-function-call smoke test are verified. A funded AIFP-1 settlement, Circle transaction, third-party usage, and hackathon-period customer revenue are not claimed until verifiable records exist.

v0.2 — autonomous procurement beyond text

The v0.2 capability layer turns the agent from a linear JSON buyer into a bounded procurement operator:

Multimodal procurement — submit a server-part photo, product image, invoice, chart, or analytics screenshot. Gemini extracts procurement-relevant facts and produces a merchant-search query; raw image bytes are not persisted.
Dynamic negotiation — when a merchant exposes a negotiation endpoint and policy explicitly permits it, Gemini may propose a counter-offer. Deterministic rules cap the discount, enforce the budget and allowlists, and re-validate the agreed offer before payment.
Self-healing payments — transient gas/RPC/network failures are classified and retried within a fixed attempt budget. Alternative network/asset paths are used only when supplied in the offer and independently permitted by allowedNetworks, allowedAssets, and recovery policy.

See ADVANCED_COMMERCE.md for request contracts, trust boundaries, negotiation rules, recovery semantics, and evidence limitations.

Why this exists

Human checkout flows do not work for autonomous agents. An agent needs to understand an offer, choose whether it is useful, stay inside an operator-defined budget, pay without receiving signing keys, verify delivery, and leave an audit trail.

This service separates reasoning from financial authority:

| Layer | Responsibility | Financial authority | |---|---|---| | Gemini | Evaluate offers and propose one structured action | None | | Policy engine | Verify price, merchant, asset, network, tier, confidence, and budget | Approve or block | | AiFinPay executor | Perform the exact approved AIFP-1 HTTP 402 flow | Exact approved payment only | | Circle service | Create an explicitly confirmed, capped USDC proof transfer | Admin-only isolated path | | Store and logging | Persist state and non-secret evidence | None |

System at a glance

flowchart TD
  Client["User or agent"] --> API["Objective API on Render"]
  API --> Gemini["Gemini decision engine"]
  Gemini --> Policy["Deterministic policy engine"]
  Policy -->|"blocked or approval needed"| Stop["Reject / await human"]
  Policy -->|"approved"| Pay["AiFinPay AIFP-1 executor"]
  Pay --> Merchant["HTTP 402 merchant service"]
  Merchant --> Evidence["Receipt + delivery evidence"]
  Evidence --> Store["Metrics / logs / optional Firestore"]

Full component, sequence, deployment, trust-boundary, state, and data diagrams are in ARCHITECTURE.md.

Core guarantees

Gemini never receives a private key, agent seed, Circle entity secret, or admin token.
Every model proposal is checked against the original offer; Gemini cannot rewrite the price or payment destination.
Merchant, network, asset, action tier, total budget, auto-approval limit, and confidence are enforced in deterministic TypeScript.
Firestore can transactionally claim an objective when enabled, preventing the same objective from executing twice across instances.
Receipt bearer tokens and delivered content are not persisted; the service stores hashes and settlement evidence.
Production refuses to start with financial credentials unless a 24+ character admin token is configured.
Circle transfers require admin authentication, confirm: true, and a hard maximum amount.

Payment lifecycle

sequenceDiagram
  autonumber
  participant C as Client
  participant A as Commerce API
  participant G as Gemini
  participant P as Policy + AiFinPay
  participant M as Merchant
  C->>A: Objective + policy + offers
  A->>G: Untrusted offers as data
  G-->>A: Structured purchase proposal
  A->>P: Exact proposal + original policy
  alt policy approved
    P->>M: Request paid resource
    M-->>P: HTTP 402 quote
    P->>M: Settlement proof + retry
    M-->>P: Paid response
    P-->>A: Receipt metadata + delivery hash
  else blocked
    P-->>A: Deterministic rejection code
  end
  A-->>C: Auditable result

Technology

| Area | Implementation | |---|---| | AI decision engine | Google Gemini 3.6 Flash via @google/genai and forced function calling | | API | Node.js 22+, TypeScript, Fastify, Zod | | Agent payments | @aifinpay/agent, AIFP-1, HTTP 402 | | Optional prize proof | Circle Developer-Controlled Wallets | | Persistence | In-memory production demo store; Google Cloud Firestore adapter available | | Runtime | Render production web service | | Evidence | Structured Render logs, metrics dashboard, optional Firestore | | Delivery | GitHub Actions + Render |

Install and create your own agent

The hosted Render service is the hackathon runtime, not a shared user wallet. Every operator should create a separate local non-custodial agent.

1. Create a unique encrypted local wallet

npx [email protected] init

The command generates a fresh 32-byte seed locally, derives the agent's EVM, Solana and Casper identities, encrypts the seed with AES-256-GCM using a scrypt-derived key, and stores only the encrypted keystore under ~/.aifinpay/ with restrictive filesystem permissions. The seed is not sent to the AiFinPay Render service.

Optional local limits:

npx [email protected] init --daily-budget 5 --per-call 0.10

2. Show your public funding addresses

npx [email protected] address

This decrypts the local keystore after passphrase entry and prints public addresses only.

3. Pay a supported HTTP 402 / x402 URL directly

npx [email protected] fetch https://merchant.example/paid --max-usd 0.05

The direct URL flow does not require the merchant to register on this landing page. The client gives AIFP-1 first refusal so AiFinPay receipt batching/reuse remains available; if the response is still HTTP 402, the installed AiFinPay SDK auto-detects another supported x402 facilitator and refuses a quote above the local --max-usd / per-call policy before authorizing payment. Support is limited to facilitator formats recognized by the installed SDK; this is not a claim that every proprietary 402 variant on the internet is automatically compatible.

MERCHANT_API_ENDPOINTS remains optional. It is for procurement discovery/catalog search, not a prerequisite for paying a known x402 URL.

4. Run the full local Gemini commerce service

export GEMINI_API_KEY=...
npx [email protected] start

The package also exports the Fastify application builder for embedding:

import { buildApp } from "aifinpay-gemini-commerce-agent";

const app = buildApp();
await app.listen({ port: 8080 });

For non-interactive local automation, the keystore passphrase can be supplied through AIFINPAY_KEYSTORE_PASSPHRASE; do not commit it or place it in public logs.

Repository map

src/
├── app.ts                    HTTP boundary, authentication and security headers
├── config.ts                 validated environment configuration
├── domain.ts                 schemas and domain records
├── dashboard.ts              operational evidence dashboard
└── services/
    ├── gemini.ts             structured Gemini decision engine
    ├── vision.ts             Gemini multimodal procurement inspection
    ├── merchant-discovery.ts configured merchant catalog search
    ├── negotiation.ts        bounded counter-offer exchange
    ├── recovery.ts           deterministic retry and network/asset failover
    ├── policy.ts             deterministic financial policy
    ├── orchestrator.ts       objective state machine
    ├── aifinpay.ts           AIFP-1 payment execution
    ├── circle.ts             isolated USDC proof transfer
    └── store.ts              memory and Firestore adapters
tests/                        policy, security and API tests
.github/                      CI and deployment workflows

Run from source

Prerequisites

Node.js 22+
npm 10+
Gemini API access for live model calls
funded AiFinPay settlement wallet for live payments
optional Google Cloud Firestore and Circle Developer-Controlled Wallet credentials

git clone https://github.com/coinsecuritiescompany/AiFinPay-Gemini-Commerce-Agent.git
cd AiFinPay-Gemini-Commerce-Agent
cp .env.example .env
npm ci
npm run dev

The service can start without financial credentials for local inspection. Open http://localhost:8080 for the evidence dashboard.

Validate

npm run check
npm run build
npm audit
npm pack --dry-run

The current suite contains 24 tests covering policy enforcement, configuration safety, protected financial routes, revenue accounting, and the successful objective flow.

Minimal objective example

curl -sS http://localhost:8080/v1/objectives \
  -H 'content-type: application/json' \
  -H "x-admin-token: $ADMIN_TOKEN" \
  -d '{
    "goal": "Buy one complex research API result",
    "requesterId": "external-user-001",
    "policy": {
      "maxBudgetUsd": 0.01,
      "autoApproveLimitUsd": 0.005,
      "minConfidence": 0.6,
      "allowedMerchants": ["merchant-id-from-aifp1"],
      "allowedNetworks": ["polygon"],
      "allowedAssets": ["USDC"]
    },
    "offers": [{
      "merchantId": "merchant-id-from-aifp1",
      "offerId": "research-complex-001",
      "title": "Research API",
      "description": "One complex research request",
      "url": "https://gateway.aifinpay.io/merchant-slug/research",
      "priceUsd": 0.002,
      "network": "polygon",
      "asset": "USDC",
      "actionTier": "COMPLEX",
      "paymentRail": "AIFP1"
    }]
  }'

Run the returned objective ID:

curl -sS -X POST http://localhost:8080/v1/objectives/OBJECTIVE_ID/run \
  -H "x-admin-token: $ADMIN_TOKEN"

API surface

| Method | Route | Authentication | Purpose | |---|---|---|---| | GET | / | Public | Evidence dashboard | | GET | /health | Public | Runtime and integration status | | GET | /v1/metrics | Public | Aggregate non-secret metrics | | GET | /v1/aifinpay/status | Public | Public agent addresses, funding recommendation and safe balance snapshot | | POST | /v1/visual-objectives | Admin token | Image → Gemini inspection → merchant offers → optional objective execution | | POST | /v1/objectives | Admin token | Create objective | | GET | /v1/objectives/:id | Admin token | Read objective state | | POST | /v1/objectives/:id/run | Admin token | Execute Gemini → policy → payment | | GET | /v1/circle/status | Public | Circle configuration status | | POST | /v1/circle/transfers | Admin token | Explicit capped USDC transfer |

Economics recorded by the service

| Action tier | Price per action | |---|---:| | Standard | $0.0005 | | Complex | $0.002 | | Premium | $0.005 |

Successful AIFP-1 transactions record 99% merchant proceeds and a fixed 1% AiFinPay protocol fee. Failed or blocked actions add zero payment volume. The policy engine rejects any model-generated price mutation.

Documentation

| Document | Purpose | |---|---| | Architecture | Components, trust boundaries, flows, state, deployment and data model | | Advanced commerce | Multimodal procurement, negotiation and self-healing payment execution | | Render deployment | Production Render runtime configuration | | Deployment | Optional Google Cloud, Firestore, Cloud Run and Secret Manager setup | | Security | Supported version, threat controls and private reporting | | Evidence | Hackathon logs, screenshots, transactions and P&L checklist | | Hackathon disclosure | New work versus pre-existing AiFinPay resources | | Contributing | Contribution rules and developer workflow | | Trademark policy | Permitted and prohibited brand use |

License and brand

The repository and npm package are source-available, not open source. The AiFinPay Source-Available License 1.0 permits review, local evaluation, security research, and hackathon judging. It does not permit production or commercial use, resale, redistribution, public derivative products, competing services, model training on the repository, or use of AiFinPay branding without written permission.

Third-party packages remain subject to their own licenses. See NOTICE and TRADEMARKS.md.