Интерфейсы агентов BlinkCodes

Машиночитаемые интерфейсы для blinkcodes.com — магазина, продающего коды подарочных карт, пополнения услуг и туристические eSIM, с доставкой по электронной почте за секунды.

Всё здесь — удалённый, размещённый сервис. Нечего устанавливать и не нужно запускать сервер: направьте своего клиента на URL-адреса ниже. Этот репозиторий существует для документирования этих конечных точек, фиксации их схем и предоставления рабочих примеров.

Документы обнаружения: /.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.

MCP-сервер

Опубликован в Официальном реестре MCP как com.blinkcodes/catalog (server.json).

Три инструмента. Два инструмента каталога доступны только для чтения и бесплатны — без ключа, без аккаунта, без оплаты. Третий принимает деньги, и только через x402:

buy_product работает по тому же каналу, что и POST /api/v1/buy ниже — проверка, резервирование, расчёт, выполнение, в таком порядке — поэтому агенту, который нашёл магазин через MCP, никогда не придётся менять протокол для завершения покупки. Первый вызов ничего не списывает, а для использования двух других инструментов кошелёк не нужен.

Добавьте его в клиент, который поддерживает удалённый MCP:

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

Полные схемы инструментов и транскрипт curl: docs/mcp.md.

Клиент, работающий только через stdio, может использовать мост в Dockerfile, который проксирует к той же размещённой конечной точке:

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

Предпочитайте прямой URL выше везде, где ваш клиент поддерживает удалённый MCP — мост добавляет лишний переход и ничего не даёт.

Related MCP server: the402-mcp-server

Покупка для агентов

Оплата — USDC на Base через x402. Одна конечная точка, два прохода:

1. POST /api/v1/buy с телом заказа → 402 с требованиями к оплате, оценёнными для этого конкретного товара, плюс блок order (id, токен доступа, URL статуса).

2. Идентичный запрос с заголовком PAYMENT-SIGNATURE → 200 с кодом, или 202 + status_url, если выполнение выходит за пределы окна синхронизации.

// 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
}

• Сеть eip155:8453, актив 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC).

• x402 v2 по умолчанию; клиенты v1 отправляют X-PAYMENT или запрашивают котировку v1 с X-PAYMENT-VERSION: 1.

• GET /api/v1 бесплатно описывает канал.

• Вызов /api/v1/buy без указания чего-либо отвечает 402 с указанием минимальной суммы канала и не создаёт заказ — это форма проверки, безопасная для краулеров.

Рабочий пример: examples/x402-buy.mjs. Каналы, минимальные суммы и пары оплачиваемых монет: GET /api/public/payment-methods.

A2A

Карточка агента по адресу /.well-known/agent-card.json, JSON-RPC message/send на https://blinkcodes.com/a2a. Навыки — это два инструмента каталога плюс buy_product, который через этот транспорт несёт расширение платежей a2a-x402 (https://github.com/google-a2a/a2a-x402/v0.1, объявлено required: false, потому что навыки каталога бесплатны).

Котировка → Task в состоянии input-required с x402.payment.required; оплата → тот же taskId с x402.payment.payload → Task completed плюс доставка как артефакт. См. examples/a2a.sh.

Документация для людей

Магазин, цены и условия: https://blinkcodes.com. Поддержка: support@blinkcodes.com.

Лицензия

MIT — применимо к документации и примерам в этом репозитории. Сам сервис регулируется условиями, опубликованными на сайте.