Financial intelligence,
made legible.

A better question for business money.

Most financial dashboards answer: How much money do we have? Quorail answers the harder question: What becomes impossible if we spend this money now?

Quorail is a financial consequence engine for small businesses that operate with USDC on Arc. It turns isolated obligations and account balances into a forward-looking model, then uses a bounded reasoning agent to assess whether payments should proceed, be deferred, or be escalated to the owner.

The purpose is to reduce manual treasury busywork without treating an AI model as a financial custodian. The business owns the wallet and spending policy. The agent operates only within those limits.

Intelligence before execution.

The platform uses two deliberately separate systems. An offchain decision engine handles forecasting and alternative evaluation. An onchain treasury vault determines whether the agent actually has the authority to spend.

The agent's decision loop

1. Observe: Query the Arc vault balance and known unpaid commitments.
2. Project: Calculate money already committed within the forecast window and the required reserve.
3. Compare: Calculate what remains after a candidate payment. Produce pay, hold, and escalate alternatives.
4. Reason: Ask the configured Claude model for a decision and concise rationale using only structured treasury facts.
5. Constrain: Apply deterministic cash and policy checks. The model cannot override them.
6. Act: When authorized, submit a unique payment identifier and USDC amount to the Arc vault contract.
7. Prove: Store a confirmed Arc transaction hash and the associated rationale. Fail closed when outcomes are uncertain.

A run can be initiated manually or by a protected scheduled endpoint. A schedule is only a wake-up mechanism; the AI agent performs the decision-making at execution time.

How to use Quorail.

Explore without credentials, or connect the treasury owner wallet

Open the Control Room. Without server configuration it opens in illustrative mode; on a live deployment, the sample dashboard opens without credentials and does not access private treasury data. Example obligations, visualizations, and assessments are stored locally in your browser, and nothing touches a real wallet.

1. Review the operating capital, upcoming commitments, reserve, and discretionary buffer.
2. Open Obligations and create a sample payment commitment.
3. Press Assess demo scenarios to create a rules-based example decision.
4. Open Decision ledger to inspect the recommendation and the alternatives.
5. Visit Policy & trust to understand the spending protections.

Operate a real testnet treasury

Once live mode is configured, click Connect wallet on the landing page and sign a free authentication message. Quorail opens the live dashboard immediately after verification. All obligations are stored in Postgres. The vault balance comes from Arc Testnet RPC, and AI decisions are recorded in the live decision ledger.

Add a real obligation with an authentic due date and an address controlled by its recipient. The vault owner must allowlist that address using an onchain wallet signature. When the agent chooses to pay an eligible small amount, it can send USDC without an owner click. If the payment exceeds the autonomous limit, the owner must sign an exact-payment approval through an EVM wallet.

Go from demonstration to settlement.

Follow the full, copy-and-paste setup in the included repository README. This high-level guide outlines the sequence.

1. Clone and install

git clone https://github.com/paulos-ui/quorail.git
cd quorail
npm install
cp .env.example .env.local
npm run dev

2. Configure persistent state and access

Create a hosted PostgreSQL database (Neon, Supabase Postgres, or similar). Set DATABASE_URL_UNPOOLED (direct Neon connection), SESSION_SECRET, and VAULT_ADDRESS in .env.local. Initialize tables with npm run db:init.

3. Set up the Arc wallet

Create a dedicated agent EVM testnet signer and an independent owner signer. Configure AGENT_PRIVATE_KEY server-side only. The demo execution adapter uses a viem signer; Circle Agent Wallet CLI is also supported as a wallet onboarding/funding workflow, but Circle-hosted signing is not automatically substituted for the viem signer.

npm install -g @circle-fin/cli
circle wallet login you@example.com --testnet
circle wallet list --type agent --chain ARC-TESTNET

Keep one-time passwords private. Fund your signing wallet and future vault with Arc Testnet USDC. Official resources: Circle Faucet and Circle Agent Wallet docs.

4. Deploy a guardrail contract

Set DEPLOYER_PRIVATE_KEY temporarily on your local development machine, configure the three caps and run npm run vault:deploy. Copy the resulting deployed vault address into VAULT_ADDRESS and NEXT_PUBLIC_VAULT_ADDRESS. The owner must use the smart contract's setRecipient(address,bool) method to allow approved recipients and fund the vault with test USDC.

5. Configure AI reasoning

Add an Anthropic API key and a model you have access to. Quorail can analyze obligations with deterministic rules in the absence of a key, but only properly configured LLM decisions can initiate autonomous settlement.

6. Operate and verify

Use the Control Room to add genuine obligations. Trigger a run or configure the protected daily endpoint with CRON_SECRET. Inspect settlement confirmations through the Arc explorer. If a broadcast outcome is ambiguous, investigate the onchain receipt before retrying; Quorail intentionally does not blindly repeat uncertain transfers.

A model cannot grant itself permission.

The owner-controlled QuorailVault.sol contract enforces five independent protections:

• Payments can only be sent by the designated agent signer.
• Only recipient addresses explicitly permitted by the owner can receive funds.
• Payments are restricted by a hard single-payment ceiling and daily spending limit.
• Amounts above the autonomous limit require owner approval of the exact payment identifier, recipient, and amount.
• Every payment ID is permanently marked spent. Replays are rejected onchain.

The owner can pause spending, rotate the agent, change limits, and update recipients. The model and normal agent signer cannot perform those owner functions.

Offchain checks supplement the vault: money is represented as integers rather than floating point, the agent examines competing obligations and reserves, and every decision is attached to a timestamped audit chain. The audit chain is tamper-evident under ordinary application use but is not externally anchored or cryptographically immutable against a database administrator.

Built as reusable infrastructure.

Quorail is a product and also a small set of reusable components other Arc builders can extend. Each part has a clearly defined contract and minimal external coupling.

Consequence Engine

lib/core/finance.ts accepts balance, obligations, candidate payment and policy, returning competing commitments, projected discretionary capital and alternative recommendations. This module has no network dependencies.

Policy Vault

contracts/QuorailVault.sol implements owner-authorized recipient allowlists, daily caps, autonomous payment thresholds, exact-payment approvals and onchain replay protection.

Arc Payment Adapter

lib/server/arc.ts connects to Arc Testnet, verifies network identity, checks USDC balances, reads vault policy and submits payment instructions using viem.

Reasoned Decision & Audit

lib/server/agent.ts composes deterministic consequence models with structured AI decisions. lib/server/db.ts stores the decision and payment trail.

For the Arc Open Source Showcase, the reusable primitives can be split into a standalone package without changing the product logic. Read the repository docs/ARC-OSS-SUBMISSION.md for the proposed OSS submission narrative.

What's working, and what's next.

The repository provides a custom responsive public interface, interactive demonstration, live authenticated treasury workflows, model reasoning integration, onchain policy contract, Arc adapter, persistence, and scripts for testnet deployment. Real operations require the owner's deployment, funding, third-party API credentials, and genuine pilot users. The shipped code alone does not establish business traction or confirm a real transaction has happened.

Planned improvements include independent invoice ingestion and vendor verification, a durable job queue, multicurrency forecasting, richer payment reconciliation, higher-quality forecasts informed by historical data, multi-tenant access control, multisignature owner control, external security review, and optional Circle-hosted wallet signing integration.

Created by Jayking / @paulos-ui. Updates at @__official__1. Built independently for the Canteen × Circle Tameion Agents Hackathon and intended for the Arc Open Source Showcase.

Confirm the settlement, not just the decision.

A live agent cycle can result in pay, hold, or escalate. Only a confirmed Arc receipt proves a payment was settled. The public simulation and its sample balances do not count as transaction or traction evidence.

1. Confirm your deployed vault address locally with npm run vault:status. Make sure it holds testnet ERC-20 USDC and the agent has native Arc Testnet gas.
2. On Vault & access, allowlist a genuine recipient using the owner's wallet signature; verify that transaction on Arcscan.
3. Create an authentic business obligation due today with an amount comfortably below the vault's autonomous limit and within available reserves.
4. Run a single manual agent cycle from Decision ledger. Read the reasoning and its action; a HOLD is a legitimate, useful outcome.
5. For a PAY result, inspect the matching Arcscan transaction hash, its successful status, the vault's PaymentExecuted event, and the ERC-20 transfer amount and recipient.
6. Save the business context, obligation identifier, decision explanation, public transaction URL and exact USDC amount. Do not publish keys, API credentials, invoices containing private details, or customer records.

The repository includes docs/SETTLEMENT-PROOF.md for a more detailed evidence checklist and a blank evidence record. Verified activity by a real business, not a staged counterparty or screenshot, is the basis for claiming hackathon traction.