obol

Paga al barquero. Puerta de enlace de agentes de Solana vía x402.

Obol es una API de Solana de pago por uso para agentes de IA. Sin claves de API, sin suscripciones: los agentes pagan por solicitud en USDC usando el protocolo de pago x402. Los costos de transacción de menos de un centavo de Solana hacen que los micropagos sean viables por primera vez.

Nombrado así por la moneda colocada en la lengua de los muertos para pagar a Caronte por el paso a través del río Estigia. El micropago original.

Cómo funciona

1. El agente solicita datos de un endpoint de pago

2. Obol devuelve HTTP 402 con un requisito de pago (monto, destinatario, red)

3. El agente envía USDC en Solana que coincide con el requisito

4. El agente reintenta con la prueba de transacción en el encabezado X-PAYMENT

5. Obol verifica en cadena y devuelve los datos

Sin cuentas. Sin tokens. Sin registro. Solo paga y listo.

Related MCP server: AgentWallet MCP Server

Endpoints

Análisis de billetera

Datos de tokens

DeFi

Gratis

Ejemplo de agente

Consulta examples/agent-client.ts para una implementación de referencia completa. El flujo clave:

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');

Ejecuta en modo solo descubrimiento (sin necesidad de billetera):

npx tsx examples/agent-client.ts

Servidor MCP

Obol se distribuye como un servidor MCP: cualquier agente de IA que admita el Protocolo de Contexto de Modelo puede descubrir y llamar a las herramientas de Obol de forma nativa.

Instalar desde npm

npm install -g obol-mcp

Claude Desktop / Claude Code

Añade a tu configuración de MCP:

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

O si desarrollas localmente:

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

Herramientas MCP disponibles

Ejecutar localmente

npm run mcp

Stack

• Fastify 5 — HTTP de alto rendimiento

• @x402/svm — SDK oficial de x402 para Solana

• Helius — API RPC + DAS

• Jupiter — precios de tokens + ejecución de swaps

• Upstash Redis — caché + recibos de pago

• TypeScript — seguridad de tipos completa

• Zod — validación en tiempo de ejecución

Configuración

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

Pruebas

# 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>

Entorno

Consulta .env.example. Variables clave:

• PAYMENT_MODE — mock (desarrollo, aprobación automática) o onchain (producción)

• PAYMENT_RECIPIENT_ADDRESS — tu billetera de Solana que recibe USDC

• HELIUS_API_KEY — acceso a RPC de Helius

• UPSTASH_REDIS_REST_URL / TOKEN — capa de caché

Hoja de ruta

• 11 endpoints de pago (wallet, token, DeFi, LST, P&L)

• Verificación de USDC en cadena con prevención de repetición

• Suite de pruebas (46 vitest + prueba de humo de 20 puntos)

• Implementación de referencia del cliente de agente

• GitHub Actions CI

• Suscripciones WebSocket para monitoreo de billetera

• Precios dinámicos basados en congestión

• Soporte multi-cadena

Licencia

MIT