CitePay

CitePay helps AI research tools pay source owners when they cite their work.

Why it exists

AI tools use sources from feeds, blogs, docs, newsletters, and public links. The source owner usually gets no payment path, no usage record, and no claim flow.

CitePay adds a payment and receipt layer at the source/citation boundary. A research product can import sources, map each source to a payee, price citation use, run an agent with a budget, and record what was used, skipped, cached, blocked, or paid.

How it works

1. Import source links from feeds or source records.
2. Map each source to a payee.
3. Mark payout state: registered, claimable, missing wallet, unverified, or test wallet.
4. Set a citation price.
5. Run the research agent with a budget.
6. Record used, skipped, cached, blocked, and paid decisions.
7. Reconcile payment records into the ledger.

What is included

• Feed/source import
• Source pool
• Payee readiness model
• Research-agent run flow
• x402-style paid content endpoint
• Circle/x402 Gateway adapter
• Supabase ledger
• Reconciliation scripts
• Metrics dashboard

Architecture

CitePay is a Next.js App Router app written in TypeScript. The UI is built with Tailwind CSS. Supabase/Postgres stores source records, agent runs, citations, payments, and reconciled Gateway transfers.

Payment support is split into a local simulation rail and a Circle/x402 Gateway rail on Arc Testnet. A local JSON store exists for development only; deployed environments should use Supabase.

Payment modes

PAYMENT_MODE=simulation is the default for local development. It creates deterministic receipts and does not move funds.

PAYMENT_MODE=circle enables the Circle/x402 Gateway path for configured testnet environments. The no-spend smoke check validates configuration, quote generation, and the paid-resource challenge without signing or settling a payment.

The spend path is guarded by explicit environment variables, a selected source, a maximum amount, and a nonce. Gateway transfer history can be reconciled into the Supabase ledger after a payment attempt.

Current testnet evidence

CitePay currently tracks 4 transfer-linked Circle/x402 Gateway Arc Testnet records totaling 0.26 USDC.

These records prove the payment path moved testnet USDC. They are not settled author earnings. Settled author earnings remains 0.00 unless a verified author wallet receives funds.

Local development

npm install
npm run dev
npm run lint
npm run build
npm run smoke:store
npm run smoke:payment

Open http://localhost:3000 after pm run dev`.

Supabase migrations

Existing Supabase deployments should run the current additive migrations before a final demo or release:

1. docs/supabase-agent-decision-status-migration.sql
2. docs/supabase-text-cleanup-migration.sql

The first keeps agent decision statuses aligned with the application. The second cleans public display text columns that may contain mojibake from older imports or seed data.

Environment variables

Use .env.example as the template.

Practical notes:

• .env.local is not committed.
• Supabase service-role keys are server-only.
• CIRCLE_RESOURCE_BASE_URL must match the deployed URL when testing paid resources.
• PAYMENT_SMOKE_SPEND must be unset unless intentionally testing a known owned source.
• ENABLE_AGENT_LIVE_PAYMENTS=false keeps /ask in no-spend decision-preview mode.

Demo workflow

1. Open /feeds.
2. Paste a public feed URL.
3. Preview and import a source.
4. Inspect payee status and payment eligibility.
5. Open /ask and run the agent against the source pool.
6. Review used, skipped, cached, blocked, and paid decisions.
7. Open /metrics to inspect payment evidence and receipt trails.

Current boundaries

CitePay is testnet-first. It does not provide production custody, KYC, or automated ownership verification.

Third-party public sources are blocked for payment unless they are registered or permissioned. Source ownership verification is manual at this stage. The research agent is deterministic so decision behavior is repeatable during testing.

Status

CitePay is an active product experiment for source-level AI payment infrastructure.