BotSupply

npx add-mcp 'https://botsupply.onrender.com/mcp'

BotSupply

Venta al por mayor para agentes de IA. BotSupply es una API de marketplace B2B: un agente abre una billetera, carga créditos prepagados y compra productos JSON.

1 crédito = $0.01 USD. POST /v1/wallets/:id/topup es una recarga gratuita de desarrollo solo cuando STRIPE_SECRET_KEY no está configurado. Cuando STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET y PUBLIC_BASE_URL están todos configurados, esa ruta gratuita devuelve 403 y los agentes pagan con Stripe Checkout.

Agentes que llaman a la API alojada: AGENT_INSTALL.md. Herramientas MCP para el mismo catálogo: MCP_INSTALL.md. Script de demostración público: DEMO.md.

Productos

SKU	Tipo	Créditos	Precio minorista previsto
pack.competitor-snapshot	paquete	50	$0.50
pack.venue-hours	paquete	20	$0.20
recipe.book-table	receta	100	$1.00

pack.competitor-snapshot es un conjunto competitivo de restaurantes informales de Cobble Hill. pack.venue-hours son los horarios semanales y la política de reservas para esos locales. recipe.book-table es una receta de reserva ejecutable que el propio agente ejecuta. Los payloads se entregan al momento de la compra.

Ejecutar localmente

Requiere Node.js 22+.

npm install
npm test
npm run build
npm start

El proceso se vincula a 0.0.0.0 y escucha en PORT, por defecto 4317.

curl -s http://127.0.0.1:4317/health

Abre http://127.0.0.1:4317 para ver la hoja de precios y ejemplos con curl.

npm run dev recarga el servidor TypeScript con tsx.

Datos

SQLite es un único archivo.

1. SQLITE_PATH, si está configurado, se usa tal cual.
2. De lo contrario, el archivo es /data/botsupply.sqlite cuando /data es escribible.
3. De lo contrario, es ./data/botsupply.sqlite.

La base de datos y el catálogo se crean al iniciar. Las billeteras comienzan con 0 créditos.

API

POST /v1/wallets

Abre una billetera. La clave API se devuelve una sola vez.

curl -s -X POST http://127.0.0.1:4317/v1/wallets \
  -H 'content-type: application/json' \
  -d '{"label":"desk-agent"}'

{ "wallet_id": "wal_…", "api_key": "bsk_…", "balance_credits": 0 }

POST /v1/wallets/:id/topup

Recarga de créditos DEV. No se cobra ningún pago. Este es el comportamiento actual solo cuando STRIPE_SECRET_KEY no está configurado (ejecuciones locales y el servicio alojado antes de agregar las claves de Stripe). Después de configurar la clave, la ruta devuelve 403 dev_topup_disabled.

curl -s -X POST http://127.0.0.1:4317/v1/wallets/$WALLET_ID/topup \
  -H 'content-type: application/json' \
  -d '{"credits":500}'

credits es un entero de 1 a 1000000.

POST /v1/wallets/:id/checkout

Recarga de pago. Requiere Authorization: Bearer <api_key> para esa billetera y las tres variables de entorno de Stripe. El cuerpo es { "credits": number } de 100 a 100000. Cada crédito es un artículo de línea de Checkout de 1 centavo (unit_amount 1, cantidad = créditos).

curl -s -X POST "$BASE/v1/wallets/$WALLET_ID/checkout" \
  -H "authorization: Bearer $API_KEY" \
  -H 'content-type: application/json' \
  -d '{"credits":500}'

La respuesta url es https://<host>/v1/pay/s/<session_id>. Abrirla redirige al Checkout alojado y conserva el fragmento # que Stripe requiere. Un id de sesión solo muestra "Este enlace está incompleto". stripe_url es el enlace completo de Checkout.

GET /v1/pay?credits=100 crea una billetera de demostración y redirige a Checkout. Agrega wallet_id para pagar en una billetera existente. Los créditos son de 100 a 100000.

Los créditos se aplican cuando Stripe llama a POST /v1/stripe/webhook con checkout.session.completed y payment_status paid. El mismo id de sesión de Checkout se acredita una sola vez.

Stripe en Render

El servicio en vivo no cobra tarjetas hasta que estas estén configuradas. En el Panel de Render, abre el servicio botsupply, luego Entorno, y agrega:

Clave	Valor
STRIPE_SECRET_KEY	Clave secreta de Stripe (sk_test_… o sk_live_…). No la confirmes en el repositorio.
STRIPE_WEBHOOK_SECRET	Secreto de firma para el endpoint a continuación (whsec_…).
PUBLIC_BASE_URL	https://botsupply.onrender.com

Guarda y vuelve a implementar. En Stripe, agrega un endpoint de webhook https://botsupply.onrender.com/v1/stripe/webhook para el evento checkout.session.completed, luego pega su secreto de firma en STRIPE_WEBHOOK_SECRET.

render.yaml lista los dos secretos con sync: false y establece PUBLIC_BASE_URL. El servicio ya existe, así que completa los secretos en el Panel. Un valor vacío cuenta como no configurado, y la recarga DEV permanece activa hasta que STRIPE_SECRET_KEY no esté vacío. Deja la clave sin configurar para mantener las recargas gratuitas.

GET /v1/catalog

Lista SKUs, precios en créditos y la tarifa minorista prevista. Los payloads de productos no están incluidos.

GET /v1/balance

Requiere Authorization: Bearer <api_key>. Devuelve wallet_id, balance_credits, label y created_at. La clave API no está incluida.

MCP

POST /mcp es un servidor MCP HTTP Streamable sin estado en este mismo proceso. Las herramientas llaman a las rutas anteriores (list_catalog, open_wallet, get_balance, purchase, create_checkout). Pasos de instalación y autenticación: MCP_INSTALL.md.

POST /v1/purchase

Requiere Authorization: Bearer <api_key>. Gasta el precio del SKU y devuelve el payload JSON.

curl -s -X POST http://127.0.0.1:4317/v1/purchase \
  -H "authorization: Bearer $API_KEY" \
  -H 'content-type: application/json' \
  -d '{"sku":"pack.venue-hours"}'

Un saldo insuficiente devuelve 402 y no deduce créditos. Un SKU desconocido devuelve 404. Una clave faltante o desconocida devuelve 401.

GET /v1/purchases/:id

Reproduce una compra para la billetera que la posee. Mismo token de portador que la compra.

GET /health

{ "status": "ok", "service": "botsupply" }

Pruebas

npm test

Cubre la creación de billeteras, la recarga DEV, una compra de cada SKU, la deducción de créditos y la aplicación idempotente de créditos de Stripe. Las pruebas de Checkout usan un cliente Stripe falso y no llaman a la red.

Implementación

Las instrucciones para Docker, Render y Fly.io están en DEPLOY.md.