Interfaces de agente de BlinkCodes

Interfaces legibles por máquina para blinkcodes.com — una tienda que vende códigos de tarjetas de regalo, recargas de servicios y eSIM de viaje, con entrega por correo electrónico en segundos.

Todo aquí es un servicio remoto y alojado. No hay nada que instalar ni servidor que ejecutar: apunta tu cliente a las URL siguientes. Este repositorio existe para documentar esos endpoints, fijar sus esquemas y ofrecer ejemplos funcionales.

Documentos de descubrimiento: /.well-known/agent-card.json, /.well-known/mcp/server-card.json, /.well-known/api-catalog, /.well-known/agent-skills/index.json, /.well-known/acp.json, /.well-known/ucp.

Servidor MCP

Publicado en el Registro oficial de MCP como com.blinkcodes/catalog (server.json).

Tres herramientas. Las dos herramientas de catálogo son de solo lectura y gratuitas: sin clave, sin cuenta, sin pago. La tercera cobra dinero, y solo a través de x402:

buy_product usa el mismo carril que POST /api/v1/buy a continuación — verificar, reservar, liquidar, cumplir, en ese orden — para que un agente que encontró la tienda a través de MCP nunca tenga que cambiar de protocolo para completar la compra. La primera llamada no cobra nada, y no se necesita cartera para usar las otras dos herramientas.

Añádelo a un cliente que hable MCP remoto:

{
  "mcpServers": {
    "blinkcodes": {
      "type": "http",
      "url": "https://blinkcodes.com/mcp"
    }
  }
}

Esquemas completos de las herramientas y una transcripción curl: docs/mcp.md.

Un cliente solo stdio puede usar el puente en Dockerfile, que hace de proxy al mismo endpoint alojado:

docker build -t blinkcodes-mcp . && docker run -i --rm blinkcodes-mcp

Prefiere la URL directa anterior siempre que tu cliente hable MCP remoto: el puente añade un salto y no compra nada.

Related MCP server: the402-mcp-server

Compra, para agentes

El pago es USDC en Base a través de x402. Un endpoint, dos pasadas:

1. POST /api/v1/buy con el cuerpo del pedido → 402 con los requisitos de pago con precio para ese artículo exacto, más un bloque order (id, token de acceso, URL de estado).

2. La solicitud idéntica con un encabezado PAYMENT-SIGNATURE → 200 con el código, o 202 + status_url si el cumplimiento supera la ventana de sincronización.

// the body, in both passes
{
  "email": "buyer@example.com",
  "product_type": "giftcard",   // giftcard | topup | esim | phone_rental
  "product_id": 187,
  "item_id": 1195,
  "quantity": 1
}

• Red eip155:8453, activo 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC).

• x402 v2 por defecto; los clientes v1 envían X-PAYMENT, o piden una cotización v1 con X-PAYMENT-VERSION: 1.

• GET /api/v1 describe el carril de forma gratuita.

• Llamar a /api/v1/buy sin nada nombrado responde 402 citando el mínimo del carril y no crea ningún pedido: esa es la forma de sonda, segura para rastreadores.

Ejemplo práctico: examples/x402-buy.mjs. Carriles, mínimos y pares de monedas pagables: GET /api/public/payment-methods.

A2A

Tarjeta de agente en /.well-known/agent-card.json, JSON-RPC message/send en https://blinkcodes.com/a2a. Las habilidades son las dos herramientas de catálogo más buy_product, que en este transporte lleva la extensión de pagos a2a-x402 (https://github.com/google-a2a/a2a-x402/v0.1, declarada required: false porque las habilidades de catálogo son gratuitas).

Cotización → Task en input-required con x402.payment.required; pago → mismo taskId con x402.payment.payload → Task completed más la entrega como artefacto. Ver examples/a2a.sh.

Documentación para humanos

Tienda, precios y términos: https://blinkcodes.com. Soporte: support@blinkcodes.com.

Licencia

MIT — se aplica a la documentación y los ejemplos de este repositorio. El servicio en sí se rige por los términos publicados en el sitio.