Obolus

Obolus is a testnet research product that lets AI agents buy creator-owned context, cite it with verified quotes, and pay the creators whose work grounds the answer.

A user asks a question and sets a USDC atom budget. The agent discovers priced assets, decides which assets are worth paying to read, buys selected assets through x402/Circle Gateway on Arc Testnet, synthesizes a grounded answer, verifies quote-level attribution, computes contribution weights in code, and pays citation royalties through the same x402 path.

This repository is a fork of Circle's arc-nanopayments reference app. Obolus keeps the proven x402/Gateway payment path and adds the context-asset registry, pay/skip reasoning, acquire pipeline, attribution gate, royalty settlement, public receipts, creator pages, creator studio, and real-content ingestion.

Links:

• App: https://obolus-web-production.up.railway.app
• Repository: https://github.com/winsznx/obolus
• X: https://x.com/obolusxyz

What Works Now

• Public research front door at / and /research.
• Public demo video page at /demovideo, driven by OBOLUS_DEMO_VIDEO_URL.
• Live run trace: discovery, pay/skip reasons, tolls, synthesis, attribution, royalties, and receipt link.
• Creator studio at /studio for testnet creator onboarding, wallet setup, context-asset registration, and URL ingestion.
• Public receipts at /receipt/[queryId].
• Public creator earning pages at /creator/[wallet].
• Real x402 toll payments and citation-license royalty payments on Arc Testnet using @circle-fin/x402-batching.
• Live Circle Gateway balance display for creators.
• One real Arc Testnet withdrawal proof path for creator earnings.
• Chunked ingestion for long creator-owned articles, briefs, benchmarks, datasets, checklists, transcripts, API results, and security notes.
• A broader context-asset model that is not limited to articles: protocol notes, implementation checklists, benchmark tables, security memos, market/research briefs, community transcripts, API snapshots, and other niche expert material can all be priced if the creator owns the rights.

What This Is Not

• Not mainnet software.
• Not a custody product.
• Not a general web crawler.
• Not a paywall bypass.
• Not a claim that every internet topic is covered. The agent can only answer from registered sources it can discover and afford.

If a query is off-topic for the current corpus, the correct behavior is to skip sources and refuse to synthesize an ungrounded answer.

Product Flow

Judge or Tester

1. Open /.
2. Try an on-topic query for the registered corpus, for example an x402, Gateway, EIP-3009, Arc, or agent-payment question.
3. Watch the live trace. The important artifact is not only the answer; it is the visible decision ledger.
4. Open the receipt and verify:
   • skipped assets include specific reasons;
   • paid assets have toll settlement ids;
   • claims include verbatim supporting quotes;
   • contribution weights produce royalty amounts;
   • creator pages show live Gateway balances and withdrawal proof where available.
5. Try an off-topic query. The correct behavior is to skip irrelevant assets and refuse to synthesize.

Researcher

1. Open /.
2. Enter a question and a budget in USDC atoms.
3. Choose the funding mode:
   • Sponsored testnet mode uses the server-side buyer Gateway wallet.
   • Test wallet mode creates a disposable testnet buyer wallet in the browser and funds/deposits it through the local testnet flow.
4. Watch the live trace.
5. Open the public receipt.

Researchers do not need a wallet in sponsored mode. That is intentional for the hackathon demo: fewer steps creates more real testnet demand. Rate limits and spend caps protect the shared buyer wallet.

Creator

1. Open /studio.
2. Create or connect a testnet creator wallet.
3. Register an owned URL or paste owned content.
4. Set an x402 toll price in USDC atoms.
5. Share /creator/[wallet].
6. Earn:
   • a toll when the source is paid to be read;
   • a royalty when verified claims in an answer are grounded in that source.

Creator ownership is currently cohort/admin/self-attested. Production would require stronger domain or account verification before opening registration broadly.

Why Context Assets Matter

Most AI-agent payment demos stop at "an article costs money." Obolus deliberately treats the paid unit as a context asset, because agents need more than prose:

• a benchmark row can decide which protocol stack an agent chooses;
• a security checklist can stop a bad integration;
• a transcript can preserve hard-to-search community knowledge;
• an API snapshot can document behavior before official docs catch up;
• a niche research brief can make an agent useful in markets that general search does not cover.

The product is reusable only when each asset has four properties: the creator opted in, the free metadata is enough for pay/skip reasoning, the paid content can ground claims, and the receipt can show who got paid.

Architecture Docs

• Architecture
• Adversarial Testing
• Security
• Notice
• License

The in-app reader docs live at /docs.

Local Setup

Requirements:

• Node.js 22+
• npm
• Supabase CLI
• Docker Desktop for local Supabase
• Arc Testnet USDC from the Circle faucet
• Groq API key for the LLM calls used by pay/skip, synthesis, attribution, and ingestion summaries

Install dependencies:

npm install

Create environment:

cp .env.example .env.local

Generate base buyer and seller wallets:

npm run generate-wallets

Start local Supabase:

npx supabase start
npx supabase migration up
npm run sync:supabase-env

Fund the buyer wallet on Arc Testnet through the Circle faucet, then deposit USDC into Gateway using the app or scripts.

Run the app:

npm run dev

Open:

• http://localhost:3000/ for research.
• http://localhost:3000/studio for creator onboarding.
• http://localhost:3000/docs for product docs.

Important Environment Variables

Variable	Scope	Purpose
NEXT_PUBLIC_SUPABASE_URL	Public	Supabase project URL.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Public	Supabase browser key.
SUPABASE_SERVICE_ROLE_KEY	Server only	Server writes for runs, payments, sources, and withdrawals.
BUYER_ADDRESS	Server only	Shared testnet buyer wallet address for sponsored research mode.
BUYER_PRIVATE_KEY	Server only	Signs x402 payment authorizations in sponsored mode. Testnet only.
SELLER_ADDRESS	Server only	Upstream demo seller wallet. Obolus sources use per-source creator wallets.
SELLER_PRIVATE_KEY	Server only	Upstream demo seller key. Testnet only.
GROQ_API_KEY	Server only	LLM calls through the OpenAI-compatible Groq API.
OBOLUS_DEMO_VIDEO_URL	Server/public content	Optional YouTube URL embedded on /demovideo.

Do not commit .env.local.

Railway production should receive the same server-side secrets through Railway variables, not through committed files. Keep BUYER_PRIVATE_KEY, creator private keys, Supabase service-role keys, and GROQ_API_KEY out of Git history.

Scripts

Core checks:

npm run lint
npm run build
npm run obolus:test:attribution

Useful Obolus scripts:

npm run obolus:discover
npm run obolus:plan
npm run obolus:acquire
npm run obolus:synthesize
npm run obolus:settle
npm run obolus:ingest
npm run obolus:gateway-balance
npm run obolus:withdraw-creator

Payment Invariants

• USDC is handled in integer atomic units.
• x402 tolls and royalties both settle through Circle Gateway.
• The model never computes payout amounts.
• Royalty amounts come from server-side persisted contribution weights.
• Quotes must be verbatim substrings of paid source content before a claim can count toward a royalty.
• Payments are idempotent by (query_id, source_id, kind).
• Per-payment and per-run caps are enforced before signing.

Honest Demo Notes

Obolus is strongest when the corpus contains creator-owned, on-topic technical sources. A question like "what do you know about RWA on Mantle" should not pay an x402/EIP-3009 article just because budget is available. It should skip the source, explain why, and avoid inventing an answer.

That behavior is not a failure. It is the product refusing to spend money on irrelevant sources.

License

This fork preserves the upstream Apache 2.0 license. See LICENSE and NOTICE.