Documentation

Recommended: OKX Agentic Wallet (ARC-TESTNET)

OKX Agentic Wallet is the recommended wallet path for agent-to-agent CiteFlowAI research on Arc Mainnet right now. In mainnet testing, this flow handled the paid research request and unspent-budget refund more cleanly than Circle Agent Wallet's current Gateway-backed agent-wallet flow.

1. Fund the OKX agent wallet with USDC on Arc Testnet.
2. Have the agent call the CiteFlowAI x402 research endpoint with the research question.
3. The endpoint returns an HTTP 402 payment challenge.
4. OKX Agentic Wallet signs and submits the payment.
5. CiteFlowAI runs the research, pays cited creators, and refunds any unspent budget to the paying wallet.

Use the same endpoint shown above:/api/agent/research?q=YOUR_ENCODED_QUESTION. The Circle-onlyrefundAddressparameter is not required for the OKX Agentic Wallet path.

For public mainnet demos, use OKX Agentic Wallet, the direct SDK example, or the MCP integration below. Keep Circle Agent Wallet mainnet tests internal until its Gateway refund/reconciliation path is hardened.

Even easier: MCP integration

If your agent runs on MCP (Claude, Codex, Antigravity, OpenCode, Cursor, or your own agent framework), you don't need to write any x402 signing code at all. We publish a small, self-contained MCP server — mcp-server/ in the CiteFlow repo — that exposes the endpoint as a single tool: citeflow_research. It handles the Gateway deposit, signing, and payment internally; your agent just calls the tool with a question.

Set a longer tool-call timeout.A real call settles an on-chain payment and typically takes 60–100+ seconds. Most MCP clients default to a 60-second tool-call timeout, right at the edge of that, so calls will intermittently fail with a timeout error even though nothing is wrong. Set your client's per-server timeout to at least 3 minutes; the exact field is shown for each client below.

Setup:

git clone https://github.com/vickman787/citeflowAI
cd citeflowAI/mcp-server
npm install
export CITEFLOW_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

Then point your MCP client at it, e.g. in Claude Desktop's config:

{
  "mcpServers": {
    "citeflow": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.mjs"],
      "timeout": 180000,
      "env": {
        "CITEFLOW_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "CITEFLOW_RESEARCH_URL": "https://citeflowai.xyz/api/agent/research"
      }
    }
  }
}

Restart your client and ask it to research something — it calls citeflow_research on its own when relevant.

Works the same with Codex, Antigravity, and OpenCode

Same server, same tool — CLI, IDE extension, or desktop app all work. Only the config format and location differ, since each client is a separate, independently-built product.

Claude Code (CLI or VS Code extension) uses the identical .mcp.json format shown above — same file, same shape, whether it's the desktop app, CLI, or extension.

Codex (CLI or IDE extension) uses TOML at ~/.codex/config.toml:

[mcp_servers.citeflow]
command = "node"
args = ["/absolute/path/to/mcp-server/index.mjs"]
tool_timeout_sec = 180

[mcp_servers.citeflow.env]
CITEFLOW_PRIVATE_KEY = "0xYOUR_PRIVATE_KEY"
CITEFLOW_RESEARCH_URL = "https://citeflowai.xyz/api/agent/research"

Antigravity (desktop app or CLI) uses the same JSON shape as Claude, but config at ~/.gemini/config/mcp_config.json, or workspace-local at .agents/mcp_config.json.

OpenCode (CLI) uses opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "citeflow-research": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp-server/index.mjs"],
      "enabled": true,
      "timeout": 180000,
      "environment": {
        "CITEFLOW_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}