SettleFlow

An AI-powered on-chain copilot for secure payments, smart treasury, and seamless financial workflows.

Comment

SettleFlow

About the project

Inspiration

SettleFlow was inspired by a simple problem: freelancers and small businesses often spend too much time chasing payments instead of doing their actual work.

For a Singapore-based freelancer billing an overseas client, the process is fragmented across invoices, emails, spreadsheets, wallet addresses, and payment confirmations. Stablecoins can make cross-border settlement faster and more transparent, but the surrounding invoicing and collections workflow is still largely manual.

We built SettleFlow to make the process feel as simple as writing one sentence:

Collect 100 USDC from Daniel Tan for the website redesign, due in 7 days.

That sentence becomes a structured invoice, a payment link, a QR code, and a customer-facing payment page. Once payment is detected on-chain, the invoice is automatically marked as paid with its transaction hash attached.

What we built

SettleFlow is a full-stack stablecoin invoicing and collections platform for freelancers.

The merchant dashboard helps answer three questions:

  • Who owes me?
  • Who is late?
  • Did the payment arrive?

Key features include:

  • Natural-language invoice creation.
  • Customer directory and customer matching.
  • Sequential invoice numbering.
  • Shareable payment links and QR codes.
  • Public payment pages that require no customer account.
  • USDC payment settlement through a smart contract.
  • Blockchain event scanning and transaction-hash tracking.
  • Pending, paid, and overdue invoice states.
  • Collection analytics and activity timelines.
  • Manual and agent-assisted payment reminders.
  • Email delivery when SMTP is configured, with HTML previews as a safe fallback.
  • Read-only AI assistance for invoice and payment questions.
  • JWT-based merchant authentication.

How we built it

SettleFlow is organized into three main layers.

Frontend

The merchant and payer interfaces are built with:

  • Next.js 14 App Router.
  • TypeScript.
  • Tailwind CSS.
  • TanStack Query.
  • Recharts.
  • wagmi and viem.

The frontend includes dedicated surfaces for the dashboard, invoice list, invoice creation, invoice details, customer management, authentication, and the public /pay/{token} payment page.

Backend

The API is built with:

  • FastAPI.
  • SQLAlchemy.
  • SQLite for the prototype.
  • Optional PostgreSQL support.
  • Pydantic validation.
  • JWT authentication.
  • Optional OpenAI-compatible LLM integration.
  • Jinja2 email templates.

The backend handles customer and invoice management, authentication, natural-language parsing, reminders, activity logging, payment-page data, and blockchain event processing.

Blockchain

The blockchain layer is built with:

  • Solidity.
  • Foundry.
  • An InvoicePaymentRouter contract.
  • A MockUSDC contract.
  • Web3.py.
  • Anvil for local development.

Each invoice receives a deterministic on-chain identifier. When the router emits an InvoicePaid event, the backend matches that event to the corresponding invoice and records the transaction hash.

The prototype can run entirely in demo mode, or connect to a local Anvil chain or a configured testnet environment.

The AI security boundary

A major design principle in SettleFlow is that the AI does not control money.

The model is limited to:

  • Parsing natural-language commands into invoice fields.
  • Answering read-only questions about existing invoices and payments.

The model cannot:

  • Submit blockchain transactions.
  • Send or move funds.
  • Change a confirmed invoice amount.
  • Mark an invoice as paid.
  • Falsify payment status.
  • Independently send collection reminders.

The merchant confirms parsed invoice fields before creation. Payment status changes only through backend logic that observes an on-chain event, or through an explicitly labelled simulation in demo mode.

This separation keeps the convenience of AI while ensuring that financial state is controlled by deterministic application and smart-contract logic.

What we learned

We learned that the most important part of using AI in financial software is not giving the model more authority, but defining its limits clearly.

A natural-language interface makes invoicing much faster, but financial actions require stronger guarantees than a conversational response. Separating parsing from execution allowed us to provide a convenient interface without allowing the model to make financial decisions.

We also learned that both sides of a payment need a focused experience. Merchants need dashboards, reminders, and reconciliation, while customers need a simple payment page that works without an account or Web3 knowledge.

Another important lesson was the value of honest prototype states. SettleFlow distinguishes between:

  • A real email and an email preview.
  • A simulated payment and blockchain-confirmed settlement.
  • A configured blockchain connection and demo mode.
  • A parsed suggestion and a confirmed invoice.

Making these distinctions visible improves trust and makes the prototype easier to evaluate.

Challenges

Natural-language parsing

Commands may omit a customer, amount, currency, description, or due date. We addressed this with structured parsing, validation, confidence values, missing-field reporting, and a confirmation step before invoice creation.

The system also includes a regex-based fallback, so the core demo works without an LLM API key.

Connecting invoices to blockchain payments

Invoice numbers are scoped to individual merchants, so the same invoice number can exist for different users. We derive a unique on-chain identifier from the merchant identity and invoice number to prevent collisions.

Reliable payment status

The frontend has no direct path to mark an invoice as paid. The backend updates payment status from blockchain events and stores the transaction hash. This makes the source of truth explicit and prevents the AI or UI from claiming that a payment arrived without evidence.

Designing for demo and production paths

The prototype supports both a simple demo flow and a real local-chain flow. Without blockchain configuration, payments can be simulated with a clearly labelled demo action. With Anvil and deployed contracts, the flow can execute real local transactions and process emitted events.

Email and reminder workflows

SMTP is optional during development. When it is not configured, SettleFlow renders the invoice or reminder as an HTML preview instead of falsely claiming that an email was delivered. This allowed us to demonstrate the workflow while keeping the system honest.

Payer usability

The payer may have never used SettleFlow or a Web3 application before. We therefore kept the public payment page unauthenticated and focused on the invoice amount, due date, description, merchant, and payment action.

Future direction

Future versions of SettleFlow could include:

  • Automated background blockchain monitoring.
  • Base Sepolia and additional stablecoin support.
  • Wallet connection for customer payments.
  • Production email delivery and scheduled reminders.
  • Multi-user merchant teams and approval workflows.
  • Accounting and spreadsheet integrations.
  • Multi-currency and cross-chain settlement.
  • Stronger dispute and partial-payment handling.
  • Human approval before agent-generated outbound communication.

SettleFlow's goal is to make cross-border stablecoin payments feel as simple as writing one sentence, while keeping settlement transparent, verifiable, and controlled by explicit rules.

Built With

Share this project:

Updates