obol

obol

付钱给摆渡人。通过 x402 提供 Solana Agent 网关。

Obol 是面向 AI Agent 的按次付费 Solana API。无需 API 密钥，无需订阅——Agent 使用 x402 payment protocol 以 USDC 按请求付费。Solana 低于 1 美分的交易成本，让微支付首次变得可行。

名称源自古代硬币：人们将硬币放在死者舌下，作为付给卡戎的渡河船费，让死者得以穿越冥河。这就是最初的微支付。

工作原理

1. Agent 向付费端点请求数据
2. Obol 返回 HTTP 402，并附上付款要求（金额、收款方、网络）
3. Agent 在 Solana 上发送符合付款要求的 USDC
4. Agent 在 X-PAYMENT 标头中附上交易证明并重试
5. Obol 在链上验证付款并返回数据

无需账户。无需代币。无需注册。付款即可使用。

端点

钱包分析

端点	价格	描述
GET /api/v1/wallet/:addr/overview	$0.01	SOL 余额、代币数量、总价值
GET /api/v1/wallet/:addr/portfolio	$0.05	完整持仓，含价格、NFT 和分类明细
GET /api/v1/wallet/:addr/activity	$0.05	分类后的交易历史
GET /api/v1/wallet/:addr/risk	$0.10	多因素风险评估
GET /api/v1/wallet/:addr/pnl	$0.15	代币流向分析、当前价值、盈亏

代币数据

端点	价格	描述
GET /api/v1/token/:mint/price	$0.005	通过 Jupiter 获取实时价格
GET /api/v1/token/:mint/metadata	$0.01	名称、符号、供应量、小数位数

DeFi

端点	价格	描述
GET /api/v1/defi/swap/quote	$0.005	Jupiter 兑换报价及路线规划
POST /api/v1/defi/swap/execute	$0.25	Jupiter 兑换交易构建器
GET /api/v1/defi/positions/:addr	$0.10	DeFi 持仓——LST、LP、借贷
GET /api/v1/defi/lst/yields	$0.02	Solana 上各类 LST 收益率比较

免费

端点	描述
GET /	API 信息和定价
GET /health	服务状态
POST /api/v1/rpc	代理 Helius RPC（允许列表中的方法）

Agent 示例

完整参考实现请参阅 examples/agent-client.ts。核心流程：

import { ObolAgent } from './examples/agent-client';

const agent = new ObolAgent();
await agent.discover();  // fetch pricing
agent.loadWallet(process.env.AGENT_PRIVATE_KEY);

// Auto-discovers price, pays, and returns data
const price = await agent.fetch('/api/v1/token/USDC_MINT/price');

以仅发现模式运行（无需钱包）：

npx tsx examples/agent-client.ts

MCP 服务

Obol 以 MCP 服务形式提供——任何支持 Model Context Protocol 的 AI Agent 都可以原生发现并调用 Obol 的工具。

从 npm 安装

npm install -g obol-mcp

Claude Desktop / Claude Code

添加到 MCP 配置中：

{
  "mcpServers": {
    "obol": {
      "command": "npx",
      "args": ["-y", "obol-mcp"],
      "env": {
        "OBOL_URL": "https://obol-production.up.railway.app"
      }
    }
  }
}

或者在本地开发时：

{
  "mcpServers": {
    "obol": {
      "command": "npx",
      "args": ["tsx", "/path/to/obol/src/mcp.ts"],
      "env": {
        "OBOL_URL": "http://localhost:3000"
      }
    }
  }
}

可用的 MCP 工具

工具	描述
obol_wallet_overview	SOL 余额、代币数量、总价值
obol_wallet_portfolio	完整持仓，含价格和分类明细
obol_wallet_activity	分类后的交易历史
obol_wallet_risk	多因素风险评估
obol_wallet_pnl	代币流向分析和盈亏
obol_token_price	通过 Jupiter 获取实时价格
obol_token_metadata	名称、符号、供应量、小数位数
obol_swap_quote	Jupiter 兑换报价及路由
obol_swap_execute	构建待签名的兑换交易
obol_defi_positions	LST、LP 和借贷持仓
obol_lst_yields	LST 收益率比较
obol_health	API 健康检查（免费）
obol_info	端点定价和信息（免费）

本地运行

npm run mcp

技术栈

• Fastify 5 — 高性能 HTTP
• @x402/svm — Solana 官方 x402 SDK
• Helius — RPC + DAS API
• Jupiter — 代币价格 + 兑换执行
• Upstash Redis — 缓存 + 付款回执
• TypeScript — 完整类型安全
• Zod — 运行时验证

设置

git clone https://github.com/halfkey/obol.git
cd obol
npm install
cp .env.example .env
# Edit .env with your Helius key and merchant wallet address
npm run dev

测试

# Unit + integration tests (46 tests)
npm test -- --run

# Smoke test against live deployment
npx tsx scripts/smoke-test.ts https://obol-production.up.railway.app

# Manual payment test
npx tsx scripts/test-payment.ts <tx-signature>

环境

请参阅 .env.example。关键变量：

• PAYMENT_MODE — mock（开发环境，自动批准）或 onchain（生产环境）
• PAYMENT_RECIPIENT_ADDRESS — 接收 USDC 的 Solana 钱包
• HELIUS_API_KEY — Helius RPC 访问权限
• UPSTASH_REDIS_REST_URL / TOKEN — 缓存层

路线图

• 11 个付费端点（钱包、代币、DeFi、LST、盈亏）
• 链上 USDC 验证，并防止重放
• 测试套件（46 项 vitest 测试 + 20 点冒烟测试）
• Agent 客户端参考实现
• GitHub Actions CI
• 用于钱包监控的 WebSocket 订阅
• 基于拥堵情况的动态定价
• 多链支持

许可证

MIT