Documentation

1. Connect a Web3 Wallet (No Seed Phrase Needed)

You don't need a crypto extension like MetaMask to use CiteFlowAI. We use Circle's User-Controlled Wallets to generate a secure Web3 wallet bound to your email address, which acts as your universal login!

• Click Connect Wallet in the top navigation bar.
• Enter your email address and verify with the One-Time Password (OTP).
• Create a secure PIN code to authorize future transactions.
• You are now invisibly authenticated to our backend! Your wallet address is your identity.

2. Get Testnet USDC

Since CiteFlowAI currently operates on the Arc Testnet, you need free Testnet USDC to pay for AI prompts.

• Copy your connected wallet address from the top navigation bar.
• Click the blue Droplet Icon in the navigation bar to open the Circle Faucet.
• Paste your address and request USDC on the Arc Testnet.
• Wait a few seconds, and your balance will automatically update in the app!

3. Ask the AI

Once your wallet is funded, you can query the AI. You set a "Max Budget" for the prompt (e.g., $0.50).

• The funds are temporarily authorized using your PIN code.
• The AI retrieves relevant articles from our vector database and writes an answer.
• Based on which articles were actually cited, the smart contract settles the payment, distributing the exact citation fees to the respective authors.

CiteFlowAI can also be called directly by other autonomous agents — no CiteFlow account, API key, or PIN prompt. The/api/agent/researchendpoint speaks the x402 protocol: send a request with no payment and it returns an HTTP 402 challenge; retry with a signed, gasless payment authorization and it settles the payment and returns a grounded, cited answer in one round trip.

Direct SDK requirements

• Any standard EVM keypair — this isn't tied to Circle's wallet product; a plain private key works.
• Testnet USDC and a small amount of native gas on Arc Testnet, free from the Circle Faucet.
• For direct SDK integrations, a one-time on-chain deposit into Circle's Gateway Wallet contract is required. Holding USDC alone isn't enough — it must be deposited into Gateway before any signed authorization can spend it. This step costs gas; every payment after it is gasless. The MCP integration performs this deposit automatically when needed.
• The @circle-fin/x402-batching client library (or any client that implements Circle Gateway's batched signing scheme).

Try it from scratch

A complete, standalone example — no CiteFlow code required. Run these in an empty folder:

mkdir citeflow-test && cd citeflow-test
npm init -y
npm install @circle-fin/x402-batching

Save this as test-x402.mjs in that folder — the .mjs extension runs it as ESM without needing to edit package.json:

import { GatewayClient } from '@circle-fin/x402-batching/client'

const client = new GatewayClient({
  chain: 'arcTestnet',
  privateKey: '0xYOUR_PRIVATE_KEY',
  rpcUrl: 'https://rpc.drpc.testnet.arc.network', // the default RPC is rate-limited
})

await client.deposit('1.00') // one-time, funds your Gateway balance

const { data } = await client.pay(
  'https://citeflowai.xyz/api/agent/research?q=' +
    encodeURIComponent('your research question here')
)

console.log(data.answer)            // grounded, cited answer
console.log(data.purchasedSources)  // which creators just got paid

Replace 0xYOUR_PRIVATE_KEY and 'your research question here' with your own values first — the script will still run and settle payment even if you forget, it just comes back with a response explaining no real question was asked, instead of an error.

Then run it:

node test-x402.mjs

Each call is a fixed $1.00 USDCbudget. Whatever isn't spent on citations is refunded back to the paying wallet — the same refund mechanism used for human researchers. Citation payments to creators are executed exactly as they are for human researchers too, regardless of which side paid.

Circle Agent Wallet

Circle Agent Wallet provides a managed alternative to supplying a raw EVM private key. The Circle CLI logs in the agent wallet, inspects the x402 challenge, checks or funds its Gateway balance, estimates the charge, and pays the same research endpoint after user confirmation.

circle services pay   "https://citeflowai.xyz/api/agent/research?q=YOUR_ENCODED_QUESTION"   --address 0xYOUR_AGENT_WALLET_ADDRESS   --chain ARC-TESTNET   --estimate   --output json

Estimate first and show the price, network, seller, and question before paying. The Agent Wallet must have enough Arc Testnet Gateway balance; a regular wallet balance is not automatically available for x402 payments.